Model Caching for Laravel

https://github.com/mike-bronner/laravel-model-caching
Admin
Model Caching for Laravel provides automatic, self-invalidating Eloquent model and relationship...
Tokens:84,517
Snippets:583
Trust Score:7.2
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install laravel-model-caching via Composer

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/README.md

Run this command to install the package. The service provider is auto-discovered, so no additional setup is required.

```bash
composer require mike-bronner/laravel-model-caching
```

--------------------------------

### PHP constructor property promotion example

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/AGENTS.md

Use PHP 8 constructor property promotion instead of leaving empty zero-parameter constructors. Example: public function __construct(public GitHub $github) { }.

```PHP
public function __construct(public GitHub $github) { }
```

--------------------------------

### Publish command usage example

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/service-provider-commands.md

Shows how to publish the config file using the modelCache:publish command with the --config flag.

```sh
php artisan modelCache:publish --config   # creates config/laravel-model-caching.php
```

--------------------------------

### Cooldown activation example

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/traits-model-caching.md

Example usage of withCacheCooldownSeconds to activate the model's declared cooldown (300 seconds) or override with a custom duration.

```php
use App\Models\Comment;

// Activate the model's declared cooldown (300 s):
Comment::withCacheCooldownSeconds()->get();

// Or override:
Comment::withCacheCooldownSeconds(30)->get();
```

--------------------------------

### Install AWS SDK via Composer

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/README.md

Install the AWS SDK for PHP if your application does not already require it. This is needed for the DynamoDB cache driver.

```sh
composer require aws/aws-sdk-php
```

--------------------------------

### Subquery usage with joinSub and whereIn

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cached-query-builder.md

Shows how subquery tables are automatically recorded and tagged. Includes a joinSub example and a whereIn with a subquery.

```php
use App\Models\Post;

// Subquery tables are recorded and tagged automatically:
$posts = Post::query()
    ->joinSub(
        Comment::select('post_id')->where('approved', true),
        'approved_comments',
        'approved_comments.post_id',
        '=',
        'posts.id',
    )
    ->select('posts.*')
    ->get();

// whereIn with a subquery:
$ids = Post::select('id')->where('active', true);
$posts = Post::whereIn('id', $ids)->get();
```

--------------------------------

### isCachable() method example

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/traits-caching.md

Checks if a query chain is cachable before executing. If true, the chain will serve from cache on get().

```php
if (Post::where('active', true)->isCachable()) {
    // this chain will serve from cache on get()
}
```

--------------------------------

### Run composer update

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/AGENTS.md

The developer runs this command to install dev tooling and run the Laravel Boost installer. The agent must never run it; instead, tell the developer it needs running and wait for confirmation.

```bash
composer update
```

--------------------------------

### Clear command usage examples

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/service-provider-commands.md

Shows how to flush the entire model cache or a specific model using the modelCache:clear command.

```sh
php artisan modelCache:clear                        # flush the whole model cache
php artisan modelCache:clear --model='App\Models\Post'   # flush one model
```

--------------------------------

### cache() method example: tag-scoped repository

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/traits-caching.md

Creates a tag-scoped cache repository for the Post model using the cache() method. The tags array scopes the returned repository.

```php
$repo = (new Post)->cache(['App\Models\Post']);   // tag-scoped repository
```

--------------------------------

### Real-world example with Post model and cached query

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/README.md

Shows a Post model with relationships and a query that is automatically cached. When a new comment is created, the cache for Post and Comment queries is invalidated automatically.

```php
class Post extends BaseModel
{
    public function comments()
    {
        return $this->hasMany(Comment::class);
    }

    public function tags()
    {
        return $this->belongsToMany(Tag::class);
    }
}

// All cached automatically — the query, the eager loads, everything. 🪄
$posts = Post::with('comments', 'tags')
    ->where('published', true)
    ->latest()
    ->paginate(15);
```

--------------------------------

### flushCache() method examples

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/traits-caching.md

Flushes cache for the Post model. With no tags, it flushes everything tagged for Post; with explicit tags, it flushes only those tags.

```php
(new Post)->flushCache();                    // flush everything tagged for Post
```

```php
(new Post)->flushCache(['genealabs:laravel-model-caching:app-models-post']);
```

--------------------------------

### Set MODEL_CACHE_STORE environment variable

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/README.md

Example of setting the MODEL_CACHE_STORE environment variable to use a dedicated cache store defined in config/cache.php.

```plaintext
MODEL_CACHE_STORE=model-cache
```

--------------------------------

### Cachable::__get() and __set()

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cached-model.md

Magic methods to get and set model attributes.

```APIDOC
## `__get($key): mixed` / `__set($key, $value): void`

### Description
Magic methods to get and set model attributes. These methods are provided by the `ModelCaching` trait.

### Method
`__get` / `__set`

### Parameters
- **$key** (string) - Required - The attribute key.
- **$value** (mixed) - Required for `__set` - The value to set.

### Return Value
`mixed` for `__get`, `void` for `__set`.

### Example
```php
$value = $model->attribute;
$model->attribute = 'new value';
```
```

--------------------------------

### PHP method signature with type hints and return type

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/AGENTS.md

Use explicit return type declarations and type hints for all method parameters. Example: function isAccessible(User $user, ?string $path = null): bool.

