includes/libs/ObjectFactory.php

   1 <?php
   2 /**
   3  * This program is free software; you can redistribute it and/or modify
   4  * it under the terms of the GNU General Public License as published by
   5  * the Free Software Foundation; either version 2 of the License, or
   6  * (at your option) any later version.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along
  14  * with this program; if not, write to the Free Software Foundation, Inc.,
  15  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  16  * http://www.gnu.org/copyleft/gpl.html
  17  *
  18  * @file
  19  */
  20
  21 /**
  22  * Construct objects from configuration instructions.
  23  *
  24  * @author Bryan Davis <bd808@wikimedia.org>
  25  * @copyright © 2014 Bryan Davis and Wikimedia Foundation.
  26  */
  27 class ObjectFactory {
  28
  29         /**
  30          * Instantiate an object based on a specification array.
  31          *
  32          * The specification array must contain a 'class' key with string value
  33          * that specifies the class name to instantiate or a 'factory' key with
  34          * a callable (is_callable() === true). It can optionally contain
  35          * an 'args' key that provides arguments to pass to the
  36          * constructor/callable.
  37          *
  38          * Object construction using a specification having both 'class' and
  39          * 'args' members will call the constructor of the class using
  40          * ReflectionClass::newInstanceArgs. The use of ReflectionClass carries
  41          * a performance penalty and should not be used to create large numbers of
  42          * objects. If this is needed, consider introducing a factory method that
  43          * can be called via call_user_func_array() instead.
  44          *
  45          * Values in the arguments collection which are Closure instances will be
  46          * expanded by invoking them with no arguments before passing the
  47          * resulting value on to the constructor/callable. This can be used to
  48          * pass DatabaseBase instances or other live objects to the
  49          * constructor/callable. This behavior can be suppressed by adding
  50          * closure_expansion => false to the specification.
  51          *
  52          * The specification may also contain a 'calls' key that describes method
  53          * calls to make on the newly created object before returning it. This
  54          * pattern is often known as "setter injection". The value of this key is
  55          * expected to be an associative array with method names as keys and
  56          * argument lists as values. The argument list will be expanded (or not)
  57          * in the same way as the 'args' key for the main object.
  58          *
  59          * @param array $spec Object specification
  60          * @return object
  61          * @throws InvalidArgumentException when object specification does not
  62          * contain 'class' or 'factory' keys
  63          * @throws ReflectionException when 'args' are supplied and 'class'
  64          * constructor is non-public or non-existent
  65          */
  66         public static function getObjectFromSpec( $spec ) {
  67                 $args = isset( $spec['args'] ) ? $spec['args'] : array();
  68                 $expandArgs = !isset( $spec['closure_expansion'] ) ||
  69                         $spec['closure_expansion'] === true;
  70
  71                 if ( $expandArgs ) {
  72                         $args = static::expandClosures( $args );
  73                 }
  74
  75                 if ( isset( $spec['class'] ) ) {
  76                         $clazz = $spec['class'];
  77                         if ( !$args ) {
  78                                 $obj = new $clazz();
  79                         } else {
  80                                 $ref = new ReflectionClass( $clazz );
  81                                 $obj = $ref->newInstanceArgs( $args );
  82                         }
  83                 } elseif ( isset( $spec['factory'] ) ) {
  84                         $obj = call_user_func_array( $spec['factory'], $args );
  85                 } else {
  86                         throw new InvalidArgumentException(
  87                                 'Provided specification lacks both factory and class parameters.'
  88                         );
  89                 }
  90
  91                 if ( isset( $spec['calls'] ) && is_array( $spec['calls'] ) ) {
  92                         // Call additional methods on the newly created object
  93                         foreach ( $spec['calls'] as $method => $margs ) {
  94                                 if ( $expandArgs ) {
  95                                         $margs = static::expandClosures( $margs );
  96                                 }
  97                                 call_user_func_array( array( $obj, $method ), $margs );
  98                         }
  99                 }
 100
 101                 return $obj;
 102         }
 103
 104         /**
 105          * Iterate a list and call any closures it contains.
 106          *
 107          * @param array $list List of things
 108          * @return array List with any Closures replaced with their output
 109          */
 110         protected static function expandClosures( $list ) {
 111                 return array_map( function ( $value ) {
 112                         if ( is_object( $value ) && $value instanceof Closure ) {
 113                                 // If $value is a Closure, call it.
 114                                 return $value();
 115                         } else {
 116                                 return $value;
 117                         }
 118                 }, $list );
 119         }
 120 }