README

The Cache package provides an integration with Stash for caching the results of expensive tasks.

Installation

composer require charcoal/cache

For Charcoal projects, the service provider can be registered from your configuration file:

{
    "service_providers": {
        "charcoal/cache/service-provider/cache": {}
    }
}

Overview

Service Provider

Parameters

cache/available-drivers: Collection of registered cache drivers that are supported by this system (via Stash\DriverList).

Services

cache/config: Configuration object for the caching service.
See Pool Configuration for available options.
cache/drivers: Collection of cache driver instances (as a service container) which uses cache/available-drivers.
These drivers are pre-configured:
- file: FileSystem
- db: SQLite
- apc: APC
- memcache: Memcached
- redis: Redis
- memory: Ephemeral (Runtime Only)
- noop: Blackhole (NULL caching driver)
cache/builder: Instance of CacheBuilder that is used to build a cache pool.
cache/driver: Reference to the Stash cache driver used by cache. Defaults to "memory".
cache: Main instance of the Stash cache pool which uses cache/driver and cache/config.prefix.

Configuration

Pool Configuration

Each pool comes with a set of default options which can be individually overridden.

Setting	Type	Default	Description
active	`boolean`	`TRUE`	Whether to enable or disable the cache service.
prefix	`string`	`charcoal`	Name of the main Stash pool.
types	`string[]`	`memory`	List of cache drivers to choose from for the main Stash pool. Defaults to "memory".
default_ttl	`integer`	1 week	Default time-to-live (in seconds) for a cached item. Currently, only used by the APC driver (`cache/drivers.apc`).

use Charcoal\Cache\CacheConfig;
use Charcoal\Cache\ServiceProvider\CacheServiceProvider;

$container->register(new CacheServiceProvider());

$container['cache/config'] = new CacheConfig([
    'prefix' => 'foobar',
    'types'  => [ 'apc', 'memcache', 'redis' ],
]);

Driver Configuration

~~Each driver comes with a set of default options which can be individually overridden.~~

—N/A—

Usage

Just fetch the default cache pool service:

$pool = $this->container->get('cache');

Or a custom-defined cache pool:

// Create a Stash pool with the Memcached driver and a custom namespace.
$pool1 = $this->container->get('cache/builder')->build('memcache', 'altcache');

// Create a custom Stash pool with the FileSystem driver and custom features.
$pool2 = $this->container->get('cache/builder')->build('file', [
    'namespace'  => 'mycache',
    'logger'     => $this->container->get('logger.custom_logger'),
    'pool_class' => \MyApp\Cache\Pool::class,
    'item_class' => \MyApp\Cache\Item::class,
]);

// Create a Stash pool with the "memory" cache driver.
$pool3 = new \Stash\Pool($container['cache/drivers']['memory']);

Then you can use the cache service directly:

// Get a Stash object from the cache pool.
$item = $pool->getItem("/user/{$userId}/info");

// Get the data from it, if any happens to be there.
$userInfo = $item->get();

// Check to see if the cache missed, which could mean that it either
// didn't exist or was stale.
if ($item->isMiss()) {
    // Run the relatively expensive code.
    $userInfo = loadUserInfoFromDatabase($userId);

    // Set the new value in $item.
    $item->set($userInfo);

    // Store the expensive code so the next time it doesn't miss.
    $pool->save($item);
}

return $userInfo;

See the Stash documentation for more information on using the cache service.

Middleware

The CacheMiddleware is available for PSR-7 applications that support middleware. The middleware saves the HTTP response body and headers into a PSR-6 cache pool and returns that cached response if still valid.

If you are using charcoal/app, you can add the middleware via the application configset:

"middlewares": {
    "charcoal/cache/middleware/cache": {
        "active": true,
        "methods": [ "GET", "HEAD" ]
    }
}

Otherwise, with Slim, for example:

use Charcoal\Cache\Middleware\CacheMiddleware;
use Slim\App;
use Stash\Pool;

$app = new App();

// Register middleware
$app->add(new CacheMiddleware([
    'cache'   => new Pool(),
    'methods' => [ 'GET', 'HEAD' ],
]));

The middleware comes with a set of default options which can be individually overridden.

Setting	Type	Default	Description
active	`boolean`	`FALSE`	Whether to enable or disable the middleware (charcoal/app only).
cache	`CacheItemPoolInterface`	`cache`	Required; The main Stash pool.
ttl	`string[]`	1 week	Time-to-live (in seconds) for a cached response.
methods	`string[]`	`GET`	Accepted HTTP method(s) to cache the response.
status_codes	`integer[]`	200	Accepted HTTP status code(s) to cache the response.
included_path	`string[]`	`*`	Accepted URI paths for caching the response.
excluded_path	`string[]`	`^/admin\b`	Rejected URI paths for caching the response.
included_query	`string[]`	`NULL`	Accepted query parameters for caching the response.
excluded_query	`string[]`	`NULL`	Rejected query parameters for caching.
ignored_query	`string[]`	`NULL`	Ignored query parameters for caching the response.

By Default

All HTTP responses are cached unless:

the request method is not GET
the request URI path starts with /admin…
the request URI contains a query string
the response is not OK (200)

Ignoring Query Strings

If query strings don't affect the server's response, you can permit caching of requests by ignoring all query parameters:

"ignored_query": "*"

or some of them:

"ignored_query": [ "sort", "theme" ]

Helpers

CachePoolAwareTrait

The CachePoolAwareTrait is offered as a convenience to avoid duplicate / boilerplate code. It simply sets and gets an instance of \Psr\Cache\CacheItemPoolInterface.

Assign a cache pool with setCachePool() and retrieve it with cachePool().

Both methods are protected; this trait has no public interface.

Resources

Contributing
Report issues and send pull requests in the main Charcoal repository

charcoal / cache

Maintainers

Details