```PHP
function isAccessible(User $user, ?string $path = null): bool
```

--------------------------------

### Explicit flush with graceful degradation using withCacheFallback

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/traits-caching.md

Example usage of withCacheFallback to flush the cache with a fallback that swallows the outage. The fallback returns null when the cache is unreachable.

```php
use App\Models\Post;

$post = new Post;
$post->withCacheFallback(
    fn () => $post->flushCache(),
    'cache flush failed',
    fn () => null,                    // swallow the outage
);
```

--------------------------------

### recordSubqueryCallsOf(EloquentBuilder $builder): EloquentBuilder

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cached-query-builder.md

Installs recording macros on the given Eloquent builder for every method in the subquery arguments map that is not already defined as a recording macro. Returns the same builder.

```APIDOC
## recordSubqueryCallsOf(EloquentBuilder $builder): EloquentBuilder

### Description
Installs a recording macro on the Eloquent builder for every method in `$subqueryArguments` that the builder does not already define as a recording macro. Each macro routes its arguments through `recordSubqueryCall()` and then invokes the pre-existing consumer macro or a fallback. Duplicate installation is avoided via a WeakMap.

### Method
`recordSubqueryCallsOf`

### Parameters
- `$builder` (EloquentBuilder) - Required - The Eloquent builder to install recording macros on.

### Returns
`EloquentBuilder` - the same builder.
```

--------------------------------

### Handling cache failures with MODEL_CACHE_FALLBACK_TO_DB

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cached-builder.md

Shows a try/catch around a CachedBuilder get() call. With MODEL_CACHE_FALLBACK_TO_DB=true and a cache outage, the catch branch is never taken for cache connection errors because the query already ran against the database and a warning was logged.

```php
use App\Models\Post;
use Throwable;

$builder = Post::where('active', true);

try {
    $posts = $builder->get();
} catch (Throwable $e) {
    // With MODEL_CACHE_FALLBACK_TO_DB=true and a cache outage, this branch
    // is never taken for cache connection errors — the query already ran
    // against the database and a warning was logged.
    report($e);
}
```

--------------------------------

### get(string $key, array $tags = [], bool $hash = false): mixed

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/model-cache-repository.md

Retrieves a value from the cache using the given key, tags, and optional hashing.

```APIDOC
## get(string $key, array $tags = [], bool $hash = false): mixed

### Description
Reads a value from the cache store, optionally scoped by tags and/or hashed key.

### Method
get

### Signature
```php
public function get(string $key, array $tags = [], bool $hash = false): mixed
```

### Parameters
- `$key` (string) - Required - Logical cache key.
- `$tags` (array) - Optional - Tags to scope the store (native) or to version the key (DynamoDB). Default `[]`.
- `$hash` (bool) - Optional - When `true`, store/read under `sha1($key)`. Default `false`.

### Returns
- `mixed` - The stored value (unserialized) or `null`.
```

--------------------------------

### Activate cool-down from a query

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/resources/boost/guidelines/core.md

Activates the cool-down window from a query. The first call uses the model's default duration; the second overrides it with 30 seconds. A query starts a window only when none is recorded, and does not extend an existing one.

```php
Comment::withCacheCooldownSeconds()->get();
Comment::withCacheCooldownSeconds(30)->get();
```

--------------------------------

### Using ModelCache::runDisabled() to disable caching

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/helper-facade.md

Example of using the ModelCache facade's runDisabled method to run queries without caching. Writes inside runDisabled do not invalidate the cache; invalidate afterwards.

```php
use GeneaLabs\LaravelModelCaching\Facades\ModelCache;

$result = ModelCache::runDisabled(function () {
    return App\Models\Post::all();
});

// Writes inside runDisabled() do NOT invalidate; invalidate afterwards:
ModelCache::runDisabled(fn () => App\Models\Post::query()->update(['status' => 'draft']));
ModelCache::invalidate(App\Models\Post::class);
```

--------------------------------

### Using CachedBuilder with automatic cache flushing

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cached-builder.md

Shows that Post::where() returns a CachedBuilder instance, and that get() serves from cache after the first run. Builder writes like update(), upsert(), and increment() automatically flush the model cache.

```php
use App\Models\Post;

// CachedBuilder is created for you; nothing to instantiate manually.
$builder = Post::where('published', true);     // instanceof CachedBuilder

$posts = $builder->get();                      // served from cache after first run

// Builder writes flush the model cache automatically:
Post::whereKey(1)->update(['title' => 'Hello']);         // flushCacheAfterBuilderWrite('update')
Post::whereKey(2)->upsert(['title' => 'X'], 'id');       // 'upsert'
Post::where('views', 3)->increment('views');             // 'increment'
```

--------------------------------

### Run console commands with vendor/bin/testbench

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/AGENTS.md

Use this command to run console commands in the repository, as there is no artisan file. Testbench boots a skeleton application, so commands report on that application, not a real one.

```bash
vendor/bin/testbench <command>
```

--------------------------------

### Cachable::bootCachable()

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cached-model.md

Static boot hook to initialize the trait.

