[Summary view] [Print] [Text view]

   1  ---
   2  title: Lazy Loading Value Holder Proxy
   3  ---
   4  
   5  # Lazy Loading Value Holder Proxy
   6  
   7  A lazy loading value holder proxy is a virtual proxy that wraps and lazily initializes a "real" instance of the proxied
   8  class.
   9  
  10  ## What is lazy loading?
  11  
  12  In pseudo-code, in userland, [lazy loading](http://www.martinfowler.com/eaaCatalog/lazyLoad.html) looks like following:
  13  
  14  ```php
  15  class MyObjectProxy
  16  {
  17      private $wrapped;
  18  
  19      public function doFoo()
  20      {
  21          $this->init();
  22  
  23          return $this->wrapped->doFoo();
  24      }
  25  
  26      private function init()
  27      {
  28          if (null === $this->wrapped) {
  29              $this->wrapped = new MyObject();
  30          }
  31      }
  32  }
  33  ```
  34  
  35  This code is problematic, and adds a lot of complexity that makes your unit tests' code even worse.
  36  
  37  Also, this kind of usage often ends up in coupling your code with a particular
  38  [Dependency Injection Container](http://martinfowler.com/articles/injection.html)
  39  or a framework that fetches dependencies for you.
  40  That way, further complexity is introduced, and some problems related
  41  with service location raise, as I've explained
  42  [in this article](http://ocramius.github.com/blog/zf2-and-symfony-service-proxies-with-doctrine-proxies/).
  43  
  44  Lazy loading value holders abstract this logic for you, hiding your complex, slow, performance-impacting objects behind
  45  tiny wrappers that have their same API, and that get initialized at first usage.
  46  
  47  ## When do I use a lazy value holder?
  48  
  49  You usually need a lazy value holder in cases where following applies
  50  
  51   * your object takes a lot of time and memory to be initialized (with all dependencies)
  52   * your object is not always used, and the instantiation overhead can be avoided
  53  
  54  ## Usage examples
  55  
  56  [ProxyManager](https://github.com/Ocramius/ProxyManager) provides a factory that eases instantiation of lazy loading
  57  value holders. To use it, follow these steps:
  58  
  59  First of all, define your object's logic without taking care of lazy loading:
  60  
  61  ```php
  62  namespace MyApp;
  63  
  64  class HeavyComplexObject
  65  {
  66      public function __construct()
  67      {
  68          // just write your business logic
  69          // don't worry about how heavy initialization of this will be!
  70      }
  71  
  72      public function doFoo() {
  73          echo 'OK!';
  74      }
  75  }
  76  ```
  77  
  78  Then use the proxy manager to create a lazy version of the object (as a proxy):
  79  
  80  ```php
  81  namespace MyApp;
  82  
  83  use ProxyManager\Factory\LazyLoadingValueHolderFactory;
  84  use ProxyManager\Proxy\LazyLoadingInterface;
  85  
  86  require_once  __DIR__ . '/vendor/autoload.php';
  87  
  88  $factory     = new LazyLoadingValueHolderFactory();
  89  $initializer = function (& $wrappedObject, LazyLoadingInterface $proxy, $method, array $parameters, & $initializer) {
  90      $initializer   = null; // disable initialization
  91      $wrappedObject = new HeavyComplexObject(); // fill your object with values here
  92  
  93      return true; // confirm that initialization occurred correctly
  94  };
  95  
  96  $proxy = $factory->createProxy('MyApp\HeavyComplexObject', $initializer);
  97  ```
  98  
  99  You can now simply use your object as before:
 100  
 101  ```php
 102  // this will just work as before
 103  $proxy->doFoo(); // OK!
 104  ```
 105  
 106  ## Lazy Initialization
 107  
 108  As you can see, we use a closure to handle lazy initialization of the proxy instance at runtime.
 109  The initializer closure signature should be as following:
 110  
 111  ```php
 112  /**
 113   * @var object  $wrappedObject the instance (passed by reference) of the wrapped object,
 114   *                             set it to your real object
 115   * @var object  $proxy         the instance proxy that is being initialized
 116   * @var string  $method        the name of the method that triggered lazy initialization
 117   * @var array   $parameters    an ordered list of parameters passed to the method that
 118   *                             triggered initialization, indexed by parameter name
 119   * @var Closure $initializer   a reference to the property that is the initializer for the
 120   *                             proxy. Set it to null to disable further initialization
 121   *
 122   * @return bool true on success
 123   */
 124  $initializer = function (& $wrappedObject, $proxy, $method, array $parameters, & $initializer) {};
 125  ```
 126  
 127  The initializer closure should usually be coded like following:
 128  
 129  ```php
 130  $initializer = function (& $wrappedObject, $proxy, $method, array $parameters, & $initializer) {
 131      $newlyCreatedObject = new Foo(); // instantiation logic
 132      $newlyCreatedObject->setBar('baz') // instantiation logic
 133      $newlyCreatedObject->setBat('bam') // instantiation logic
 134  
 135      $wrappedObject = $newlyCreatedObject; // set wrapped object in the proxy
 136      $initializer   = null; // disable initializer
 137  
 138      return true; // report success
 139  };
 140  ```
 141  
 142  The
 143  [`ProxyManager\Factory\LazyLoadingValueHolderFactory`](https://github.com/Ocramius/ProxyManager/blob/master/src/ProxyManager/Factory/LazyLoadingValueHolderFactory.php)
 144  produces proxies that implement both the
 145  [`ProxyManager\Proxy\ValueHolderInterface`](https://github.com/Ocramius/ProxyManager/blob/master/src/ProxyManager/Proxy/ValueHolderInterface.php)
 146  and the
 147  [`ProxyManager\Proxy\LazyLoadingInterface`](https://github.com/Ocramius/ProxyManager/blob/master/src/ProxyManager/Proxy/LazyLoadingInterface.php).
 148  
 149  At any point in time, you can set a new initializer for the proxy:
 150  
 151  ```php
 152  $proxy->setProxyInitializer($initializer);
 153  ```
 154  
 155  In your initializer, you currently **MUST** turn off any further initialization:
 156  
 157  ```php
 158  $proxy->setProxyInitializer(null);
 159  ```
 160  
 161  or
 162  
 163  ```php
 164  $initializer = null; // if you use the initializer by reference
 165  ```
 166  
 167  ## Triggering Initialization
 168  
 169  A lazy loading proxy is initialized whenever you access any property or method of it.
 170  Any of the following interactions would trigger lazy initialization:
 171  
 172  ```php
 173  // calling a method
 174  $proxy->someMethod();
 175  
 176  // reading a property
 177  echo $proxy->someProperty;
 178  
 179  // writing a property
 180  $proxy->someProperty = 'foo';
 181  
 182  // checking for existence of a property
 183  isset($proxy->someProperty);
 184  
 185  // removing a property
 186  unset($proxy->someProperty);
 187  
 188  // cloning the entire proxy
 189  clone $proxy;
 190  
 191  // serializing the proxy
 192  $unserialized = serialize(unserialize($proxy));
 193  ```
 194  
 195  Remember to call `$proxy->setProxyInitializer(null);` to disable initialization of your proxy, or it will happen more
 196  than once.
 197  
 198  ## Proxying interfaces
 199  
 200  You can also generate proxies from an interface FQCN. By proxying an interface, you will only be able to access the
 201  methods defined by the interface itself, even if the `wrappedObject` implements more methods. This will anyway save
 202  some memory since the proxy won't contain useless inherited properties.
 203  
 204  ## Known limitations
 205  
 206   * methods using `func_get_args()`, `func_get_arg()` and `func_num_arg()` will not function properly
 207     for parameters that are not part of the proxied object interface: use 
 208     [variadic arguments](http://php.net/manual/en/functions.arguments.php#functions.variable-arg-list)
 209     instead.
 210  
 211  ## Tuning performance for production
 212  
 213  See [Tuning ProxyManager for Production](tuning-for-production.md).