Charcoal Cache
![License][badge-license]
![Code Quality][badge-scrutinizer]
![SensioLabs Insight][badge-sensiolabs]
, (*1)
A Charcoal service provider for the Stash Cache Library., (*2)
Table of Contents
Installation
-
The preferred (and only supported) method is with Composer:, (*3)
$ composer require locomotivemtl/charcoal-cache
-
Add the service provider and configure the default caching service via the application configset:, (*4)
"service_providers": {
"charcoal/cache/service-provider/cache": {}
},
"cache": {
"prefix": "foobar",
"types": [ "apc", "memcache", "redis" ]
}
or via the service container:, (*5)
$container->register(new \Charcoal\Cache\ServiceProvider\CacheServiceProvider());
$container['cache/config'] = new \Charcoal\Cache\CacheConfig([
'prefix' => 'foobar',
'types' => [ 'apc', 'memcache', 'redis' ],
]);
If you are using locomotivemtl/charcoal-app, the CacheServiceProvider is automatically registered by the AppServiceProvider., (*6)
Dependencies
Required
PSR
-
PSR-3: Common interface for logging libraries. Supported by Stash.
-
PSR-6: Common interface for caching libraries. Fulfilled by Stash.
-
PSR-7: Common interface for HTTP messages. Followed by
CacheMiddleware.
-
PSR-11: Common interface for dependency containers. Fulfilled by Pimple.
Dependents
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., (*7)
| 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). |
Driver Configuration
~~Each driver comes with a set of default options which can be individually overridden.~~, (*8)
—N/A—, (*9)
Usage
Just fetch the default cache pool service:, (*10)
$pool = $this->container->get('cache');
Or a custom-defined cache pool:, (*11)
// 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:, (*12)
// 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., (*13)
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., (*14)
If you are using locomotivemtl/charcoal-app, you can add the middleware via the application configset:, (*15)
"middlewares": {
"charcoal/cache/middleware/cache": {
"active": true,
"methods": [ "GET", "HEAD" ]
}
}
Otherwise, with Slim, for example:, (*16)
$app = new \Slim\App();
// Register middleware
$app->add(new \Charcoal\Cache\Middleware\CacheMiddleware([
'cache' => new \Stash\Pool(),
'methods' => [ 'GET', 'HEAD' ],
]));
The middleware comes with a set of default options which can be individually overridden., (*17)
| Setting |
Type |
Default |
Description |
| active |
boolean |
FALSE |
Whether to enable or disable the middleware (locomotivemtl/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:, (*18)
- 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:, (*19)
"ignored_query": "*"
or some of them:, (*20)
"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., (*21)
Assign a cache pool with setCachePool() and retrieve it with cachePool()., (*22)
Both methods are protected; this trait has no public interface., (*23)
Development
To install the development environment:, (*24)
$ composer install
To run the scripts (phplint, phpcs, and phpunit):, (*25)
$ composer test
API Documentation
Development Dependencies
Coding Style
The charcoal-cache module follows the Charcoal coding-style:, (*26)
Coding style validation / enforcement can be performed with composer phpcs. An auto-fixer is also available with composer phpcbf., (*27)
Credits
License
- Charcoal is licensed under the MIT license. See LICENSE for details.
- Stash is licensed under the BSD License. See the LICENSE file for details.
Wallogit.com