```APIDOC
## `bootCachable(): void`

### Description
Static boot hook to initialize the trait. This method is provided by the `ModelCaching` trait.

### Method
`bootCachable`

### Parameters
None

### Return Value
`void`

### Example
```php
// Called automatically when the model is booted.
```
```

--------------------------------

### make(): static

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/model-cache-repository.md

Static factory method that resolves the cache repository and store from the container and configuration.

```APIDOC
## make(): static

### Description
Resolves the cache repository and store from the container and configuration, and returns a new static instance.

### Method
make

### Signature
```php
public static function make(): static
```

### Behavior
- Resolves `cache` and `config` from the container.
- Store is determined by config `laravel-model-caching.store` (or the default store).
- Driver is determined by `cache.stores.<name>.driver` (or `cache.default`).
- `usesDynamoDb` is set to `true` when the driver is `dynamodb` or when the repository store is an instance of `DynamoDbStore`.
- Returns `new static($repository, $usesDynamoDb)`.

### Returns
- `static` - A new instance of the repository.
```

--------------------------------

### Run Laravel Pint to fix formatting

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/AGENTS.md

Run this command to fix any formatting issues. Do not use --test; this command directly applies fixes.

```bash
vendor/bin/pint --format agent
```

--------------------------------

### Run test suite and static analysis with composer

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/AGENTS.md

Run the full test suite and PHPStan analysis. composer test requires a reachable Redis on the default port because Redis is the cache store used by the suite.

```bash
composer test
composer analyse
```

--------------------------------

### Run tests with php artisan test

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/AGENTS.md

Run the narrowest set of tests covering the change. Pass a file path or --filter=testName to target specific tests. Use --compact for compact output.

```bash
php artisan test --compact
```

--------------------------------

### Using ModelCache::invalidate() to clear cache

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/helper-facade.md

Example of invalidating cache for one or multiple models. Throws InvalidArgumentException if the model does not use the Cachable trait.

```php
use GeneaLabs\LaravelModelCaching\Facades\ModelCache;

ModelCache::invalidate(App\Models\Post::class);                    // single model
ModelCache::invalidate([App\Models\Post::class, App\Models\Comment::class]); // multiple

try {
    ModelCache::invalidate(App\Models\PlainModel::class);
} catch (InvalidArgumentException $e) {
    // "App\Models\PlainModel does not use the Cachable trait ..."
}
```

--------------------------------

### Basic retrieval with caching

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/traits-buildable.md

Shows common Eloquent queries that are cached transparently, including with(), where(), first(), paginate(), pluck(), count(), exists(), and sum().

```php
use App\Models\Post;

$posts  = Post::with('comments')->where('published', true)->get();   // cached
$first  = Post::where('featured', true)->first();                    // cached
$page   = Post::orderBy('id')->paginate(15);                         // cached, path fixed on hit
$tags   = Post::pluck('tags');                                       // cached
$count  = Post::where('active', true)->count();                      // cached
$any    = Post::where('draft', true)->exists();                      // cached
$total  = Post::sum('views');                                        // cached
```

--------------------------------

### Manual caching without the package

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/README.md

Shows the manual approach using Cache::remember and Cache::forget, which requires tracking cache keys and invalidating them manually.

```php
$posts = Cache::remember('posts:active:page:1', 3600, function () {
    return Post::where('active', true)->with('comments')->paginate();
});

// And in every observer or event listener…
Cache::forget('posts:active:page:1');
// Hope you remembered every key variant! 😅
```

--------------------------------

### Disable model caching in tests

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/README.md

Disables model caching entirely in the test suite by setting the enabled config to false. Place in TestCase setUp() or phpunit.xml.

```php
// In your TestCase setUp() or phpunit.xml
config(['laravel-model-caching.enabled' => false]);
```

--------------------------------

### Run Laravel Pint on dirty files

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/AGENTS.md

Run this command to format modified PHP files before finalizing changes. Use --dirty to only check changed files and --format agent for agent-friendly output.

```bash
vendor/bin/pint --dirty --format agent
```

--------------------------------

### Invalidate cache after runDisabled() closure

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/README.md

After a runDisabled() closure, explicitly invalidate the cache to ensure fresh data. This example shows a write inside the closure and then invalidating the model cache.

```php
ModelCache::runDisabled(fn () => MyModel::whereKey($id)->update($changes));
ModelCache::invalidate(MyModel::class);
```

--------------------------------

### Config file options (config/laravel-model-caching.php)

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/configuration.md

The default configuration array for the package. It defines options for cache prefix, enabled flag, database keying, store, fallback to database, and TTL. The 'enabled' and 'use-database-keying' options default to true via environment variables, while 'store' and 'ttl' default to null. The 'cache-prefix' is read directly from config, not from an env var.

```php
return [
    'cache-prefix' => '',

    'enabled' => env('MODEL_CACHE_ENABLED', true),

    'use-database-keying' => env('MODEL_CACHE_USE_DATABASE_KEYING', true),

    'store' => env('MODEL_CACHE_STORE'),

    'fallback-to-database' => env('MODEL_CACHE_FALLBACK_TO_DB', false),

    'ttl' => env('MODEL_CACHE_TTL'),
];
```

--------------------------------

### make() method signature

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cache-tags.md

Returns the full, de-duplicated tag list. The order covers eager-load relations, primary model tag, join tags, subquery where tags, and pivot entries.

