Caching and Performance

TruCMS runs on shared hosting as well as on dedicated servers, so a plugin must be fast without help from a cache and correct when a cache is switched on. This page shows both sides.

The caches at a glance

The response cache

The response cache stores rendered pages and serves them without running controllers. It ships switched off (RESPONSE_CACHE_ENABLED=false); a site owner turns it on in Settings → Cache. Never assume it is on, and never assume it is off.

What is cached

Only routes that carry the doCache middleware are candidates. Core uses it on the public front routes and the {slug} resolver; Booking on its public catalogue; TruCommerce on the shop and product pages. On top of that, App\Services\ResponseCache\CacheProfile decides per request:

• Only successful GET responses with a text/html content type are stored. JSON and XHR requests never are.
• A request that carries flash data (validation errors, old input, status messages) is neither served from nor written to the cache.
• Guests share one copy per page. A signed-in user gets a private copy keyed by their id and updated_at, with a shorter lifetime (RESPONSE_CACHE_AUTHENTICATED_LIFETIME, 15 minutes).
• Pages with a query string live briefly (RESPONSE_CACHE_QUERY_LIFETIME). Free-text search parameters (q, s, search, query) are never cached; tracking parameters (utm_*, gclid, fbclid) are ignored.
• The cookie-consent and announcement banners are rendered on the server, so whether those cookies are present is part of the key.
• Entries live in their own responsecache store, so clearing them never wipes rate limiters or locks.

Opt a plugin route in

Modules/Testimonials/routes/front.php

Route::get('/', [TestimonialController::class, 'index'])
    ->middleware('doCache')
    ->name('index');

Route::post('/', [TestimonialController::class, 'store'])    // never on a write route
    ->name('store');

Add doCache only to pages that look the same for every guest. Leave it off account pages, carts, checkouts, wizards, forms that show per-visitor state, and anything that changes data.

Pages with personal data

Sometimes a cacheable page shows something personal only in certain cases. Tell the profile from the code that adds that data:

use App\Services\ResponseCache\CacheProfile;

// This response belongs to one visitor: render it, never store it.
CacheProfile::keepOutOfCache();

// This page records or shows per-user state: cache it for guests, never for signed-in users.
request()->attributes->set(CacheProfile::GUESTS_ONLY, true);

TruCommerce's product page uses GUESTS_ONLY because it records the signed-in customer's visit. Booking's MyBookings component keeps any page it appears on out of the cache entirely.

Small per-visitor fragments

A cached page can still contain a fresh CSRF token or a fresh cart badge, because replacers rewrite marked fragments when a cached copy is served. The core uses CsrfTokenReplacer and StripCookiesReplacer; TruCommerce adds its CartFragmentReplacer from its provider's register() by appending to config('responsecache.replacers'). Follow that pattern only for tiny fragments that every page shares; for anything larger, keep the page out of the cache.

Invalidation: keep cached pages true

Models that extend BaseModel

App\Models\BaseModel uses the ClearCache trait. On created, updated and deleted it forgets the model's cache keys and flushes the response cache. You get this for free. Override two methods when you need to:

class Testimonial extends BaseModel
{
    /** Extra keys to forget when a testimonial changes. */
    protected function cacheKeys(): array
    {
        return ['testimonials:published', 'testimonials:count'];
    }

    /** Return false when changes never affect what visitors see (counters, audit fields). */
    protected function shouldClearResponseCache(): bool
    {
        return true;
    }
}

Any other model

For models that do not extend BaseModel (translation models, pivot models, other modules' models, media), register them once in boot():

use App\Services\ResponseCache\ResponseCacheInvalidator;

ResponseCacheInvalidator::flushWhenChanged([
    TestimonialTranslation::class,
    config('media-library.media_model'),     // the configured media class, not Spatie's base class
]);

• Eloquent events fire per concrete class. Register the exact class that is saved: the configured media model, and subclasses such as Booking's Staff rather than their parent.
• Translation rows are separate models. Editing only the Arabic title saves a translation model, not the parent, so register those too. Booking's registerReferenceCacheInvalidation() lists every translation model for this reason.
• Data written with the query builder (DB::table(), mass update()) fires no model events. Call ResponseCacheInvalidator::flush() yourself afterwards.
• Settings saved through a settings screen already flush the response cache. If you write settings in your own code, flush after Setting::save().

Your own data caches

For heavy reference data, use a versioned key instead of hunting down every cached variant. Booking (BookingReferenceCache) and TruCommerce (StorefrontReferenceCache) do this:

final class TestimonialCache
{
    private const VERSION_KEY = 'testimonials:cache-version';

    public function remember(string $name, Closure $callback): mixed
    {
        $version = (int) Cache::get(self::VERSION_KEY, 1);

        return Cache::remember("testimonials:{$version}:{$name}", now()->addHour(), $callback);
    }

    public function flush(): void
    {
        Cache::forever(self::VERSION_KEY, (int) Cache::get(self::VERSION_KEY, 1) + 1);
    }
}

Old entries simply expire. Call flush() from the same model events that flush the response cache.

Habits that keep every request fast

Your provider runs on every request, including those served from the response cache's miss path, admin AJAX calls and Artisan commands. The cheapest code is code that does not run.

1. Build settings pages lazily. Pass 'pages' => fn (): array => [...] to SettingsManager::add(). Building field definitions eagerly cost the core about 30 ms of an 80 ms admin request before it was made lazy.
2. No queries in register() or boot(). Register class names and closures; resolve data when a page, widget or shortcode actually renders.
3. Admin-only work goes on AdminBooting. Sidebar items, settings sections and menu-builder sources are never built for public visitors.
4. Eager-load what you render. Lists of translatable records need with('translations'); lists with images need the media relation.
5. Load assets only where they are used. Shortcode assets declared on the definition are loaded only on pages that contain the shortcode.
6. Use async dashboard widgets for anything that runs aggregate queries.

Testing cache behaviour

The test environment disables the response cache (RESPONSE_CACHE_ENABLED=false) and uses the array store. Turn it on inside a test to check your rules; tests/Pest.php has helpers for this.

it('serves the testimonials page from the cache and refreshes it after a change', function (): void {
    config([
        'responsecache.enabled' => true,
        'responsecache.cache.store' => 'array',
        'responsecache.debug.enabled' => true,     // adds the X-Cache-Status header
    ]);

    $this->get(route('testimonials.index'));                                     // MISS, stored
    expect(cacheStatus($this->get(route('testimonials.index'))))->toBe('HIT');

    Testimonial::factory()->create(['author_name' => 'Grace Hopper']);       // flushes

    nextVisitor($this)->get(route('testimonials.index'))->assertSee('Grace Hopper');
});

cacheStatus() reads the X-Cache-Status header, cachedResponses() lists what the array store holds, and nextVisitor() starts a fresh session so one test can act as several visitors.