vendor/zendframework/zend-cache/doc/book/pattern/object-cache.md

   1 # ObjectCache
   2
   3 The `ObjectCache` pattern is an extension to the `CallbackCache` pattern. It has
   4 the same methods, but instead caches output from any instance method calls or
   5 public properties.
   6
   7 ## Quick Start
   8
   9 ```php
  10 use stdClass;
  11 use Zend\Cache\PatternFactory;
  12
  13 $object      = new stdClass();
  14 $objectCache = PatternFactory::factory('object', [
  15     'object'  => $object,
  16     'storage' => 'apc'
  17 ]);
  18 ```
  19
  20 ## Configuration Options
  21
  22 Option | Data Type | Default Value | Description
  23 ------ | --------- | ------------- | -----------
  24 `storage` | `string | array | Zend\Cache\Storage\StorageInterface` | none | Adapter used for reading and writing cached data.
  25 `object` | `object` | none | The object for which to cache method calls.
  26 `object_key` | `null | string` | Class name of object | Hopefully unique!
  27 `cache_output` | `boolean` | `true` | Whether or not to cache method output.
  28 `cache_by_default` | `boolean` | `true` | Cache all method calls by default.
  29 `object_cache_methods` | `array` | `[]` | List of methods to cache (if `cache_by_default` is disabled).
  30 `object_non_cache_methods` | `array` | `[]` | List of methods to blacklist (if `cache_by_default` is enabled).
  31 `object_cache_magic_properties` | `boolean` | `false` | Whether or not to cache properties exposed by method overloading.
  32
  33 ## Available Methods
  34
  35 In addition to the methods defined in `PatternInterface`, this implementation
  36 defines the following methods.
  37
  38 ```php
  39 namespace Zend\Cache\Pattern;
  40
  41 use Zend\Cache\Exception;
  42
  43 class ObjectCache extends CallbackCache
  44 {
  45     /**
  46      * Call and cache a class method
  47      *
  48      * @param  string $method  Method name to call
  49      * @param  array  $args    Method arguments
  50      * @return mixed
  51      * @throws Exception\RuntimeException
  52      * @throws \Exception
  53      */
  54     public function call($method, array $args = []);
  55
  56     /**
  57      * Method overloading: proxies to call().
  58      *
  59      * @param  string $method  Method name to call
  60      * @param  array  $args    Method arguments
  61      * @return mixed
  62      * @throws Exception\RuntimeException
  63      * @throws \Exception
  64      */
  65     public function __call($method, array $args);
  66
  67     /**
  68      * Generate a unique key in base of a key representing the callback part
  69      * and a key representing the arguments part.
  70      *
  71      * @param  string     $method  The method
  72      * @param  array      $args    Callback arguments
  73      * @return string
  74      * @throws Exception\RuntimeException
  75      */
  76     public function generateKey($method, array $args = []);
  77
  78     /**
  79      * Property overloading: write data to a named property.
  80      *
  81      * NOTE:
  82      * Magic properties will be cached too if the option cacheMagicProperties
  83      * is enabled and the property doesn't exist in real. If so it calls __set
  84      * and removes cached data of previous __get and __isset calls.
  85      *
  86      * @param  string $name
  87      * @param  mixed  $value
  88      * @return void
  89      * @see    http://php.net/manual/language.oop5.overloading.php#language.oop5.overloading.members
  90      */
  91     public function __set($name, $value);
  92
  93     /**
  94      * Property overloading: read data from a named property.
  95      *
  96      * NOTE:
  97      * Magic properties will be cached too if the option cacheMagicProperties
  98      * is enabled and the property doesn't exist in real. If so it calls __get.
  99      *
 100      * @param  string $name
 101      * @return mixed
 102      * @see http://php.net/manual/language.oop5.overloading.php#language.oop5.overloading.members
 103      */
 104     public function __get($name);
 105
 106     /**
 107      * Property overloading: check if a named property exists.
 108      *
 109      * NOTE:
 110      * Magic properties will be cached too if the option cacheMagicProperties
 111      * is enabled and the property doesn't exist in real. If so it calls __get.
 112      *
 113      * @param  string $name
 114      * @return bool
 115      * @see    http://php.net/manual/language.oop5.overloading.php#language.oop5.overloading.members
 116      */
 117     public function __isset($name);
 118
 119     /**
 120      * Property overloading: unset a named property.
 121      *
 122      * NOTE:
 123      * Magic properties will be cached too if the option cacheMagicProperties
 124      * is enabled and the property doesn't exist in real. If so it removes
 125      * previous cached __isset and __get calls.
 126      *
 127      * @param  string $name
 128      * @return void
 129      * @see    http://php.net/manual/language.oop5.overloading.php#language.oop5.overloading.members
 130      */
 131     public function __unset($name);
 132
 133     /**
 134      * Handle casting to string
 135      *
 136      * @return string
 137      * @see    http://php.net/manual/language.oop5.magic.php#language.oop5.magic.tostring
 138      */
 139     public function __toString();
 140
 141     /**
 142      * Intercept and cache invokable usage.
 143      *
 144      * @return mixed
 145      * @see    http://php.net/manual/language.oop5.magic.php#language.oop5.magic.invoke
 146      */
 147     public function __invoke();
 148 }
 149 ```
 150
 151 ## Examples
 152
 153 ### Caching a filter
 154
 155 ```php
 156 $filter       = new Zend\Filter\RealPath();
 157 $cachedFilter = Zend\Cache\PatternFactory::factory('object', [
 158     'object'     => $filter,
 159     'object_key' => 'RealpathFilter',
 160     'storage'    => 'apc',
 161
 162     // The realpath filter doesn't output anything
 163     // so the output don't need to be caught and cached
 164     'cache_output' => false,
 165 ]);
 166
 167 $path = $cachedFilter->call("filter", ['/www/var/path/../../mypath']);
 168
 169 // OR
 170 $path = $cachedFilter->filter('/www/var/path/../../mypath');
 171 ```