Overview

Complete API reference for the Filterable caching system.

HasFilterableCache Trait

All methods available on any class using the HasFilterableCache trait.

cache()

Enable caching with optional TTL.

public function cache(DateTimeInterface|int|null $ttl = null): self

Parameters:

• $ttl - Time to live in seconds or DateTimeInterface instance

Returns: Self for method chaining

Example:

Post::filter()->cache(3600)->get();
Post::filter()->cache(now()->addHour())->get();

---

remember()

Alias for cache() method.

public function remember(DateTimeInterface|int|null $ttl = null): self

Example:

Post::filter()->remember(1800)->get();

---

cacheForever()

Cache results permanently until manually flushed.

public function cacheForever(): self

Returns: Self for method chaining

Example:

Category::filter()->cacheForever()->get();

---

cacheTags()

Set cache tags for organization and bulk invalidation.

public function cacheTags(array $tags): self

Parameters:

• $tags - Array of tag strings

Returns: Self for method chaining

Example:

Post::filter()
    ->cache(3600)
    ->cacheTags(['posts', 'content'])
    ->get();

Warning

Cache tags require Redis or Memcached. Not supported by file/database drivers.

---

scopeByUser()

Scope cache by authenticated user ID.

public function scopeByUser(int|string|null $userId = null): self

Parameters:

• $userId - User ID (defaults to auth()->id())

Returns: Self for method chaining

Example:

// Automatic user ID
Post::filter()
    ->cache(1800)
    ->scopeByUser()
    ->get();

// Explicit user ID
Post::filter()
    ->cache(1800)
    ->scopeByUser(123)
    ->get();

---

scopeByTenant()

Scope cache by tenant ID for multi-tenant applications.

public function scopeByTenant(int|string $tenantId): self

Parameters:

• $tenantId - Tenant identifier

Returns: Self for method chaining

Example:

Post::filter()
    ->cache(3600)
    ->scopeByTenant(tenant()->id)
    ->get();

---

scopeBy()

Add a custom cache scope.

public function scopeBy(string $key, mixed $value): self

Parameters:

• $key - Scope key name
• $value - Scope value

Returns: Self for method chaining

Example:

Post::filter()
    ->cache(3600)
    ->scopeBy('organization', $orgId)
    ->scopeBy('department', $deptId)
    ->get();

---

withScopes()

Set multiple cache scopes at once.

public function withScopes(array $scopes): self

Parameters:

• $scopes - Associative array of scope key-value pairs

Returns: Self for method chaining

Example:

Post::filter()
    ->cache(3600)
    ->withScopes([
        'organization' => $orgId,
        'department' => $deptId,
        'region' => $region,
    ])
    ->get();

---

cacheProfile()

Use a predefined cache profile from configuration.

public function cacheProfile(string $profile): self

Parameters:

• $profile - Profile name from config

Returns: Self for method chaining

Example:

// Uses settings from config/filterable.php profiles
Post::filter()
    ->cacheProfile('heavy_reports')
    ->get();

---

cacheWhen()

Cache only when a condition is true.

public function cacheWhen(bool|callable $condition, DateTimeInterface|int|null $ttl = null): self

Parameters:

• $condition - Boolean or callable returning boolean
• $ttl - Optional TTL override

Returns: Self for method chaining

Example:

// Boolean condition
Post::filter()
    ->cacheWhen(!auth()->user()->isAdmin(), 3600)
    ->get();

// Callable condition
Post::filter()
    ->cacheWhen(fn() => !app()->isLocal(), 1800)
    ->get();

---

cacheUnless()

Cache unless a condition is true (inverse of cacheWhen).

public function cacheUnless(bool|callable $condition, DateTimeInterface|int|null $ttl = null): self

Parameters:

• $condition - Boolean or callable returning boolean
• $ttl - Optional TTL override

Returns: Self for method chaining

Example:

Post::filter()
    ->cacheUnless(request()->has('refresh'), 3600)
    ->get();

---

flushCache()

Flush all cached results for this filterable class.

public function flushCache(): bool

Returns: True if cache was flushed

Example:

$filter = new PostFilter();
$filter->flushCache(); // Flushes all PostFilter caches

---

flushCacheByTags()

Flush cache by specific tags.

public function flushCacheByTags(?array $tags = null): bool

Parameters:

• $tags - Array of tags (defaults to instance tags)

Returns: True if cache was flushed

Example:

$filter = new PostFilter();
$filter->flushCacheByTags(['posts', 'content']);

---

flushCacheByTagsStatic()

Static method to flush cache by tags.

public static function flushCacheByTagsStatic(array $tags): bool

Parameters:

• $tags - Array of tags to flush

Returns: True if cache was flushed

Example:

Post::flushCacheByTagsStatic(['posts']);
PostFilter::flushCacheByTagsStatic(['posts', 'content']);

---

isCachingEnabled()

Check if caching is enabled for this instance.

public function isCachingEnabled(): bool

Returns: True if caching is enabled

Example:

$filter = Post::filter()->cache(3600);
if ($filter->isCachingEnabled()) {
    // Caching is active
}

---

getCacheTtl()

Get the cache TTL setting.

public function getCacheTtl(): DateTimeInterface|int|null

Returns: TTL value or null

---

getCacheTags()

Get the cache tags for this instance.

public function getCacheTags(): array

Returns: Array of cache tags (includes auto-generated class tag)