```php
public function make(): array
```

--------------------------------

### Automatic caching with the package

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/README.md

Shows the simple query using the package's trait, where caching and invalidation happen automatically.

```php
// Just query. Caching and invalidation happen automatically. ✨
$posts = Post::where('active', true)->with('comments')->paginate();
```

--------------------------------

### make(array $columns = ["*"], $idColumn = null, string $keyDifferentiator = ""): string

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cache-key.md

Assembles a cache key by concatenating various query components in a specific order. It includes the cache prefix, table slug, model slug, id column, query columns, distinct clause, join clauses, where clauses, group by clauses, having clauses, eager load models, order by clauses, offset/limit clauses, union clauses, bindings slug, deferred callbacks slug, unkeyed query properties slug, key differentiator, and macro key. Throws an UnkeyableValueException if the key contains an unkeyable segment.

```APIDOC
## make(array $columns = ["*"], $idColumn = null, string $keyDifferentiator = ""): string

### Description
Assembles the cache key by concatenating various query components in a specific order. The key includes the cache prefix, table slug, model slug, id column, query columns, distinct clause, join clauses, where clauses, group by clauses, having clauses, eager load models, order by clauses, offset/limit clauses, union clauses, bindings slug, deferred callbacks slug, unkeyed query properties slug, key differentiator, and macro key. Throws an UnkeyableValueException if the key contains an unkeyable segment.

### Method
make

### Signature
public function make(array $columns = ["*"], $idColumn = null, string $keyDifferentiator = "") : string

### Parameters
- **$columns** (array) - Optional - Default: ["*"] - Selected columns; merged into the key when the query has none.
- **$idColumn** (mixed) - Optional - Default: null - Extra id segment appended after the model slug.
- **$keyDifferentiator** (string) - Optional - Default: "" - Caller-supplied suffix before $macroKey (e.g. -paginate_by_15_page_1).

### Throws
- **GeneaLabs\LaravelModelCaching\Exceptions\UnkeyableValueException** - When the key contains an unkeyable marker or binding (condition: a resource, an object whose state is hidden from JSON/serialization and holds a resource, an unserializable object, or an Expression/closure that fails to compile). Thrown once per make(); callers in Caching/CachesOneOrManyThrough/CachesPivotRelationKeys catch it and disable caching for that instance.

### Key Assembly Order
1. getCachePrefix() — genealabs:laravel-model-caching:[connection:][database:][cache-prefix:]
2. getTableSlug() — Str::slug($query->from) + ":", or sub-<sha1> for Expression/derived tables (SQL + from bindings hashed so fromSub(id > 1) and fromSub(id > 2) differ)
3. getModelSlug() — slug of get_class($model)
4. getIdColumn($idColumn) — _{$idColumn} when set
5. getQueryColumns($columns) — _col1_col2… (query columns win over the argument)
6. getDistinctClause() — -distinct/-distinct_c1_c2
7. getJoinClauses() — -join_{type}_{table}_{sha1(wheres)} (+ join bindings slug)
8. getWhereClauses() — segments per where type: Nested/Exists/NotExists (recursive), Column, raw (bindings inlined), In/NotIn/InRaw/NotInRaw (UUID bytes decoded; placeholders substituted with bound values), RowValues, and everything else via type/values clauses
9. getGroupByClauses() — -groupBy_… (+ groupBy bindings slug)
10. getHavingClauses() — -having_… (+ having bindings slug)
11. getWithModels() — -{connection}:{database}:{relation} per eager load, -{relation} when the model has no such method; plus eager-load constraint keys (+sha1(...) for changed state, =sha1(...) for added wheres)
12. getOrderByClauses() — _orderBy_{column}_{direction} / _orderByRaw_{sql}
13. getOffsetClause() / getLimitClause() — -offset_N / -limit_N
14. getUnionClauses() — -union_{all_}sha1(sql+bindings)
15. getBindingsSlug() — Arr::query($model->query()...->getBindings()) with global scopes applied/removed per the without* flags
16. getDeferredCallbacksSlug() — -beforeQuery_sha1(sql+bindings) when beforeQueryCallbacks exist (unkeyable marker when reflection fails)
17. getUnkeyedQueryPropertiesSlug() — -q<sha1> of remaining non-null/non-false query properties (everything except KEYED_QUERY_PROPERTIES and the infrastructure properties), normalized (expressions → SQL, closures → "Closure", builders → SQL+bindings, objects → class name), sorted
18. $keyDifferentiator (caller-supplied, e.g. -count, -first)
19. $macroKey (from the constructor)

Finally, throw_if($this->hasUnkeyableSegment($key), UnkeyableValueException::class) — a key containing the unkeyable marker, or with a binding marked unkeyable, throws.
```

--------------------------------

### Activate cache cool-down with withCacheCooldownSeconds()

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/README.md

Call withCacheCooldownSeconds() in a query to activate the cool-down. Use no argument to use the model's default, or pass a specific duration in seconds. Writes during the cool-down window do not flush the cache.

```php
// Activate using the model's default (300 seconds)
Comment::withCacheCooldownSeconds()->get();

// Or override with a specific duration
Comment::withCacheCooldownSeconds(30)->get();
```

