Modularous

Appearance

Per-Module Setup ​

Enable module-route cache for a single Modularous module in four steps: config, entity readiness, repository/controller readiness, and graph rebuild.

Checklist ​

StepActionVerify
1Add cache.modules.{Module} block to app configModularousCache::isEnabled('Module', 'Route', 'counts') returns true
2Confirm entity extends Modularous Model (includes HasCaching)CacheObserver fires on save
3Confirm repository uses CacheableTrait (generated by default)Counts and index respect shouldUseCache
4Rebuild graph + optional warmphp artisan modularous:cache:graph rebuild
5Add dependencies if cross-module invalidation neededEdit related model, confirm dependent route cache clears

Step 1 — Configuration ​

Add to config/modularous.php or config/modularity.php:

php
'cache' => [
    'modules' => [
        'BusinessPackage' => [
            'enabled' => true,
            'ttl' => [
                'counts' => 900,
                'formattedItem' => 1800,
                'formItem' => 900,
            ],
            'routes' => [
                'Package' => [
                    'enabled' => true,
                    'types' => [
                        'counts' => true,
                        'index' => false,
                        'record' => false,
                        'formattedItem' => true,
                        'formItem' => true,
                        'presentationItem' => false,
                    ],
                ],
            ],
        ],
    ],
],

For public CMS pilot routes, enable presentationItem separately (see CMS Public Pages):

php
'PrimaryPage' => [
    'routes' => [
        'Home' => [
            'types' => [
                'presentationItem' => true,
            ],
            'ttl' => [
                'presentationItem' => 900,
            ],
        ],
    ],
],

Start with one pilot route before enabling index on large tables.

See Configuration for TTL hierarchy and env overrides.

Step 2 — Entity and HasCaching ​

Unusualify\Modularous\Entities\Model already includes HasCaching. Any entity that extends it gets cache invalidation automatically — do not re-declare the trait on standard module entities.

php
<?php

namespace Modules\BusinessPackage\Entities;

use Unusualify\Modularous\Entities\Model;

class Package extends Model
{
    // Optional: declare manual dependents
    // public function getCacheDependents(): array { ... }
}

Inherited HasCaching behavior:

  • Uses Cacheable for module/route name resolution
  • Boots CacheObserver via bootHasCaching()
  • Exposes shouldCacheInvalidate(), withoutCacheInvalidation(), preventDependentWarming()

Only override or opt out when needed — e.g. a model that does not extend Modularous Model, or an entity that must skip invalidation for specific saves. Cross-module dependencies still apply to any model whose changes should clear dependent route caches.

Step 3 — Repository and Controller ​

Repository ​

Module repositories generated by Modularous include CacheableTrait, which provides:

  • cacheableCount() for filter badges
  • getPaginator() → cached index when index type enabled
  • getByIdCached() for single records
  • trackCacheRelations (default true) for relation tags

Opt out per request:

php
$repository->withoutCache()->getPaginator(...);
$repository->withoutRelationTracking()->getByIdCached($id);

Controller ​

BaseController descendants use CacheableResponse for:

  • getFormItem() → formItem cache
  • getFormattedIndexItem() → formattedItem cache

No extra wiring required if the module follows standard Modularous scaffolding.

Step 4 — Graph and Warm ​

bash
php artisan modularous:cache:graph rebuild
php artisan modularous:cache:warm BusinessPackage Package --counts --formattedItems
php artisan modularous:cache:stats BusinessPackage

Step 5 — Cross-Module Dependencies ​

When route A displays data from model B (e.g. press release list shows company name), add B to dependencies or ensure B's entity defines getEloquentRelationships() so the graph links them.

Copy patterns from b2press-app/config/modularity.php cache.dependencies block.

User-Aware Repositories ​

If the repository uses CreatorTrait or AssignmentTrait:

  • Keep user_aware: true (default)
  • Do not expect global count warmup to work — counts are per-user
  • Test with multiple admin accounts to confirm isolated cache keys

Disabling Cache Temporarily ​

php
// Single repository chain
$repo->withoutCache()->getById($id);

// Single model save without invalidation storm
$model->withoutCacheInvalidation()->update($attrs);

// Global — .env
MODULAROUS_RESOURCE_CACHE_ENABLED=false

Pilot Recommendation (b2press-cms) ​

For admin panel pilot (Faz 4 in the CMS performance plan):

  1. BusinessPackage + PrimaryPage modules first
  2. Enable counts, formattedItem, formItem only
  3. Keep index and record off until query patterns are stable
  4. Schedule modularous:cache:graph rebuild weekly and warm after content imports

Public CMS pages remain separate — see CMS Public Pages.

See Also ​