[Summary view] [Print] [Text view]

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