--------------------------------

### Direct CacheKey instantiation and usage

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cache-key.md

Shows direct use of CacheKey to generate a cache key for a query. The constructor takes an array of eager loads, the model, the base query builder, a string, an array, and a boolean. The resulting key includes the connection, database, model, table, and query constraints. Also demonstrates that eager-load constraint variations produce distinct keys.

```php
use GeneaLabs\LaravelModelCaching\CacheKey;
use App\Models\Post;

$builder = Post::where('published', true)->toBase();
$key = (new CacheKey([], new Post, $builder, "", [], false))->make();
// genealabs:laravel-model-caching:mysql:db:app-models-post:posts:-published...

// Eager-load constraint variations produce distinct keys:
$list = Post::with(['comments' => fn ($q) => $q->where('approved', true)]);
$keyWithConstraint = (new CacheKey($list->getEagerLoads(), new Post, $list->toBase(), "", [], false))->make();
```

--------------------------------

### hidesStateFromJson(mixed $value): bool (static)

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cache-key.md

Determines whether an object's state is hidden from JSON serialization. Returns false for non-objects, JsonSerializable, and DateTimeInterface. Otherwise inspects the object's accessible properties and returns true when there are no accessible properties or when any property name starts with a null byte (private/protected). Used to decide whether a binding's string form is a faithful key.

```APIDOC
## hidesStateFromJson(mixed $value): bool (static)

### Description
Determines whether an object's state is hidden from JSON serialization. Returns false for non-objects, JsonSerializable, and DateTimeInterface. Otherwise inspects the object's accessible properties and returns true when there are no accessible properties or when any property name starts with a null byte (private/protected). Used to decide whether a binding's string form is a faithful key.

### Method
hidesStateFromJson

### Signature
public static function hidesStateFromJson(mixed $value) : bool

### Parameters
- **$value** (mixed) - Required - The value to inspect.

### Returns
- **bool** - True if the value is an object that hides state from JSON, false otherwise.
```

--------------------------------

### Handling UnkeyableValueException

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cache-key.md

Shows how to catch UnkeyableValueException when creating a cache key. In normal use, Caching::makeCacheKey() catches this exception and runs the query uncached instead of crashing.

```php
use App\Models\Post;
use GeneaLabs\LaravelModelCaching\Exceptions\UnkeyableValueException;

try {
    $key = (new CacheKey([], new Post, $query->toBase(), "", [], false))->make();
} catch (UnkeyableValueException) {
    // In normal use you never see this: Caching::makeCacheKey() catches it
    // and runs this query uncached instead.
}
```

--------------------------------

### Advanced usage: detection and disabling cache

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cached-model.md

Demonstrates per-query opt-out with disableCache(), block-level opt-out with ModelCache::runDisabled(), manual invalidation with ModelCache::invalidate(), and programmatic inspection with isCachable() and flushCache().

```php
use GeneaLabs\LaravelModelCaching\Facades\ModelCache;
use App\Models\Post;

// Per-query opt-out (only this chain)
$posts = Post::disableCache()->where('active', true)->get();   // scopeDisableCache()

// Block-level opt-out with guaranteed restore
$result = ModelCache::runDisabled(function () {
    return Post::get();          // runs against the database, no cache writes
});
// Invalidate manually after writes made inside runDisabled():
ModelCache::runDisabled(fn () => Post::whereKey(1)->update(['title' => 'New']));
ModelCache::invalidate(Post::class);

// Programmatic inspection
$post = new Post;
if ($post->isCachable()) {
    $post->flushCache();         // generated tags for this model only
}
```

--------------------------------

### Create a Pest test

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/AGENTS.md

Use this artisan command to create a new Pest test. Do not include the test suite directory in the name; use e.g. SomeFeatureTest instead of Feature/SomeFeatureTest.

```bash
php artisan make:test --pest {name}
```

--------------------------------

### __clone method signature

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cached-builder.md

Signature for __clone, which clones the inner builder and reassigns the subquery recorder.

```php
public function __clone(): void
```

--------------------------------

### Publish the config file with artisan modelCache:publish

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/README.md

Run this artisan command to publish the package's config file to config/laravel-model-caching.php.

```sh
php artisan modelCache:publish --config
```

--------------------------------

### CacheTags::__construct

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cache-tags.md

Constructor that initializes the eager-load map, the primary model, and the query builder.

```APIDOC
## CacheTags::__construct

### Description
Initializes the CacheTags instance with the eager-load map, the primary model, and the query builder.

### Method
Constructor

### Signature
```php
public function __construct(array $eagerLoad, $model, $query)
```

### Parameters
- **$eagerLoad** (array) - Required - Eager-load map `[relationName => constraint]`.
- **$model** (mixed) - Required - The primary model instance.
- **$query** (mixed) - Required - The Eloquent or base query builder (can be `null` for tag-only use, e.g. pivot tags).

### Source
`src/CacheTags.php:36`
```

--------------------------------

### touch method signature

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cached-builder.md

Signature for touch, which executes and flushes the cache for 'touch'.

```php
public function touch($column = null): int|false
```

--------------------------------

### fromSub($query, $as): static

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cached-query-builder.md

Records the subquery as a related-where table, then delegates to the parent fromSub method.

