citrus-cms/resources/views/guide/blade-caching-system.md

Blade Caching System Implementation Guide

This guide provides a step-by-step explanation of how to implement the Blade View Caching system in DevQMS. This system is designed to improve performance for heavy pages (like complex dashboards, large reports, or data grids) by serving pre-rendered HTML from storage instead of processing PHP/Database queries on every request.

Table of Contents

1. System Overview
2. Related Files
3. Implementation Steps
   • Step 1: Isolate Heavy Logic (No-Cache View)
   • Step 2: Create the Loader View
   • Step 3: Trigger Cache Updates
4. Adding to Default Updates

---

System Overview

The caching mechanism splits a standard Blade view into two parts:

1. Source View (*-no-cache.blade.php): Contains the actual code, queries, and heavy logic. This file is rarely accessed directly by the user.
2. Loader View (*.blade.php): A lightweight file that simply reads the rendered output of the Source View from the file storage.

When data changes in the system, a background job renders the Source View and saves the HTML to the storage folder. The Loader View then serves this static HTML instantly.

Related Files

• app/Functions/cache-blade-load.php: Contains the cacheBladeLoad($cacheName) function used in Loader Views to read from storage.
• app/Functions/cache-blade-views.php: Contains the dispatchCacheBladeViews($views) function used to trigger cache regeneration.
• app/Jobs/CacheBladeViewJob.php: The background job that performs the actual rendering and saving.

---

Implementation Steps

Let's assume you have a heavy report file at: resources/views/reports/monthly-summary.blade.php.

Step 1: Isolate Heavy Logic (No-Cache View)

Rename your existing heavy file by appending -no-cache to the filename.

• Old Path: resources/views/reports/monthly-summary.blade.php
• New Path: resources/views/reports/monthly-summary-no-cache.blade.php

This file keeps all your original logic, loops, and database calls.

Step 2: Create the Loader View

Create a new file with the original filename (monthly-summary.blade.php). This file will act as a proxy.

File: resources/views/reports/monthly-summary.blade.php

@php
    // Define a unique cache key for this view
    // Ideally, use a naming convention related to the file path
    $cacheKey = 'reports-monthly-summary'; 
@endphp

{{-- Load the cached content --}}
{{ cacheBladeLoad($cacheKey) }}

Now, when a user visits the page, they will see the content from the cache.

Step 3: Trigger Cache Updates

Since the Loader View reads static files, it won't show new data automatically. You must trigger a cache refresh when data changes (e.g., after an Excel import, a form submission, or a status change).

Use the dispatchCacheBladeViews helper in your Controller or Service:

// In your Controller
public function updateReportData(Request $request)
{
    // 1. Perform the data update
    // ... code to update database ...

    // 2. Refresh the cache for the report
    dispatchCacheBladeViews([
        [
            'view'  => 'reports.monthly-summary-no-cache', // Dot-notation path to the NO-CACHE file
            'cache' => 'reports-monthly-summary'           // The cache key used in Step 2
        ]
    ]);

    return redirect()->back()->with('success', 'Data updated and cache refreshing...');
}

The system will push a job to the queue. The job will render reports.monthly-summary-no-cache and save the output to storage/app/cache/reports-monthly-summary.blade.php.

---

Adding to Default Updates

If your view is a core part of the system (like a main dashboard) and should be updated with general system events, you can add it to the default list.

1. Open app/Functions/cache-blade-views.php.
2. Locate the $defaultCacheViews array.
3. Add your view configuration:

$defaultCacheViews = [
    // ... existing views ...
    [
        'view' => 'reports.monthly-summary-no-cache',
        'cache' => 'reports-monthly-summary'
    ],
];

Now, whenever any part of the code calls dispatchCacheBladeViews() (without arguments), your report will also be refreshed.