[Summary view] [Print] [Text view]

   1  ---
   2  title: Access Interceptor Value Holder Proxy
   3  ---
   4  
   5  # Access Interceptor Value Holder Proxy
   6  
   7  An access interceptor value holder is a smart reference proxy that allows you to dynamically
   8  define logic to be executed before or after any of the wrapped object's methods
   9  logic.
  10  
  11  It wraps around a real instance of the object to be proxied, and can be useful for things like:
  12  
  13   * caching execution of slow and heavy methods
  14   * log method calls
  15   * debugging
  16   * event triggering
  17   * handling of orthogonal logic, and [AOP](http://en.wikipedia.org/wiki/Aspect-oriented_programming) in general
  18  
  19  ## Example
  20  
  21  Here's an example of how you can create and use an access interceptor value holder:
  22  
  23  ```php
  24  <?php
  25  
  26  use ProxyManager\Factory\AccessInterceptorValueHolderFactory as Factory;
  27  
  28  require_once  __DIR__ . '/vendor/autoload.php';
  29  
  30  class Foo
  31  {
  32      public function doFoo()
  33      {
  34          echo "Foo!\n";
  35      }
  36  }
  37  
  38  $factory = new Factory();
  39  
  40  $proxy = $factory->createProxy(
  41      new Foo(),
  42      ['doFoo' => function () { echo "PreFoo!\n"; }],
  43      ['doFoo' => function () { echo "PostFoo!\n"; }]
  44  );
  45  
  46  $proxy->doFoo();
  47  ```
  48  
  49  This send something like following to your output:
  50  
  51  ```
  52  PreFoo!
  53  Foo!
  54  PostFoo!
  55  ```
  56  
  57  ## Implementing pre- and post- access interceptors
  58  
  59  A proxy produced by the
  60  [`ProxyManager\Factory\AccessInterceptorValueHolderFactory`](https://github.com/Ocramius/ProxyManager/blob/master/src/ProxyManager/Factory/AccessInterceptorValueHolderFactory.php)
  61  implements the
  62  [`ProxyManager\Proxy\AccessInterceptorValueHolderInterface`](https://github.com/Ocramius/ProxyManager/blob/master/src/ProxyManager/Proxy/AccessInterceptorValueHolderInterface.php).
  63  
  64  Therefore, you can set an access interceptor callback by calling:
  65  
  66  ```php
  67  $proxy->setMethodPrefixInterceptor('methodName', function () { echo 'pre'; });
  68  $proxy->setMethodSuffixInterceptor('methodName', function () { echo 'post'; });
  69  ```
  70  
  71  You can also listen to public properties access by attaching interceptors to `__get`, `__set`, `__isset` and `__unset`.
  72  
  73  A prefix interceptor (executed before method logic) should have the following signature:
  74  
  75  ```php
  76  /**
  77   * @var object $proxy       the proxy that intercepted the method call
  78   * @var object $instance    the wrapped instance within the proxy
  79   * @var string $method      name of the called method
  80   * @var array  $params      sorted array of parameters passed to the intercepted
  81   *                          method, indexed by parameter name
  82   * @var bool   $returnEarly flag to tell the interceptor proxy to return early, returning
  83   *                          the interceptor's return value instead of executing the method logic
  84   *
  85   * @return mixed
  86   */
  87  $prefixInterceptor = function ($proxy, $instance, $method, $params, & $returnEarly) {};
  88  ```
  89  
  90  A suffix interceptor (executed after method logic) should have the following signature:
  91  
  92  ```php
  93  /**
  94   * @var object $proxy       the proxy that intercepted the method call
  95   * @var object $instance    the wrapped instance within the proxy
  96   * @var string $method      name of the called method
  97   * @var array  $params      sorted array of parameters passed to the intercepted
  98   *                          method, indexed by parameter name
  99   * @var mixed  $returnValue the return value of the intercepted method
 100   * @var bool   $returnEarly flag to tell the proxy to return early, returning the interceptor's
 101   *                          return value instead of the value produced by the method
 102   *
 103   * @return mixed
 104   */
 105  $suffixInterceptor = function ($proxy, $instance, $method, $params, $returnValue, & $returnEarly) {};
 106  ```
 107  
 108  ## Known limitations
 109  
 110   * methods using `func_get_args()`, `func_get_arg()` and `func_num_arg()` will not function properly
 111     for parameters that are not part of the proxied object interface: use 
 112     [variadic arguments](http://php.net/manual/en/functions.arguments.php#functions.variable-arg-list)
 113     instead.
 114  
 115  ## Tuning performance for production
 116  
 117  See [Tuning ProxyManager for Production](https://github.com/Ocramius/ProxyManager/blob/master/docs/tuning-for-production.md).