base/weak_interface.php

   1 <?php
   2 // Hoplite
   3 // Copyright (c) 2011 Blue Static
   4 //
   5 // This program is free software: you can redistribute it and/or modify it
   6 // under the terms of the GNU General Public License as published by the Free
   7 // Software Foundation, either version 3 of the License, or any later version.
   8 //
   9 // This program is distributed in the hope that it will be useful, but WITHOUT
  10 // ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  11 // FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  12 // more details.
  13 //
  14 // You should have received a copy of the GNU General Public License along with
  15 // this program.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 namespace hoplite\base {
  18
  19 /*!
  20   A WeakInterface is a class that implements some interface and then can bind
  21   a subset of those methods to some other object. This allows a delegate pattern
  22   to be implemented more easily in that the delegate class need not implement
  23   every method.
  24
  25   To use this class, define an interface as you normally would. When making a
  26   call to an object that implements the interface, create a WeakInterface object
  27   and instead make the calls on that.
  28 */
  29 class WeakInterface
  30 {
  31   /*! @var array Map of MethodImps keyed by the method name. */
  32   private $imps = array();
  33
  34   /*! @var object The object to which this interface is bound. */
  35   private $object = NULL;
  36
  37   /*! @var ReflectionClass The reflector of #object. */
  38   private $object_reflector = NULL;
  39
  40   /*! @var bool Whether or not a NULL object will throw when called. */
  41   private $null_allowed = FALSE;
  42
  43   /*! Creates a weak interface with the name of an actual interface. */
  44   public function __construct($interface)
  45   {
  46     $reflector = new \ReflectionClass($interface);
  47     $methods = $reflector->GetMethods();
  48     foreach ($methods as $method) {
  49       $name = $method->name;
  50       $this->imps[$name] = new internal\MethodImp($this, $method);
  51     }
  52   }
  53
  54   /*! Gets the object to which this interface is bound. */
  55   public function get()
  56   {
  57     return $this->object;
  58   }
  59
  60   /*! Sets whether NULL is allowed. */
  61   public function set_null_allowed($flag)
  62   {
  63     $this->null_allowed = $flag;
  64   }
  65
  66   /*! Binds an object to the interface. */
  67   public function Bind($object)
  68   {
  69     $this->_CheckObject($object);
  70     $this->object = $object;
  71     $this->object_reflector = new \ReflectionClass($this->object);
  72   }
  73
  74   /*! Magic method that performs the actual method invocation. */
  75   public function __call($meth, $args)
  76   {
  77     if (!$this->object) {
  78       if (!$this->null_allowed)
  79         throw new WeakInterfaceException('NULL object when calling ' . $meth);
  80       else
  81         return;
  82     }
  83
  84     return $this->imps[$meth]->Invoke($this->object_reflector, $args);
  85   }
  86
  87   /*! Ensures that the bound object properly implements the interface. */
  88   private function _CheckObject($object)
  89   {
  90     $reflector = new \ReflectionClass($object);
  91     $methods = $reflector->GetMethods();
  92     $by_name = array();
  93     foreach ($methods as $method) {
  94       $by_name[$method->name] = $method;
  95     }
  96
  97     foreach ($this->imps as $name => $imp) {
  98       if ($imp->IsRequired() && !isset($by_name[$name]))
  99         throw new WeakInterfaceException($reflector->name . ' does not implement required interface method ' . $name);
 100
 101       if (isset($by_name[$name]) && !$imp->Matches($by_name[$name]))
 102         throw new WeakInterfaceException($reflector->name . '::' . $name . ' does not match interface definition');
 103     }
 104   }
 105 }
 106
 107 class WeakInterfaceException extends \Exception {}
 108
 109 }  // namespace hoplite\base
 110
 111 namespace hoplite\base\internal {
 112
 113 /*!
 114   An encapsulation of a method implementation.
 115 */
 116 class MethodImp
 117 {
 118   /*! @var WeakInterface The interface to which this method belongs. */
 119   private $interface = NULL;
 120
 121   /*! @var ReflectionMethod The method of the actual interface that this is implementing. */
 122   private $method = NULL;
 123
 124   /*! @var bool Whether or not this is required. */
 125   private $required = FALSE;
 126
 127   public function __construct(\hoplite\base\WeakInterface $interface,
 128                               \ReflectionMethod $method)
 129   {
 130     $this->interface = $interface;
 131     $this->method = $method;
 132     $this->required = strpos($this->method->GetDocComment(), '@required') !== FALSE;
 133   }
 134
 135   /*! Forwards a method call. */
 136   public function Invoke($reflector, $args)
 137   {
 138     try {
 139       $impl = $reflector->GetMethod($this->method->name);
 140     } catch (\ReflectionException $e) {
 141       if ($this->required)
 142         throw $e;
 143       return;
 144     }
 145     return $impl->InvokeArgs($this->interface->get(), $args);
 146   }
 147
 148   /*! Performs method signature validation. */
 149   public function Matches(\ReflectionMethod $method)
 150   {
 151     return $method->GetParameters() == $this->method->GetParameters();
 152   }
 153
 154   /*! Checks if a method is marked as required. */
 155   public function IsRequired()
 156   {
 157     return $this->required;
 158   }
 159 }
 160
 161 }  // namespace hoplite\base\internal