Cache Strategy

Configure response caching with Redis, database, or any Laravel cache store

The Rest Generic Class package implements a store-agnostic cache strategy using Laravel’s native cache system. This allows you to use Redis, database, file, Memcached, or any other Laravel-supported cache driver without code changes.

How Cache Works

Cache is applied in BaseService for read operations:

• list_all - Caches paginated list responses
• get_one - Caches individual resource responses

Write operations (create, update, destroy, destroybyid) automatically invalidate the cache by bumping a model-level cache version.

Cache Key Fingerprint

The cache key is built from multiple factors to ensure correct cache isolation:

Factor	Purpose
Model class	Separate cache per resource type
Operation	Different keys for list_all vs get_one
Route/path	Different endpoints get different cache
Query parameters	Different filters/selects/relations get different cache
Authenticated user	User-specific data gets user-specific cache
Request headers	Multi-tenant and locale-aware caching
Model cache version	Automatic invalidation on writes

This prevents cache pollution where one query’s results might incorrectly serve another query.

Enabling Cache

1. Configure Environment

Set these variables in your .env file:

REST_CACHE_ENABLED=true
REST_CACHE_STORE=redis
REST_CACHE_TTL=60

Cache is disabled by default (REST_CACHE_ENABLED=false). You must explicitly enable it.

2. Select Cache Store

The REST_CACHE_STORE variable accepts any Laravel cache driver:

Redis

REST_CACHE_STORE=redis

The array store only persists cache for the current request lifecycle. Don’t use it in production.

3. Configure Store in Laravel

Ensure your selected cache store is properly configured in config/cache.php:

'stores' => [
    'redis' => [
        'driver' => 'redis',
        'connection' => 'cache',
        'lock_connection' => 'default',
    ],
    'database' => [
        'driver' => 'database',
        'table' => 'cache',
        'connection' => null,
        'lock_connection' => null,
    ],
    // ...
],

For database caching, run the migration:

php artisan cache:table
php artisan migrate

TTL Configuration

Default TTL

Set a baseline TTL for all cached responses:

REST_CACHE_TTL=60

Method-Specific TTLs

Override TTL for specific operations:

REST_CACHE_TTL_LIST=300    # 5 minutes for list endpoints
REST_CACHE_TTL_ONE=600     # 10 minutes for single-item reads

Configuration structure:

'cache' => [
    'ttl' => (int)env('REST_CACHE_TTL', 60),
    'ttl_by_method' => [
        'list_all' => (int)env('REST_CACHE_TTL_LIST', 60),
        'get_one' => (int)env('REST_CACHE_TTL_ONE', 30),
    ],
],

TTL Strategy Recommendations

Data Type	Recommended TTL	Reason
Frequently updated	30-60 seconds	Balance freshness and performance
Moderately updated	5-15 minutes	Reduce database load significantly
Rarely updated	30-60 minutes	Maximize cache hit rate
Static/reference data	1-24 hours	Near-permanent caching

List endpoints (list_all) often have shorter TTLs than single-item reads (get_one) because lists change more frequently when new items are added.

Per-Request Cache Control

Clients can control caching behavior on individual requests using query parameters.

Disable Cache for One Request

GET /api/v1/products?cache=false

This bypasses the cache entirely and always queries fresh data from the database.

Override TTL for One Request

GET /api/v1/products?cache_ttl=120

This caches the response for 120 seconds, overriding the configured TTL.

Combined Example

GET /api/v1/products?select=["id","name"]&cache_ttl=300

Cache this specific query shape for 5 minutes.

Per-request cache control is useful for debugging and special cases, but shouldn’t be relied upon for normal operation. Configure appropriate default TTLs instead.

Multi-Tenant and Locale Awareness

Vary by Headers

By default, cache keys vary by specific request headers to prevent cross-tenant or cross-locale data leaks:

