README.md
1Wikimedia ObjectFactory
2=======================
3
4Construct objects from configuration instructions.
5
6It can be used statically, or as a service wrapping a PSR-11 service container
7for lazy instantiation of objects with dependency injection.
8
9Specification array
10-------------------
11
12Contents of the specification array are as follows:
13
14 'factory' => callable,
15 'class' => string,
16
17The specification array must contain either a 'class' key with string value
18that specifies the class name to instantiate or a 'factory' key with a
19callable (is_callable() === true). If both are passed, 'factory' takes
20precedence but an InvalidArgumentException will be thrown if the resulting
21object is not an instance of the named class.
22
23 'args' => array,
24 'closure_expansion' => bool, // default true
25 'spec_is_arg' => bool, // default false
26 'services' => string[], // default empty
27
28The 'args' key, if provided, specifies arguments to pass to the constructor/callable.
29Values in 'args' which are Closure instances will be expanded by invoking
30them with no arguments before passing the resulting value on to the
31constructor/callable. This can be used to pass live objects to the
32constructor/callable. This behavior can be suppressed by adding
33closure_expansion => false to the specification.
34
35If 'spec_is_arg' => true is in the specification, 'args' is ignored. The
36entire spec array is passed to the constructor/callable instead.
37
38If 'services' is supplied and non-empty (and a service container is available),
39the named services are requested from the PSR-11 service container and
40prepended before 'args'.
41
42If any extra arguments are passed in the options to getObjectFromSpec() or
43createObject(), these are prepended before the 'services' and 'args'.
44
45 'calls' => array
46
47The specification may also contain a 'calls' key that describes method
48calls to make on the newly created object before returning it. This
49pattern is often known as "setter injection". The value of this key is
50expected to be an associative array with method names as keys and
51argument lists as values. The argument list will be expanded (or not)
52in the same way as the 'args' key for the main object.
53
54Note these calls are not passed the extra arguments.
55
56Installation
57------------
58
59```
60$ composer require wikimedia/object-factory
61```
62
63Usage
64-----
65
66```
67<?php
68
69$specs = [
70 // Simple constructor based injection
71 'testDB' => [
72 'class' => PDO::class,
73 'args' => [
74 'mysql:dbname=testdb;host=127.0.0.1',
75 'dbuser',
76 'dbpass',
77 ],
78 ],
79];
80
81$db = ObjectFactory::getObjectFromSpec( $specs['testDB'] ):
82```
83
84License
85-------
86Wikimedia ObjectFactory is licensed under the GNU General Public License,
87version 2 and any later version (GPL-2.0-or-later). See the
88[`COPYING`](COPYING) file for more details.
89