```APIDOC
## fromSub($query, $as): static

### Description
Records the subquery as a related-where table (tagged with the querying model's prefix; `fromRaw()` is intentionally not tagged), then calls `parent::fromSub(...)`.

### Method
`fromSub`

### Parameters
- `$query` (mixed) - Required - The subquery builder.
- `$as` (mixed) - Required - The alias.

### Returns
`static`
```

--------------------------------

### Basic usage: using the Cachable trait

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cached-model.md

Shows how to apply the Cachable trait to a base model and configure optional cache properties: cachePrefix, cacheCooldownSeconds, and cacheTtlSeconds.

```php
<?php

namespace App\Models;

use GeneaLabs\LaravelModelCaching\Traits\Cachable;
use Illuminate\Database\Eloquent\Model;

abstract class BaseModel extends Model
{
    use Cachable;
}

class Post extends BaseModel
{
    protected $cachePrefix = 'tenant-123';       // optional per-model prefix
    protected $cacheCooldownSeconds = 300;       // optional cool-down default
    protected $cacheTtlSeconds = 3600;           // optional per-model TTL
}
```

--------------------------------

### Pest TIA baseline commands

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/AGENTS.md

Commands to use the CI baseline for Pest Test Impact Analysis. Run git fetch origin first, then vendor/bin/pest --tia --baselined to use the latest baseline, and --refetch to replace the local graph immediately.

```Shell
git fetch origin
```

```Shell
vendor/bin/pest --tia --baselined
```

```Shell
vendor/bin/pest --tia --baselined --refetch
```

--------------------------------

### Use array cache driver for testing

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/README.md

Configures the array cache driver for testing cache behavior itself. Sets a custom store and points the package to use it.

```php
config(['cache.stores.model-test' => ['driver' => 'array']]);
config(['laravel-model-caching.store' => 'model-test']);
```

--------------------------------

### Custom builder writes and fallback with MODEL_CACHE_FALLBACK_TO_DB

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/traits-caching.md

Shows that builder-level writes (e.g., increment) flush through the same caching engine, and that when MODEL_CACHE_FALLBACK_TO_DB=true and the cache is down, reads log a warning and hit the database without throwing.

```php
use App\Models\Comment;

// Builder-level writes flush through the same engine:
Comment::where('post_id', 1)->increment('likes');          // flushes after increment

// When MODEL_CACHE_FALLBACK_TO_DB=true and the cache is down,
// reads log a warning and hit the database; nothing throws.
$comments = Comment::where('post_id', 1)->get();
```

--------------------------------

### crossJoinSub($query, $as): static

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cached-query-builder.md

Records the subquery table, then delegates to the parent crossJoinSub method.

```APIDOC
## crossJoinSub($query, $as): static

### Description
Records the subquery table, then calls `parent::crossJoinSub(...)`.

### Method
`crossJoinSub`

### Parameters
- `$query` (mixed) - Required - The subquery builder.
- `$as` (mixed) - Required - The alias.

### Returns
`static`
```

--------------------------------

### CacheKey constructor signature

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cache-key.md

Defines the constructor parameters for CacheKey. The $eagerLoad parameter is an array mapping relation names to constraint closures or null. $macroKey is pre-computed from Caching::keyableMacroKey() and appended last. Uses CachePrefixing trait for prefix logic.

```php
public function __construct(
    array $eagerLoad,
    $model,
    $query,
    $macroKey,
    array $withoutGlobalScopes,
    $withoutAllGlobalScopes
)
```

--------------------------------

### Enable graceful fallback via MODEL_CACHE_FALLBACK_TO_DB environment variable

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/README.md

Set MODEL_CACHE_FALLBACK_TO_DB=true to enable graceful fallback. When the cache backend is unavailable, the package logs a warning and queries the database directly instead of throwing an exception.

```plaintext
MODEL_CACHE_FALLBACK_TO_DB=true
```

--------------------------------

### Error handling for faulty pivot configuration

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cached-relations.md

Shows how to handle a cache-flush failure during a pivot sync operation. The write still occurs, but a cache-flush failure with fallback disabled surfaces as an exception, allowing manual recovery via flushCache().

```php
use App\Models\Post;

try {
    $post->tags()->sync([1, 2]);
} catch (\Throwable $e) {
    // The write still happened in traitSync(); a cache-flush failure with
    // fallback disabled would surface here from flushCacheForPivotOperation().
    report($e);
    ($post->getRelated())->flushCache();   // manual recovery
}
```

--------------------------------

### Run tests with Pest directly

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/AGENTS.md

Call the test runner directly with vendor/bin/pest. Accepts the same file path and --filter=testName arguments as php artisan test.

```bash
vendor/bin/pest
```

--------------------------------

### Generate cache tags and TTL with CacheTags

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cache-tags.md

Creates a CacheTags instance from a query builder to generate cache tags for the model and its eager loads, and another instance to retrieve the TTL. The TTL is the minimum of global and model TTLs.

