includes/libs/ObjectFactory.php

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