Cache Bundle Laravel Package

Getting Started

This release is a low-risk, additive update: the cache library constraint was bumped and apcu and file stores are now supported alongside the previously available drivers. There are no breaking changes, so an existing install only needs composer update and, if you want the new drivers, a config touch.

1. Update and verify the resolved constraint:

composer update --with-dependencies
composer show <vendor>/<package>   # confirm v1.3.0 and the cache library version

2. Publish/refresh the config if you plan to switch stores (a republished config will overwrite local edits — diff it first):

php artisan vendor:publish --tag=package-config --force

3. Point the package at a store. The new options matter most in two situations:

// config/package.php
'cache' => [
    'store' => env('PACKAGE_CACHE_STORE', 'file'), // now: 'file' | 'apcu' | redis | ...
    'ttl'   => 3600,
    'prefix' => 'pkg',
],

• Single server, no Redis available → file is the pragmatic default. It needs a writable storage/framework/cache and nothing else.
• Single server, latency-sensitive → apcu is the fastest option but lives in shared memory per PHP process/pool.

4. First use case: wrap the expensive read you already have (settings lookup, remote API call, computed report) rather than redesigning anything. Confirm it works end-to-end with php artisan config:clear && php artisan cache:clear, then hit the route twice and check the second request does no I/O.

Where to look first: the package's cache resolver/manager class (the thing that maps your store string to a Illuminate\Contracts\Cache\Repository) if you need to know whether it uses Cache::store() or a custom adapter — this determines whether config/cache.php stores apply or only the package config does.

Implementation Patterns

Define the store once in config/cache.php, reference it by name. Rather than hardcoding file/apcu in the package config, declare a dedicated store so TTLs, prefixes, and serialization are managed in one place:

// config/cache.php
'stores' => [
    'package' => [
        'driver' => env('PACKAGE_CACHE_DRIVER', 'file'),
        'path'   => storage_path('framework/cache/package'),
    ],
],

This makes the driver swap a pure env change between local (file), staging (apcu), and production (redis).

Environment matrix is the main workflow win. Typical split that this release unlocks for teams without Redis everywhere:

Warm the cache in deploy rather than on first request. Add a small artisan command or a php artisan tinker-free hook into your deploy script so the first user after a release doesn't pay the cold-start cost:

// app/Console/Commands/WarmPackageCache.php
public function handle(): void
{
    $this->call('cache:clear');       // only if the payload schema changed
    // iterate the hot keys and re-populate via the package API
}

Invalidate on domain events, not on a timer. If the package caches derived data, hook saved/deleted model events or your domain events to forget the affected keys. With file/apcu you cannot lean on tag flushing, so keep keys derivable and forget them explicitly.

Test against the real driver at least once. Run the suite on array, but add one integration test that boots with file to catch serialization and permission problems that array hides.

Gate the driver per feature if you mix. Nothing stops you from using apcu for hot config and file for larger payloads; the new support makes that a config decision rather than a code change.

Gotchas and Tips

• APCu is disabled on the CLI by default. apc.enable_cli=0 means queue workers, artisan commands, and any CLI-triggered test see an empty (or unavailable) cache while web requests see a warm one. This is the single most common "it works in the browser, not in the job" bug after enabling apcu. Set apc.enable_cli=1 in the CLI ini if you genuinely need it, or keep CLI paths on file.
• APCu is per-process and lost on restart. It is not shared between PHP-FPM pools, not shared across servers, and is wiped by a deploy/php-fpm reload. Never treat it as durable, and never use it behind a load balancer with more than one node.
• APCu requires the extension. Guard the config or fail fast at boot; a missing apcu extension should not surface as a silent cache miss on every request.
• file cache and permissions. The directory must be writable by both the web user and the CLI user (deploy scripts, queue workers). Mixed ownership produces intermittent write failures that look like cache misses. Use a dedicated subdirectory and check it in your deploy smoke test.
• file on shared storage is not a cache. NFS/EFS-backed storage/ gives you cross-node "sharing" with locking and latency problems. If you need multi-node, use Redis — file is a single-host tool.
• No tag support on file/apcu. Cache::tags() will throw or silently degrade depending on the store. Design keys so invalidation is by explicit forget() or a version prefix (pkg:v2:...) that you bump on schema change.
• The constraint bump is the real risk surface. Run composer why <cache-library> and check nothing else pins the old version; a transitive downgrade or a major bump in the cache library can change serialization or TTL semantics even though the package's own API is unchanged.
• Clear config after changing drivers. php artisan config:cache bakes the store name in; a stale cached config is a frequent cause of "I changed the env and nothing happened". Follow any env change with config:clear (or re-run config:cache) and queue:restart for workers.
• Check TTL 0/null semantics per driver. file and apcu handle "forever" differently from Redis; if the package passes your TTL straight through, verify a null TTL doesn't mean "expire immediately" on the new stores.
• Extension points: the store selection is the intended customization seam — prefer overriding the config/resolver binding in a service provider over forking the package, so future constraint bumps stay a one-line composer update.