```php
use GeneaLabs\LaravelModelCaching\CacheTags;
use App\Models\Post;

$builder = Post::with('comments.tags')
    ->join('categories', 'categories.id', '=', 'posts.category_id')
    ->where('published', true);

$tags = (new CacheTags($builder->getEagerLoads(), new Post, $builder))->make();
// e.g. ["genealabs:laravel-model-caching:app-models-post",
//        " ...app-models-comment", "...app-models-category", "...posts", ...]

$ttl = (new CacheTags([], new Post, null))->ttl();   // ?int, min of global + model TTLs
```

--------------------------------

### modelCache:publish

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/service-provider-commands.md

Artisan command to publish various assets of the package. Currently only the --config flag publishes anything.

```APIDOC
## modelCache:publish

### Description
Publish various assets of the 'Model Caching for Laravel' package.

### Method
Artisan Command

### Endpoint
`php artisan modelCache:publish`

### Parameters
#### Options
- `--assets` - Optional - Publish assets (currently publishes nothing).
- `--config` - Optional - Publish config file.
- `--views` - Optional - Publish views (currently publishes nothing).
- `--migrations` - Optional - Publish migrations (currently publishes nothing).

### Request Example
```sh
php artisan modelCache:publish --config   # creates config/laravel-model-caching.php
```

### Response
No return value (void).
```

--------------------------------

### Run a single Pest test by filter

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/AGENTS.md

Filter Pest tests by description to run one test while iterating. Replace <test description> with the actual test description.

```bash
vendor/bin/pest --configuration phpunit.xml.dist --filter "<test description>"
```

--------------------------------

### Global cache prefix configuration

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/README.md

Set a global cache prefix in config to isolate cache entries per tenant. This applies to all models using the cache.

```php
'cache-prefix' => 'tenant-123',
```

--------------------------------

### joinSub($query, $as, $first, $operator = null, $second = null, $type = "inner", $where = false): static

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cached-query-builder.md

Records the joined subquery table, then delegates to the parent joinSub method.

```APIDOC
## joinSub($query, $as, $first, $operator = null, $second = null, $type = "inner", $where = false): static

### Description
Records the joined subquery table, then calls `parent::joinSub(...)`.

### Method
`joinSub`

### Parameters
- `$query` (mixed) - Required - The subquery builder.
- `$as` (mixed) - Required - The alias.
- `$first` (mixed) - Required - The first join column.
- `$operator` (mixed) - Optional - The operator.
- `$second` (mixed) - Optional - The second join column.
- `$type` (string) - Optional - The join type, default "inner".
- `$where` (bool) - Optional - Whether it's a where join, default false.

### Returns
`static`
```

--------------------------------

### Cachable::all()

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cached-model.md

Static method to retrieve all models, with caching applied.

```APIDOC
## `all($columns = ['*']): EloquentCollection`

### Description
Static method to retrieve all models, with caching applied. This method is provided by the `ModelCaching` trait.

### Method
`all`

### Parameters
- **$columns** (array) - Optional - The columns to select. Defaults to `['*']`.

### Return Value
`EloquentCollection`

### Example
```php
$posts = Post::all();
```
```

--------------------------------

### Cachable::newEloquentBuilder()

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cached-model.md

Override to return a custom Eloquent builder.

```APIDOC
## `newEloquentBuilder($query): Builder`

### Description
Override to return a custom Eloquent builder. This method is provided by the `ModelCaching` trait.

### Method
`newEloquentBuilder`

### Parameters
- **$query** (mixed) - Required - The query builder instance.

### Return Value
`Builder` - The custom Eloquent builder.

### Example
```php
$builder = $model->newEloquentBuilder($query);
```
```

--------------------------------

### Default config file content (laravel-model-caching.php)

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/README.md

The published config file with default values. The cache-prefix is set directly here, not via an environment variable.

```php
return [
    'cache-prefix'         => '',
    'enabled'              => env('MODEL_CACHE_ENABLED', true),
    'use-database-keying'  => env('MODEL_CACHE_USE_DATABASE_KEYING', true),
    'store'                => env('MODEL_CACHE_STORE'),
    'fallback-to-database' => env('MODEL_CACHE_FALLBACK_TO_DB', false),
];
```

--------------------------------

### CacheTags constructor

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cache-tags.md

Initializes the CacheTags instance with the eager-load map, the primary model, and the query builder. The query can be null for tag-only use, such as pivot tags.

```php
// phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingAnyTypeHint
public function __construct(array $eagerLoad, $model, $query) {
    $this->eagerLoad = $eagerLoad;
    $this->model = $model;
    $this->query = $query;
}
```

--------------------------------

### Cachable::__wakeup()

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cached-model.md

Reinitializes the model after unserialization to keep cache round-trips valid across requests.

```APIDOC
## `__wakeup(): void`

### Description
Reinitializes the model after unserialization. Saves `original`, `attributes`, `relations`, `exists`, and `connection`, runs `$this->__construct()` to rebuild internal state (including the `isCachable` default), restores the saved state, then calls `parent::__wakeup()`. This keeps cache round-trips (values are `serialize()`d by `ModelCacheRepository`) valid across requests.

### Method
`__wakeup`

### Parameters
None

### Return Value
`void`

### Example
```php
$model = unserialize($serialized);
// __wakeup is called automatically
```
```

--------------------------------

### Cachable::__call()

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cached-model.md

Magic method to handle dynamic method calls.

