From 853c50c977746a48f08ce163906b0f7d1113f9d7 Mon Sep 17 00:00:00 2001 From: Michael M Slusarz Date: Fri, 3 Sep 2010 11:01:14 -0600 Subject: [PATCH] phpdoc --- framework/Injector/lib/Horde/Injector.php | 67 ++++++++++++++-------- framework/Injector/lib/Horde/Injector/Binder.php | 15 +++-- .../lib/Horde/Injector/Binder/AnnotatedSetters.php | 44 +++++++++----- .../Injector/lib/Horde/Injector/Binder/Closure.php | 12 +++- .../Injector/lib/Horde/Injector/Binder/Factory.php | 13 ++++- .../lib/Horde/Injector/Binder/Implementation.php | 19 ++++-- .../lib/Horde/Injector/DependencyFinder.php | 23 +++++++- .../Injector/lib/Horde/Injector/Exception.php | 10 ++-- framework/Injector/lib/Horde/Injector/Scope.php | 22 ++++--- framework/Injector/lib/Horde/Injector/TopLevel.php | 22 ++++--- 10 files changed, 170 insertions(+), 77 deletions(-) diff --git a/framework/Injector/lib/Horde/Injector.php b/framework/Injector/lib/Horde/Injector.php index eefb3ef84..a147c036b 100644 --- a/framework/Injector/lib/Horde/Injector.php +++ b/framework/Injector/lib/Horde/Injector.php @@ -10,12 +10,23 @@ * @author Bob Mckee * @author James Pepin * @category Horde - * @package Horde_Injector + * @package Injector */ class Horde_Injector implements Horde_Injector_Scope { + /** + * @var Horde_Injector_Scope + */ private $_parentInjector; + + /** + * @var array + */ private $_bindings = array(); + + /** + * @var array + */ private $_instances; /** @@ -48,12 +59,9 @@ class Horde_Injector implements Horde_Injector_Scope } /** - * TODO - * - * @param string $name TODO - * @param array $name TODO + * Method overloader. Handles $this->bind[BinderType] type calls. * - * @return TODO + * @return Horde_Injector_Binder See _bind(). * @throws BadMethodCallException */ public function __call($name, $args) @@ -88,11 +96,12 @@ class Horde_Injector implements Horde_Injector_Scope $reflectionClass = new ReflectionClass('Horde_Injector_Binder_' . $type); - if ($reflectionClass->getConstructor()) { - $this->_addBinder($interface, $reflectionClass->newInstanceArgs($args)); - } else { - $this->_addBinder($interface, $reflectionClass->newInstance()); - } + $this->_addBinder( + $interface, + $reflectionClass->getConstructor() + ? $reflectionClass->newInstanceArgs($args) + : $reflectionClass->newInstance() + ); return $this->_getBinder($interface); } @@ -102,16 +111,14 @@ class Horde_Injector implements Horde_Injector_Scope * * This is the method by which we bind an interface to a concrete * implentation or factory. For convenience, binders may be added by - * bind[BinderType]. + * $this->bind[BinderType]. * - * bindFactory - creates a Horde_Injector_Binder_Factory - * bindImplementation - creates a Horde_Injector_Binder_Implementation + * bindFactory - Creates a Horde_Injector_Binder_Factory + * bindImplementation - Creates a Horde_Injector_Binder_Implementation * * All subsequent arguments are passed to the constructor of the * Horde_Injector_Binder object. * - * Any Horde_Injector_Binder object may be created this way. - * * @param string $interface The interface to bind to. * @param Horde_Injector_Binder $binder The binder to be bound to the * specified $interface. @@ -125,11 +132,11 @@ class Horde_Injector implements Horde_Injector_Scope } /** - * TODO + * @see self::addBinder() */ private function _addBinder($interface, Horde_Injector_Binder $binder) { - // first we check to see if our parent already has an equal binder set. + // First we check to see if our parent already has an equal binder set. // if so we don't need to do anything if (!$binder->equals($this->_parentInjector->getBinder($interface))) { $this->_bindings[$interface] = $binder; @@ -157,7 +164,13 @@ class Horde_Injector implements Horde_Injector_Scope } /** - * TODO + * Get the Binder associated with the specified instance. + * + * @param string $interface The interface to retrieve binding information + * for. + * + * @return Horde_Injector_Binder The binder object created. Useful for + * method chaining. */ private function _getBinder($interface) { @@ -205,33 +218,37 @@ class Horde_Injector implements Horde_Injector_Scope * * This method gets you an instance, and saves a reference to that * instance for later requests. + * * Interfaces must be bound to a concrete class to be created this way. * Concrete instances may be created through reflection. + * * It does not gaurantee that it is a new instance of the object. For a * new instance see createInstance(). * * @param string $interface The interface name, or object class to be * created. * - * @return mixed An object that implements $interface, not necessarily a - * new one. + * @return mixed An object that implements $interface, but not + * necessarily a new one. */ public function getInstance($interface) { - // do we have an instance? + // Do we have an instance? if (!isset($this->_instances[$interface])) { - // do we have a binding for this interface? if so then we don't ask our parent + // Do we have a binding for this interface? If so then we don't + // ask our parent if (!isset($this->_bindings[$interface])) { - // does our parent have an instance? + // Does our parent have an instance? if ($instance = $this->_parentInjector->getInstance($interface)) { return $instance; } } - // we have to make our own instance + // We have to make our own instance $this->setInstance($interface, $this->createInstance($interface)); } return $this->_instances[$interface]; } + } diff --git a/framework/Injector/lib/Horde/Injector/Binder.php b/framework/Injector/lib/Horde/Injector/Binder.php index 8078c37e5..9f1eb8969 100644 --- a/framework/Injector/lib/Horde/Injector/Binder.php +++ b/framework/Injector/lib/Horde/Injector/Binder.php @@ -5,7 +5,7 @@ * PHP version 5 * * @category Horde - * @package Horde_Injector + * @package Injector * @author Bob Mckee * @author James Pepin * @license http://opensource.org/licenses/bsd-license.php BSD @@ -16,7 +16,7 @@ * Describes a binding class that is able to create concrete object instances. * * @category Horde - * @package Horde_Injector + * @package Injector * @author Bob Mckee * @author James Pepin * @license http://opensource.org/licenses/bsd-license.php BSD @@ -27,8 +27,9 @@ interface Horde_Injector_Binder /** * Create an instance. * - * @param Horde_Injector $injector The injector should provide all required - * dependencies for creating the instance. + * @param Horde_Injector $injector The injector should provide all + * required dependencies for creating the + * instance. * * @return mixed The concrete instance. */ @@ -37,9 +38,11 @@ interface Horde_Injector_Binder /** * Determine if one binder equals another binder * - * @param Horde_Injector_Binder $binder The binder to compare against $this + * @param Horde_Injector_Binder $binder The binder to compare against + * $this. * - * @return bool true if they are equal, or false if they are not equal + * @return boolean True if equal, false if not equal. */ public function equals(Horde_Injector_Binder $binder); + } diff --git a/framework/Injector/lib/Horde/Injector/Binder/AnnotatedSetters.php b/framework/Injector/lib/Horde/Injector/Binder/AnnotatedSetters.php index eee9f3e85..2d71971d5 100644 --- a/framework/Injector/lib/Horde/Injector/Binder/AnnotatedSetters.php +++ b/framework/Injector/lib/Horde/Injector/Binder/AnnotatedSetters.php @@ -8,7 +8,7 @@ * @author James Pepin * @author Chuck Hagenbuch * @category Horde - * @package Horde_Injector + * @package Injector */ class Horde_Injector_Binder_AnnotatedSetters implements Horde_Injector_Binder { @@ -23,18 +23,27 @@ class Horde_Injector_Binder_AnnotatedSetters implements Horde_Injector_Binder private $_dependencyFinder; /** + * Constructor. + * + * @param Horde_Injector_Binder $binder TODO + * @param Horde_Injector_DependencyFinder $finder TODO * */ - public function __construct(Horde_Injector_Binder $binder, Horde_Injector_DependencyFinder $dependencyFinder = null) + public function __construct(Horde_Injector_Binder $binder, + Horde_Injector_DependencyFinder $finder = null) { $this->_binder = $binder; - - if (is_null($dependencyFinder)) { $dependencyFinder = new Horde_Injector_DependencyFinder(); } - $this->_dependencyFinder = $dependencyFinder; + $this->_dependencyFinder = is_null($finder) + ? new Horde_Injector_DependencyFinder() + : $finder; } /** * TODO + * + * @param Horde_Injector_Binder $binder TODO + * + * @return boolean Equality. */ public function equals(Horde_Injector_Binder $otherBinder) { @@ -42,6 +51,11 @@ class Horde_Injector_Binder_AnnotatedSetters implements Horde_Injector_Binder $this->getBinder()->equals($otherBinder->getBinder()); } + /** + * TODO + * + * @return Horde_Injector_Binder TODO + */ public function getBinder() { return $this->_binder; @@ -65,9 +79,9 @@ class Horde_Injector_Binder_AnnotatedSetters implements Horde_Injector_Binder * Find all public methods in $reflectionClass that are annotated with * @inject. * - * @param ReflectionClass $reflectionClass + * @param ReflectionClass $reflectionClass TODO * - * @return array + * @return array TODO */ private function _findAnnotatedSetters(ReflectionClass $reflectionClass) { @@ -82,10 +96,10 @@ class Horde_Injector_Binder_AnnotatedSetters implements Horde_Injector_Binder } /** - * Is a method a setter method, by the criteria we define (has a doc comment - * that includes @inject). + * Is a method a setter method, by the criteria we define (has a doc + * comment that includes @inject). * - * @param ReflectionMethod $reflectionMethod + * @param ReflectionMethod $reflectionMethod TODO */ private function _isSetterMethod(ReflectionMethod $reflectionMethod) { @@ -103,11 +117,12 @@ class Horde_Injector_Binder_AnnotatedSetters implements Horde_Injector_Binder * Call each ReflectionMethod in the $setters array, filling in its * dependencies with the $injector. * - * @param array $setters Array of ReflectionMethods to call - * @param Horde_Injector $injector The Horde_Injector to get dependencies from - * @param object $instance The object to call setters on + * @param array $setters Array of ReflectionMethods to call. + * @param Horde_Injector $injector The injector to get dependencies from. + * @param object $instance The object to call setters on. */ - private function _callSetters(array $setters, Horde_Injector $injector, $instance) + private function _callSetters(array $setters, Horde_Injector $injector, + $instance) { foreach ($setters as $setterMethod) { $setterMethod->invokeArgs( @@ -116,4 +131,5 @@ class Horde_Injector_Binder_AnnotatedSetters implements Horde_Injector_Binder ); } } + } diff --git a/framework/Injector/lib/Horde/Injector/Binder/Closure.php b/framework/Injector/lib/Horde/Injector/Binder/Closure.php index 9a528e42d..4a8f551cd 100644 --- a/framework/Injector/lib/Horde/Injector/Binder/Closure.php +++ b/framework/Injector/lib/Horde/Injector/Binder/Closure.php @@ -6,18 +6,22 @@ * Horde_Injector and return an object that satisfies the instance * requirement. For example: * + * 
  * $injector->bindClosure('database', function($injector) { return new my_mysql(); });
+ *
* * @author Bob Mckee * @author James Pepin * @author Chuck Hagenbuch * @category Horde - * @package Horde_Injector + * @package Injector */ class Horde_Injector_Binder_Closure implements Horde_Injector_Binder { /** * TODO + * + * @var Horde_Injector_Binder_Closure */ private $_closure; @@ -33,6 +37,10 @@ class Horde_Injector_Binder_Closure implements Horde_Injector_Binder /** * TODO + * + * @param Horde_Injector_Binder $otherBinder TODO + * + * @return boolean Equality. */ public function equals(Horde_Injector_Binder $otherBinder) { @@ -70,6 +78,8 @@ class Horde_Injector_Binder_Closure implements Horde_Injector_Binder { $childInjector = $injector->createChildInjector(); $closure = $this->_closure; + return $closure($childInjector); } + } diff --git a/framework/Injector/lib/Horde/Injector/Binder/Factory.php b/framework/Injector/lib/Horde/Injector/Binder/Factory.php index 588a8688e..56dacf93a 100644 --- a/framework/Injector/lib/Horde/Injector/Binder/Factory.php +++ b/framework/Injector/lib/Horde/Injector/Binder/Factory.php @@ -6,6 +6,7 @@ * provide a method or methods that accept a Horde_Injector, and return an * object that satisfies the instance requirement. For example: * + * 
  * class MyFactory {
  *   ...
  *   public function create(Horde_Injector $injector)
@@ -14,21 +15,26 @@
  *   }
  *   ...
  * }
+ *
* * @author Bob Mckee * @author James Pepin * @category Horde - * @package Horde_Injector + * @package Injector */ class Horde_Injector_Binder_Factory implements Horde_Injector_Binder { /** * TODO + * + * @var string */ private $_factory; /** * TODO + * + * @var string */ private $_method; @@ -47,6 +53,10 @@ class Horde_Injector_Binder_Factory implements Horde_Injector_Binder /** * TODO + * + * @param Horde_Injector_Binder $otherBinder TODO + * + * @return boolean Equality. */ public function equals(Horde_Injector_Binder $otherBinder) { @@ -100,4 +110,5 @@ class Horde_Injector_Binder_Factory implements Horde_Injector_Binder * type. */ return $childInjector->getInstance($this->_factory)->{$this->_method}($childInjector); } + } diff --git a/framework/Injector/lib/Horde/Injector/Binder/Implementation.php b/framework/Injector/lib/Horde/Injector/Binder/Implementation.php index 86d350d5a..034e69aa0 100644 --- a/framework/Injector/lib/Horde/Injector/Binder/Implementation.php +++ b/framework/Injector/lib/Horde/Injector/Binder/Implementation.php @@ -5,7 +5,7 @@ * @author Bob Mckee * @author James Pepin * @category Horde - * @package Horde_Injector + * @package Injector */ class Horde_Injector_Binder_Implementation implements Horde_Injector_Binder { @@ -22,16 +22,19 @@ class Horde_Injector_Binder_Implementation implements Horde_Injector_Binder /** * TODO */ - public function __construct($implementation, Horde_Injector_DependencyFinder $dependencyFinder = null) + public function __construct($implementation, + Horde_Injector_DependencyFinder $finder = null) { $this->_implementation = $implementation; - - if (is_null($dependencyFinder)) { $dependencyFinder = new Horde_Injector_DependencyFinder(); } - $this->_dependencyFinder = $dependencyFinder; + $this->_dependencyFinder = is_null($finder) + ? new Horde_Injector_DependencyFinder() + : $finder; } /** * TODO + * + * @return TODO */ public function getImplementation() { @@ -40,6 +43,8 @@ class Horde_Injector_Binder_Implementation implements Horde_Injector_Binder /** * TODO + * + * @return boolean Equality. */ public function equals(Horde_Injector_Binder $otherBinder) { @@ -70,10 +75,12 @@ class Horde_Injector_Binder_Implementation implements Horde_Injector_Binder /** * TODO */ - protected function _getInstance(Horde_Injector $injector, ReflectionClass $class) + protected function _getInstance(Horde_Injector $injector, + ReflectionClass $class) { return $class->getConstructor() ? $class->newInstanceArgs($this->_dependencyFinder->getMethodDependencies($injector, $class->getConstructor())) : $class->newInstance(); } + } diff --git a/framework/Injector/lib/Horde/Injector/DependencyFinder.php b/framework/Injector/lib/Horde/Injector/DependencyFinder.php index 2ac3bbe2c..82b0f86aa 100644 --- a/framework/Injector/lib/Horde/Injector/DependencyFinder.php +++ b/framework/Injector/lib/Horde/Injector/DependencyFinder.php @@ -7,13 +7,21 @@ * @author James Pepin * @author Chuck Hagenbuch * @category Horde - * @package Horde_Injector + * @package Injector */ class Horde_Injector_DependencyFinder { /** + * TODO + * + * @param Horde_Injector $injector TODO + * @param ReflectionMethod $method TODO + * + * @return array TODO + * @throws Horde_Injector_Exception */ - public function getMethodDependencies(Horde_Injector $injector, ReflectionMethod $method) + public function getMethodDependencies(Horde_Injector $injector, + ReflectionMethod $method) { $dependencies = array(); @@ -29,8 +37,16 @@ class Horde_Injector_DependencyFinder } /** + * TODO + * + * @param Horde_Injector $injector TODO + * @param ReflectionParameter $method TODO + * + * @return mixed TODO + * @throws Horde_Injector_Exception */ - public function getParameterDependency(Horde_Injector $injector, ReflectionParameter $parameter) + public function getParameterDependency(Horde_Injector $injector, + ReflectionParameter $parameter) { if ($parameter->getClass()) { return $injector->getInstance($parameter->getClass()->getName()); @@ -40,4 +56,5 @@ class Horde_Injector_DependencyFinder throw new Horde_Injector_Exception("Untyped parameter \$" . $parameter->getName() . "can't be fulfilled"); } + } diff --git a/framework/Injector/lib/Horde/Injector/Exception.php b/framework/Injector/lib/Horde/Injector/Exception.php index 9ef52464f..401c5804d 100644 --- a/framework/Injector/lib/Horde/Injector/Exception.php +++ b/framework/Injector/lib/Horde/Injector/Exception.php @@ -1,10 +1,8 @@ - * @author James Pepin + * @author Bob Mckee + * @author James Pepin * @category Horde - * @package Horde_Injector + * @package Injector */ -class Horde_Injector_Exception extends Exception -{ -} +class Horde_Injector_Exception extends Exception {} diff --git a/framework/Injector/lib/Horde/Injector/Scope.php b/framework/Injector/lib/Horde/Injector/Scope.php index a94bba6b7..3667bf9af 100644 --- a/framework/Injector/lib/Horde/Injector/Scope.php +++ b/framework/Injector/lib/Horde/Injector/Scope.php @@ -2,28 +2,36 @@ /** * Interface for injector scopes * - * Injectors implement a Chain of Responsibility pattern. This is the required - * interface for injectors to pass on responsibility to parent objects in the chain. + * Injectors implement a Chain of Responsibility pattern. This is the + * required interface for injectors to pass on responsibility to parent + * objects in the chain. * * @category Horde - * @package Horde_Injector + * @package Injector */ interface Horde_Injector_Scope { /** - * Returns the Horde_Injector_Binder object mapped to the request interface if such a + * Returns the Horde_Injector_Binder object mapped to the request + * interface if such a * mapping exists * + * @param string $interface Interface name of object whose binding if + * being retrieved. + * * @return Horde_Injector_Binder|null - * @param string $interface interface name of object whose binding if being retrieved */ public function getBinder($interface); /** - * Returns instance of requested object if proper configuration has been provided. + * Returns instance of requested object if proper configuration has been + * provided. + * + * @param string $interface Interface name of object which is being + * requested. * * @return Object - * @param string $interface interface name of object which is being requested */ public function getInstance($interface); + } diff --git a/framework/Injector/lib/Horde/Injector/TopLevel.php b/framework/Injector/lib/Horde/Injector/TopLevel.php index 31c4d31b3..8412025e8 100644 --- a/framework/Injector/lib/Horde/Injector/TopLevel.php +++ b/framework/Injector/lib/Horde/Injector/TopLevel.php @@ -5,25 +5,30 @@ * This class returns a Horde_Injector_Binder_Implementation with the requested * $interface mapped to itself. This is the default case, and for conrete * classes should work all the time so long as you constructor parameters are - * typed + * typed. * - * @author Bob Mckee - * @author James Pepin + * @author Bob Mckee + * @author James Pepin * @category Horde - * @package Horde_Injector + * @package Injector */ class Horde_Injector_TopLevel implements Horde_Injector_Scope { /** * Get an Implementation Binder that maps the $interface to itself * - * @param string $interface The interface to retrieve binding information for - * @return Horde_Injector_Binder_ImplementationWithSetters a new binding object that maps the interface to itself, with setter injection + * @param string $interface The interface to retrieve binding information + * for. + * + * @return Horde_Injector_Binder_ImplementationWithSetters + * A new binding object that maps the interface to itself, with + * setter injection. */ public function getBinder($interface) { $dependencyFinder = new Horde_Injector_DependencyFinder(); $implementationBinder = new Horde_Injector_Binder_Implementation($interface, $dependencyFinder); + return new Horde_Injector_Binder_AnnotatedSetters($implementationBinder, $dependencyFinder); } @@ -31,8 +36,8 @@ class Horde_Injector_TopLevel implements Horde_Injector_Scope * Always return null. Object doesn't keep instance references * * Method is necessary because this object is the default parent Injector. - * The child of this injector will ask it for instances in the case where no - * bindings are set on the child. This should always return null. + * The child of this injector will ask it for instances in the case where + * no bindings are set on the child. This should always return null. * * @param string $interface The interface in question * @return null @@ -41,4 +46,5 @@ class Horde_Injector_TopLevel implements Horde_Injector_Scope { return null; } + } -- 2.11.0