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 bool Whether or not a NULL object will throw when called. */
  38   private $null_allowed = FALSE;
  39
  40   /*! Creates a weak interface with the name of an actual interface. */
  41   public function __construct($interface)
  42   {
  43     $reflector = new \ReflectionClass($interface);
  44     $methods = $reflector->GetMethods();
  45     foreach ($methods as $method) {
  46       $name = $method->name;
  47       $this->imps[$name] = new internal\MethodImp($this, $method);
  48     }
  49   }
  50
  51   /*! Gets the object to which this interface is bound. */
  52   public function get()
  53   {
  54     return $this->object;
  55   }
  56
  57   /*! Sets whether NULL is allowed. */
  58   public function set_null_allowed($flag)
  59   {
  60     $this->null_allowed = $flag;
  61   }
  62
  63   /*! Binds an object to the interface. */
  64   public function Bind($object)
  65   {
  66     $this->_CheckObject($object);
  67     $this->object = $object;
  68   }
  69
  70   /*! Magic method that performs the actual method invocation. */
  71   public function __call($meth, $args)
  72   {
  73     if (!$this->object) {
  74       if (!$this->null_allowed)
  75         throw new WeakInterfaceException('NULL object when calling ' . $meth);
  76       else
  77         return;
  78     }
  79
  80     return $this->imps[$meth]->Invoke($args);
  81   }
  82
  83   /*! Ensures that the bound object properly implements the interface. */
  84   private function _CheckObject($object)
  85   {
  86     $reflector = new \ReflectionClass($object);
  87     $methods = $reflector->GetMethods();
  88     $by_name = array();
  89     foreach ($methods as $method) {
  90       $by_name[$method->name] = $method;
  91     }
  92
  93     foreach ($this->imps as $name => $imp) {
  94       if ($imp->IsRequired() && !isset($by_name[$name]))
  95         throw new WeakInterfaceException($reflector->name . ' does not implement required interface method ' . $name);
  96
  97       if (isset($by_name[$name]) && !$imp->Matches($by_name[$name]))
  98         throw new WeakInterfaceException($reflector->name . '::' . $name . ' does not match interface definition');
  99     }
 100   }
 101 }
 102
 103 class WeakInterfaceException extends \Exception {}
 104
 105 }  // namespace hoplite\base
 106
 107 namespace hoplite\base\internal {
 108
 109 /*!
 110   An encapsulation of a method implementation.
 111 */
 112 class MethodImp
 113 {
 114   /*! @var WeakInterface The interface to which this method belongs. */
 115   private $interface = NULL;
 116
 117   /*! @var ReflectionMethod The method of the actual interface that this is implementing. */
 118   private $method = NULL;
 119
 120   public function __construct(\hoplite\base\WeakInterface $interface,
 121                               \ReflectionMethod $method)
 122   {
 123     $this->interface = $interface;
 124     $this->method = $method;
 125   }
 126
 127   /*! Forwards a method call. */
 128   public function Invoke($args)
 129   {
 130     $reflector = new \ReflectionClass($this->interface->get());
 131     try {
 132       $impl = $reflector->GetMethod($this->method->name);
 133     } catch (\ReflectionException $e) {
 134       if ($this->IsRequired())
 135         throw $e;
 136       return;
 137     }
 138     return $impl->InvokeArgs($this->interface->get(), $args);
 139   }
 140
 141   /*! Performs method signature validation. */
 142   public function Matches(\ReflectionMethod $method)
 143   {
 144     return $method->GetParameters() == $this->method->GetParameters();
 145   }
 146
 147   /*! Checks if a method is marked as required. */
 148   public function IsRequired()
 149   {
 150     return strpos($this->method->GetDocComment(), '@required') !== FALSE;
 151   }
 152 }
 153
 154 }  // namespace hoplite\base\internal