```APIDOC
## `__call($method, $parameters): mixed`

### Description
Magic method to handle dynamic method calls. This method is provided by the `Caching` trait.

### Method
`__call`

### Parameters
- **$method** (string) - Required - The method name.
- **$parameters** (array) - Required - The parameters to pass.

### Return Value
`mixed` - The result of the method call.

### Example
```php
$result = $model->someDynamicMethod($arg);
```
```

--------------------------------

### rightJoinSub($query, $as, $first, $operator = null, $second = null): static

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cached-query-builder.md

Delegates to joinSub with type "right", including recording.

```APIDOC
## rightJoinSub($query, $as, $first, $operator = null, $second = null): static

### Description
Delegates to `$this->joinSub(..., "right")`.

### Method
`rightJoinSub`

### Parameters
- `$query` (mixed) - Required - The subquery builder.
- `$as` (mixed) - Required - The alias.
- `$first` (mixed) - Required - The first join column.
- `$operator` (mixed) - Optional - The operator.
- `$second` (mixed) - Optional - The second join column.

### Returns
`static`
```

--------------------------------

### Run PHPCS over changed files

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/AGENTS.md

Run this command after any change to PHP or Blade code to check for CleanCode standard violations. Fix every violation before reporting work as done.

```bash
vendor/bin/phpcs
```

--------------------------------

### Set global TTL via environment variable

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/README.md

Sets the global cache TTL to 86400 seconds for all cachable models unless overridden. This is an opt-in safety net for data written outside Eloquent.

```bash
MODEL_CACHE_TTL=86400
```

--------------------------------

### ModelCache facade class definition

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/helper-facade.md

The ModelCache facade extends Illuminate\Support\Facades\Facade and returns 'model-cache' as the accessor, proxying Helper methods.

```php
class ModelCache extends Facade
{
    protected static function getFacadeAccessor(): string
    {
        return 'model-cache';
    }
}
```

--------------------------------

### withCacheFallback method signature

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/traits-caching.md

Signature for the withCacheFallback method. Runs the operation, and on cache connection exceptions, logs a warning and runs the fallback if provided, otherwise returns null.

```php
public function withCacheFallback(callable $operation, string $context, ?callable $fallback = null): mixed
```

--------------------------------

### leftJoinSub($query, $as, $first, $operator = null, $second = null): static

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cached-query-builder.md

Delegates to joinSub with type "left", including recording.

```APIDOC
## leftJoinSub($query, $as, $first, $operator = null, $second = null): static

### Description
Delegates to `$this->joinSub($query, $as, $first, $operator, $second, "left")` — recording included.

### Method
`leftJoinSub`

### Parameters
- `$query` (mixed) - Required - The subquery builder.
- `$as` (mixed) - Required - The alias.
- `$first` (mixed) - Required - The first join column.
- `$operator` (mixed) - Optional - The operator.
- `$second` (mixed) - Optional - The second join column.

### Returns
`static`
```

--------------------------------

### Pest TIA baseline storage command

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/AGENTS.md

Command to print where the TIA graph is stored. Never commit the graph or .pest/ directory.

```Shell
vendor/bin/pest --baseline
```

--------------------------------

### ModelCacheRepository Constructor

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/model-cache-repository.md

Constructor accepting the Laravel cache repository and a flag for DynamoDB usage. When true, tag scoping is replaced by namespace versioning.

```php
public function __construct(
    protected Repository $repository,
    protected bool $usesDynamoDb = false,
) {}
```

--------------------------------

### Cachable::cache()

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cached-model.md

Returns a cache factory or repository instance for the model, optionally with tags.

```APIDOC
## `cache(array $tags = []): CacheFactory|CacheRepository`

### Description
Returns a cache factory or repository instance for the model, optionally with tags. This method is provided by the `Caching` trait.

### Method
`cache`

### Parameters
- **$tags** (array) - Optional - An array of cache tags to apply.

### Return Value
`CacheFactory|CacheRepository`

### Example
```php
$cache = $model->cache(['tag1', 'tag2']);
```
```

--------------------------------

### Environment variables for DynamoDB cache store

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/README.md

Set these environment variables to configure the DynamoDB cache store. The store name 'dynamodb-model' must match the store defined in config/cache.php.

```env
MODEL_CACHE_STORE=dynamodb-model
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_DEFAULT_REGION=us-east-1
AWS_DYNAMODB_CACHE_ENDPOINT=
AWS_DYNAMODB_CACHE_TABLE=cache
```

--------------------------------

### getJoinedSubqueryTables(): array

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cached-query-builder.md

Returns the list of table-name strings joined via joinSub-family calls.

```APIDOC
## getJoinedSubqueryTables(): array

### Description
Returns `$this->joinedSubqueryTables` (list of table-name strings joined via `joinSub`-family calls).

### Method
`getJoinedSubqueryTables`

### Returns
`array` - list of table-name strings.
```

--------------------------------

### CachedBuilder constructor signature

Source: https://github.com/mike-bronner/laravel-model-caching/blob/master/_autodocs/api-reference/cached-builder.md

Constructor signature for CachedBuilder. It accepts a QueryBuilder and converts it to a CachedQueryBuilder via CachedQueryBuilder::fromBase().

```php
public function __construct(QueryBuilder $query)
```
Tokens:
Raw