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.
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.
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
22 * Construct objects from configuration instructions.
24 * @copyright © 2014 Wikimedia Foundation and contributors
29 * Instantiate an object based on a specification array.
31 * The specification array must contain a 'class' key with string value
32 * that specifies the class name to instantiate or a 'factory' key with
33 * a callable (is_callable() === true). It can optionally contain
34 * an 'args' key that provides arguments to pass to the
35 * constructor/callable.
37 * Values in the arguments collection which are Closure instances will be
38 * expanded by invoking them with no arguments before passing the
39 * resulting value on to the constructor/callable. This can be used to
40 * pass IDatabase instances or other live objects to the
41 * constructor/callable. This behavior can be suppressed by adding
42 * closure_expansion => false to the specification.
44 * The specification may also contain a 'calls' key that describes method
45 * calls to make on the newly created object before returning it. This
46 * pattern is often known as "setter injection". The value of this key is
47 * expected to be an associative array with method names as keys and
48 * argument lists as values. The argument list will be expanded (or not)
49 * in the same way as the 'args' key for the main object.
51 * @param array $spec Object specification
53 * @throws InvalidArgumentException when object specification does not
54 * contain 'class' or 'factory' keys
55 * @throws ReflectionException when 'args' are supplied and 'class'
56 * constructor is non-public or non-existent
58 public static function getObjectFromSpec( $spec ) {
59 $args = isset( $spec['args'] ) ?
$spec['args'] : [];
60 $expandArgs = !isset( $spec['closure_expansion'] ) ||
61 $spec['closure_expansion'] === true;
64 $args = static::expandClosures( $args );
67 if ( isset( $spec['class'] ) ) {
68 $clazz = $spec['class'];
72 $obj = static::constructClassInstance( $clazz, $args );
74 } elseif ( isset( $spec['factory'] ) ) {
75 $obj = call_user_func_array( $spec['factory'], $args );
77 throw new InvalidArgumentException(
78 'Provided specification lacks both factory and class parameters.'
82 if ( isset( $spec['calls'] ) && is_array( $spec['calls'] ) ) {
83 // Call additional methods on the newly created object
84 foreach ( $spec['calls'] as $method => $margs ) {
86 $margs = static::expandClosures( $margs );
88 call_user_func_array( [ $obj, $method ], $margs );
96 * Iterate a list and call any closures it contains.
98 * @param array $list List of things
99 * @return array List with any Closures replaced with their output
101 protected static function expandClosures( $list ) {
102 return array_map( function ( $value ) {
103 if ( is_object( $value ) && $value instanceof Closure
) {
104 // If $value is a Closure, call it.
113 * Construct an instance of the given class using the given arguments.
115 * PHP's `call_user_func_array()` doesn't work with object construction so
116 * we have to use other measures. Starting with PHP 5.6.0 we could use the
117 * "splat" operator (`...`) to unpack the array into an argument list.
118 * Sadly there is no way to conditionally include a syntax construct like
119 * a new operator in a way that allows older versions of PHP to still
120 * parse the file. Instead, we will try a loop unrolling technique that
121 * works for 0-10 arguments. If we are passed 11 or more arguments we will
122 * take the performance penalty of using
123 * `ReflectionClass::newInstanceArgs()` to construct the desired object.
125 * @param string $clazz Class name
126 * @param array $args Constructor arguments
127 * @return mixed Constructed instance
129 public static function constructClassInstance( $clazz, $args ) {
130 // $args should be a non-associative array; show nice error if that's not the case
131 if ( $args && array_keys( $args ) !== range( 0, count( $args ) - 1 ) ) {
132 throw new InvalidArgumentException( __METHOD__
. ': $args cannot be an associative array' );
135 // TODO: when PHP min version supported is >=5.6.0 replace this
136 // with `return new $clazz( ... $args );`.
138 switch ( count( $args ) ) {
143 $obj = new $clazz( $args[0] );
146 $obj = new $clazz( $args[0], $args[1] );
149 $obj = new $clazz( $args[0], $args[1], $args[2] );
152 $obj = new $clazz( $args[0], $args[1], $args[2], $args[3] );
156 $args[0], $args[1], $args[2], $args[3], $args[4]
161 $args[0], $args[1], $args[2], $args[3], $args[4],
167 $args[0], $args[1], $args[2], $args[3], $args[4],
173 $args[0], $args[1], $args[2], $args[3], $args[4],
174 $args[5], $args[6], $args[7]
179 $args[0], $args[1], $args[2], $args[3], $args[4],
180 $args[5], $args[6], $args[7], $args[8]
185 $args[0], $args[1], $args[2], $args[3], $args[4],
186 $args[5], $args[6], $args[7], $args[8], $args[9]
190 // Fall back to using ReflectionClass and curse the developer
191 // who decided that 11+ args was a reasonable method
193 $ref = new ReflectionClass( $clazz );
194 $obj = $ref->newInstanceArgs( $args );