phossa/phossa-cache

The PSR-6 compliant PHP caching library.

1.0.10 2016-04-18 03:50 UTC

README

Build Status HHVM Latest Stable Version License

Introduction

Phossa-cache is a PSR-6 compliant caching library. It supports various drivers and useful features like bypass, encrypt, stampede protection, garbage collect, taggable item etc.

More information about PSR-6 and PSR-6 Meta

Installation

Install via the composer utility.

composer require "phossa/phossa-cache=1.*"

or add the following lines to your composer.json

{
    "require": {
       "phossa/phossa-cache": "^1.0.8"
    }
}

Features

  • Fully PSR-6 compliant. Maybe the most feature-rich PSR-6 caching package you will find at github at this time.

  • Support all serializable PHP datatypes.

  • Extensions:

    • Bypass: If sees a trigger in URL (e.g. '?nocache=true'), bypass the cache.

    • Stampede: Whenever cached object's lifetime is less than a configurable time, by certain percentage, the cache will return false on 'isHit()' which will trigger re-generation of the object.

    • Encrypt: A simple extension to encrypt the serialized content

    • GarbageCollect: A simple extension to auto-clean the cache pool.

    • Taggable: Item is taggable and can be cleared by tag.

    • DistributeMiss: Even out the spikes of item misses by alter expiration time a little bit.

  • Drivers

    • FilesystemDriver

      The filesystem driver stores cached item in filesystem. It stores cached items in a md5-filename flat file. Configurable settings are

      • dir_root: the base directory for the filesystem cache
      • hash_level: hashed subdirectory level. default to 2
      • file_pref: cached item filename prefix
      • file_suff: cached item filename suffix
      /*
       * construct the driver manually
       */
      $driver = new Driver\FilesystemDriver([
          'hash_level'    => 1,
          'file_pref'     => 'cache.',
          'dir_root'      => '/var/tmp/cache',
      ]);
    • NullDriver

      The blackhole driver. used as fallback driver for all other drivers.

    • Fallback driver

      User may configure a fallback driver if the desired driver is not ready. The NullDriver is the final fallback for all other drivers.

      // default memcache driver
      $driver = new Driver\MemcacheDriver([
          'server' => [ '127.0.0.1', 11211 ]
      ]);
      
      // set a fallback filesystem driver
      $driver->setFallback(new Driver\FilesystemDriver([
          'dir_root' => '/var/tmp/cache'
      ]));
      
      $cache = new CachePool($driver);
    • CompositeDriver

      The CompositeDriver consists of two drivers, the front-end driver and the backend driver. User filters cachable objects by defining a tester callable which will determine which objects stores to both ends or backend only.

      /*
       * set the composite driver
       */
      $driver = new Driver\CompositeDriver(
          // front-end driver
          new Driver\MemcacheDriver([
              'server' => [ '127.0.0.1', 11211 ]
          ]),
      
          // backend driver
          new Driver\FilesystemDriver([
              'dir_root' => '/var/tmp/cache'
          ]),
      
          // other settings
          [
              // if size > 10k, stores at backend only
              'tester' => function($item) {
                  if (strlen($item->get()) > 10240) return false;
                  return true;
              }
          ]
      );
  • Logging

    The phossa-cache supports psr-3 compliant logger. Also provides a log() method for logging.

    /*
     * set the logger
     */
    $cache->setLogger($psrLogger);
    $cache->log('info', 'this is an info');

    Or configure with logger at cache init

    /*
     * the third argument is used for configuring CachePool
     */
    $cache = new CachePool($driver, [],
        'logger' => $psrLogger
    );
    $cache->log('info', 'this is an info');
  • Error

    No exceptions thrown during caching process. So only errors will be used.

    /*
     * create cache pool, exceptions may thrown here
     */
    $cache = new CachePool();
    $cache->setLogger($psrLogger);
    
    $item = $cache->getItem('widget_list');
    $val  = $item->get();
    if ($cache->hasError()) {
        $cache->log('error', $cache->getError());
        $widget_list = compute_expensive_widget_list();
        $item->set($widget_list);
        $item->expiresAfter(3600); // expires after an hour
        $cache->save($item);
        if ($cache->hasError()) $cache->log('error', $cache->getError());
    } else {
        $widget_list = $val;
    }
  • I18n

    Messages are in Message\Message.php. I18n is possible. See phossa-shared package for detail.

  • Support PHP 5.4+, PHP 7.0, HHVM.

  • PHP7 ready for return type declarations and argument type declarations.

  • PSR-1, PSR-2, PSR-3, PSR-4, PSR-6 compliant.

Usage

  • The simple usage

    /*
     * use the default FilesystemDriver which also set default cache
     * directory to sys_get_temp_dir() .'/cache'
     */
    $cache = new CachePool();
    
    $item = $cache->getItem('widget_list');
    if (!$item->isHit()) {
        $value = compute_expensive_widget_list();
        $item->set($value);
        $cache->save($item);
    }
    $widget_list = $item->get();
  • Configure the driver

    $driver = new Driver\FilesystemDriver([
        'hash_level'    => 1, // subdirectory hash levels
        'file_pref'     => 'cache.', // cache file prefix
        'file_suff'     => '.txt',   // cache file suffix
        'dir_root'      => '/var/tmp/cache' // reset cache root
    ]);
    
    $cache = new CachePool($driver);
  • Use extensions

    /*
     * SerializeExtension is the default ext, always used.
     * Second argument is an array of ExtensionInterface or config array
     */
    $cache = new CachePool(
        $driver,
        [
            new Extension\BypassExtension(),
            new Extension\StampedeExtension(['probability' => 80 ])
        ]
    );

    or addExtension()

    $cache = new CachePool($driver);
    $cache->addExtension(new Extension\BypassExtension());
  • Hierarchal cache support

    Directory-style hierarchal structure is supported in FilesystemDriver and so other coming drivers.

    // hierarchy key
    $item = $cache->getItem('mydomain/host1/newfile_xxx');
    
    // ending '/' means delete the hierarchy structure
    $cache->deleteItem('mydomain/host1/');

Dependencies

  • PHP >= 5.4.0
  • phossa/phossa-shared 1.0.6
  • psr/cache 1.*

License

MIT License