Skip to content

Latest commit

 

History

History

cache

README.md

Charcoal Cache

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:
  • 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:

  1. the request method is not GET
  2. the request URI path starts with /admin…
  3. the request URI contains a query string
  4. 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