Example:

$filter = Post::filter()
    ->cacheTags(['posts', 'content']);

$tags = $filter->getCacheTags();
// ['filterable:post_filter', 'posts', 'content']

---

getCacheScopes()

Get the cache scopes for this instance.

public function getCacheScopes(): array

Returns: Array of scope key-value pairs

---

getCacheProfile()

Get the current cache profile name.

public function getCacheProfile(): ?string

Returns: Profile name or null

---

FilterableCacheManager

Singleton cache manager for advanced operations.

getInstance()

Get the singleton instance.

public static function getInstance(): FilterableCacheManager

Example:

$manager = \Kettasoft\Filterable\Caching\FilterableCacheManager::getInstance();

---

put()

Store a value in cache.

public function put(string $key, mixed $value, DateTimeInterface|int|null $ttl = null): bool

Parameters:

• $key - Cache key
• $value - Value to cache
• $ttl - Time to live

Returns: True if successful

---

remember()

Get from cache or execute callback and cache result.

public function remember(string $key, DateTimeInterface|int|null $ttl, callable $callback): mixed

Parameters:

• $key - Cache key
• $ttl - Time to live
• $callback - Callback to execute if cache miss

Returns: Cached or computed value

---

forever()

Cache a value permanently.

public function forever(string $key, mixed $value): bool

---

rememberForever()

Remember forever version of remember().

public function rememberForever(string $key, callable $callback): mixed

---

get()

Retrieve a value from cache.

public function get(string $key, $default = null): mixed

Parameters:

• $key - Cache key
• $default - Default value if not found

Returns: Cached value or default

---

has()

Check if a key exists in cache.

public function has(string $key): bool

---

forget()

Remove a value from cache.

public function forget(string $key): bool

---

flushByTags()

Flush all cache entries with given tags.

public function flushByTags(array $tags): bool

Parameters:

• $tags - Array of tags

Returns: True if successful

Warning

Requires Redis or Memcached cache driver.

---

withTags()

Set tags for the next operation.

public function withTags(array $tags): self

Returns: Self for method chaining

---

addScope()

Add a scope to the cache manager.

public function addScope(string $key, mixed $value): self

---

generateKey()

Generate a cache key with current scopes.

public function generateKey(string $baseKey): string

---

enable() / disable()

Enable or disable caching globally.

public function enable(): self
public function disable(): self

---

isEnabled()

Check if caching is globally enabled.

public function isEnabled(): bool

---

CacheKeyGenerator

Generates deterministic cache keys.

generate()

Generate a cache key for a filterable operation.

public function generate(
    string $filterClass,
    array $filters = [],
    array $providedData = [],
    array $scopes = [],
    ?Builder $query = null
): string

Parameters:

• $filterClass - Filter class name
• $filters - Applied filters
• $providedData - Provided data
• $scopes - Cache scopes
• $query - Optional query builder

Returns: Generated cache key

---

simple()

Generate a simple cache key from components.

public function simple(string ...$components): string

Returns: Generated cache key

---

forUser()

Generate a user-scoped cache key.

public function forUser(string $filterClass, int|string $userId, array $filters = []): string

---

forTenant()

Generate a tenant-scoped cache key.

public function forTenant(string $filterClass, int|string $tenantId, array $filters = []): string

---

Configuration Reference

// config/filterable.php
return [
    'cache' => [
        // Global enable/disable
        'enabled' => env('FILTERABLE_CACHE_ENABLED', true),

        // Cache driver (null = use default)
        'driver' => env('FILTERABLE_CACHE_DRIVER', null),

        // Default TTL in seconds
        'default_ttl' => env('FILTERABLE_CACHE_TTL', 3600),

        // Cache key prefix
        'prefix' => env('FILTERABLE_CACHE_PREFIX', 'filterable'),

        // Cache version (increment to bust all caches)
        'version' => env('FILTERABLE_CACHE_VERSION', 'v1'),

        // Cache profiles
        'profiles' => [
            'profile_name' => [
                'ttl' => 7200,
                'tags' => ['tag1', 'tag2'],
            ],
        ],

        // Auto-invalidation
        'auto_invalidate' => [
            'enabled' => env('FILTERABLE_AUTO_INVALIDATE', false),
            'models' => [
                App\Models\Post::class => ['posts', 'content'],
            ],
        ],

        // Cache tracking
        'tracking' => [
            'enabled' => env('FILTERABLE_CACHE_TRACKING', false),
            'log_channel' => env('FILTERABLE_CACHE_LOG_CHANNEL', 'daily'),
        ],
    ],
];

Environment Variables

# Enable/disable caching
FILTERABLE_CACHE_ENABLED=true

# Cache driver
FILTERABLE_CACHE_DRIVER=redis

# Default TTL (seconds)
FILTERABLE_CACHE_TTL=3600

# Cache key prefix
FILTERABLE_CACHE_PREFIX=filterable

# Cache version
FILTERABLE_CACHE_VERSION=v1

# Auto-invalidation
FILTERABLE_AUTO_INVALIDATE=true

# Cache tracking
FILTERABLE_CACHE_TRACKING=true
FILTERABLE_CACHE_LOG_CHANNEL=daily

Next Steps

• Getting started guide →
• Caching strategies →
• Examples → :::

Contributors: kettasoft

Previous pageMonitoring Cached Items

Next pageExamples