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.

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.

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

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