'cache' => [
    'vary' => [
        'headers' => ['Accept-Language', 'X-Tenant-Id'],
    ],
],

How it works:

• Request with Accept-Language: en gets a different cache key than Accept-Language: es
• Request with X-Tenant-Id: tenant-a gets a different cache key than X-Tenant-Id: tenant-b

Customizing Vary Headers

If your application uses different headers for tenant identification, update the configuration:

'cache' => [
    'vary' => [
        'headers' => [
            'Accept-Language',
            'X-Organization-Id',  // Custom tenant header
            'X-Client-Version',    // Version-specific caching
        ],
    ],
],

Security critical: If your application is multi-tenant, ensure your tenant identification header is listed in cache.vary.headers. Otherwise, users may see cached data from other tenants.

Cache Invalidation

Automatic Version-Based Invalidation

The package uses a model-level cache versioning strategy:

1. Each model has a version key stored in cache (e.g., cache_version:products)
2. Every cache key includes the current model version
3. On write operations (create, update, destroy), the version is bumped
4. Existing cache keys become stale automatically without explicit deletion

Example flow:

1. GET /products → Cache key: products:v1:list:...
2. POST /products (create) → Bump version to v2
3. GET /products → Cache key: products:v2:list:... (cache miss, queries DB)

Manual Cache Clearing

Clear all application cache:

php artisan cache:clear

Clear cache for a specific store:

php artisan cache:clear --store=redis

You rarely need to manually clear cache because version-based invalidation handles writes automatically.

Cache Without Tags Support

The package’s version-based invalidation strategy works with all cache stores, including those that don’t support tags (like file, database, memcached).

This is more flexible than tag-based invalidation, which only works with Redis and a few other stores.

Example Configurations

High-Traffic Production (Redis)

REST_CACHE_ENABLED=true
REST_CACHE_STORE=redis
REST_CACHE_TTL=300
REST_CACHE_TTL_LIST=300
REST_CACHE_TTL_ONE=600

Best for: APIs with heavy read traffic and moderate write traffic

Simple Staging (File)

REST_CACHE_ENABLED=true
REST_CACHE_STORE=file
REST_CACHE_TTL=120
REST_CACHE_TTL_LIST=120
REST_CACHE_TTL_ONE=180

Best for: Staging environments without Redis infrastructure

Distributed Applications (Database)

REST_CACHE_ENABLED=true
REST_CACHE_STORE=database
REST_CACHE_TTL=180
REST_CACHE_TTL_LIST=180
REST_CACHE_TTL_ONE=300

Best for: Multi-server setups sharing a database but without Redis

Development (Disabled)

REST_CACHE_ENABLED=false

Best for: Local development where you always want fresh data

Monitoring Cache Performance

Track these metrics to optimize your cache configuration:

Metric	Target	Action if Below Target
Cache hit rate	> 80%	Increase TTL
Average response time	< 100ms	Enable caching or increase TTL
Cache memory usage	< 80% capacity	Reduce TTL or add more cache capacity
Database query count	Significant reduction	Cache is working well

Troubleshooting

Cache Not Working

Verify cache is enabled

Check that REST_CACHE_ENABLED=true in .env and configuration is not cached with old values.

php artisan config:clear
php artisan config:cache

Check cache store configuration

Ensure the store specified in REST_CACHE_STORE exists in config/cache.php and is properly configured.

For Redis, verify connection:

php artisan tinker
>>> Cache::store('redis')->get('test')

Verify cache permissions (file store)

If using file cache, ensure storage/framework/cache is writable:

chmod -R 775 storage/framework/cache

Cache Serving Stale Data

If cache persists after updates, check:

1. Version bump logic - Ensure write operations are using BaseService methods
2. Custom write logic - If you bypass BaseService, manually bump the cache version
3. TTL too long - Reduce TTL if data staleness is unacceptable

Related Topics

Environment Variables

Complete reference of cache-related environment variables

Validation Cache

Configure caching for validation queries