fakerpress / src / functions / container.php

container.php in FakerPress 0.7.2, at src/functions/container.php

284 lines 9.5 KB

Raw Download Zip

1	<?php
2
3	namespace FakerPress;
4
5	use FakerPress\Contracts\Service_Provider;
6	use FakerPress\Contracts\Container;
7
8	/**
9	* Registers a class as a singleton.
10	*
11	* Each call to obtain an instance of this class made using the `make( $slug )` function
12	* will return the same instance; the instances are built just in time (if not passing an
13	* object instance or callback function) and on the first request.
14	* The container will call the class `__construct` method on the class (if not passing an object
15	* or a callback function) and will try to automagically resolve dependencies.
16	*
17	* Example use:
18	*
19	* singleton( 'fakerpress.foo.admin', FakerPress\Foo\Admin::class );
20	*
21	* // some code later...
22	*
23	* // class is built here
24	* make( 'fakerpress.foo.admin' )->do_something();
25	*
26	* Need the class built immediately? Build it and register it:
27	*
28	* singleton( 'fakerpress.foo.admin', new FakerPress\Foo\Admin() );
29	*
30	* // some code later...
31	*
32	* make( 'fakerpress.foo.admin' )->do_something();
33	*
34	* Need a very custom way to build the class? Register a callback:
35	*
36	* singleton( Admin_Class::class, [ FakerPress\Foo\Factory, 'make' ] );
37	*
38	* // some code later...
39	*
40	* make( Admin_Class::class )->do_something();
41	*
42	* Or register the methods that should be called on the object after its construction:
43	*
44	* singleton( FakerPress\Foo\Admin::class, FakerPress\Foo\Admin::class, [ 'hook', 'register' ] );
45	*
46	* // some code later...
47	*
48	* // the `hook` and `register` methods will be called on the built instance.
49	* make( FakerPress\Foo\Admin::class )->do_something();
50	*
51	* The class will be built only once (if passing the class name or a callback function), stored
52	* and the same instance will be returned from that moment on.
53	*
54	* @since 0.6.0
55	*
56	* @param string $slug The human-readable and catchy name of the class.
57	* @param string\|object\|callable $class The full class name or an instance of the class
58	* or a callback that will return the instance of the class.
59	* @param array\|null $after_build_methods An array of methods that should be called on
60	* the built object after the `__construct` method; the methods
61	* will be called only once after the singleton instance
62	* construction.
63	*/
64	function singleton( $slug, $class, array $after_build_methods = null ) {
65	Container::init()->singleton( $slug, $class, $after_build_methods );
66	}
67
68	/**
69	* Registers a class.
70	*
71	* Each call to obtain an instance of this class made using the `make( $slug )` function
72	* will return a new instance; the instances are built just in time (if not passing an
73	* object instance, in that case it will work as a singleton) and on the first request.
74	* The container will call the class `__construct` method on the class (if not passing an object
75	* or a callback function) and will try to automagically resolve dependencies.
76	*
77	* Example use:
78	*
79	* register( 'fakerpress.some', 'FakerPress\Some' );
80	*
81	* // some code later...
82	*
83	* // class is built here
84	* $some_one = make( 'fakerpress.some' )->doSomething();
85	*
86	* // $some_two !== $some_one
87	* $some_two = make( 'fakerpress.some' )->doSomething();
88	*
89	* Need the class built immediately? Build it and register it:
90	*
91	* register( 'fakerpress.admin.class', new Admin_Class() );
92	*
93	* // some code later...
94	*
95	* // $some_two === $some_one
96	* // acts like a singleton
97	* $some_one = make( 'fakerpress.some' )->doSomething();
98	* $some_two = make( 'fakerpress.some' )->doSomething();
99	*
100	* Need a very custom way to build the class? Register a callback:
101	*
102	* register( 'fakerpress.some', array( Some_Factory, 'make' ) );
103	*
104	* // some code later...
105	*
106	* // $some_two !== $some_one
107	* $some_one = make( 'fakerpress.some' )->doSomething();
108	* $some_two = make( 'fakerpress.some' )->doSomething();
109	*
110	* Or register the methods that should be called on the object after its construction:
111	*
112	* singleton( 'fakerpress.admin.class', 'Admin_Class', array( 'hook', 'register' ) );
113	*
114	* // some code later...
115	*
116	* // the `hook` and `register` methods will be called on the built instance.
117	* make( 'fakerpress.admin.class' )->doSomething();
118	*
119	* @since 0.6.0
120	*
121	* @param string $slug The human-readable and catchy name of the class.
122	* @param string\|object\|callable $class The full class name or an instance of the class
123	* or a callback that will return the instance of the class.
124	* @param array\|null $after_build_methods An array of methods that should be called on
125	* the built object after the `__construct` method; the methods
126	* will be called each time after the instance construction.
127	*/
128	function bind( $slug, $class, array $after_build_methods = null ) {
129	Container::init()->bind( $slug, $class, $after_build_methods );
130	}
131
132	/**
133	* Returns a ready to use instance of the requested class.
134	*
135	* Example use:
136	*
137	* singleton( 'fakerpress.plugin', 'FakerPress\Plugin' );
138	*
139	* // some code later...
140	*
141	* make( 'fakerpress.plugin' )->do_something();
142	*
143	* @since 0.6.0
144	*
145	* @param string\|null $slug_or_class Either the slug of a binding previously registered using `singleton` or
146	* `register` or the full class name that should be automagically created or
147	* `null` to get the container instance itself.
148	*
149	* @return mixed\|object\|Container The instance of the requested class. Please note that the cardinality of
150	* the class is controlled registering it as a singleton using `singleton`
151	* or `register`; if the `$slug_or_class` parameter is null then the
152	* container itself will be returned.
153	*/
154	function make( $slug_or_class = null ) {
155	return null === $slug_or_class ? Container::init() : Container::init()->make( $slug_or_class );
156	}
157
158	/**
159	* Registers a value under a slug in the container.
160	*
161	* Example use:
162	*
163	* set_var( 'fakerpress.url', 'http://example.com' );
164	*
165	* @since 0.6.0
166	*
167	* @param string $slug The human-readable and catchy name of the var.
168	* @param mixed $value The variable value.
169	*/
170	function set_var( $slug, $value ) {
171	Container::init()->setVar( $slug, $value );
172	}
173
174	/**
175	* Returns the value of a registered variable.
176	*
177	* Example use:
178	*
179	* set_var( 'fakerpress.url', 'http://example.com' );
180	*
181	* $url = get_var( 'fakerpress.url' );
182	*
183	* @since 0.6.0
184	*
185	* @param string $slug The slug of the variable registered using `set_var`.
186	* @param null $default The value that should be returned if the variable slug
187	* is not a registered one.
188	*
189	* @return mixed Either the registered value or the default value if the variable
190	* is not registered.
191	*/
192	function get_var( $slug, $default = null ) {
193	try {
194	$var = Container::init()->getVar( $slug );
195	} catch ( \InvalidArgumentException $e ) {
196	return $default;
197	}
198
199	return $var;
200	}
201
202	/**
203	* Returns the value of a registered variable.
204	*
205	* Example use:
206	*
207	* set_var( 'fakerpress.url', 'http://example.com' );
208	*
209	* unset_var( 'fakerpress.url' );
210	*
211	* @since 0.6.0
212	*
213	* @param string $slug The slug of the variable registered using `unset_var`.
214	*
215	* @return void
216	*/
217	function unset_var( $slug ) {
218	try {
219	Container::init()->offsetUnset( $slug );
220	} catch ( \Exception $e ) {
221	}
222	}
223
224	/**
225	* Returns the value of a registered variable.
226	*
227	* Example use:
228	*
229	* set_var( 'fakerpress.url', 'http://example.com' );
230	*
231	* isset_var( 'fakerpress.url' );
232	*
233	* @since 0.6.0
234	*
235	* @param string $slug The slug of the variable checked using `isset_var`.
236	*
237	* @return boolean Either the given slug exists.
238	*/
239	function isset_var( $slug ) {
240	return Container::init()->offsetExists( $slug );
241	}
242
243	/**
244	* Registers a service provider in the container.
245	*
246	* Service providers must extend the `Service_Provider` class.
247	*
248	* @see Service_Provider
249	*
250	* @since 0.6.0
251	*
252	* @param string $provider_class
253	*/
254	function register( string $provider_class ): void {
255	Container::init()->register( $provider_class );
256	}
257
258	/**
259	* Returns a lambda function suitable to use as a callback; when called the function will build the implementation
260	* bound to `$classOrInterface` and return the value of a call to `$method` method with the call arguments.
261	*
262	* @since 0.6.0
263	*
264	* @param string $slug A class or interface fully qualified name or a string slug.
265	* @param string $method The method that should be called on the resolved implementation with the
266	* specified array arguments.
267	* @param mixed [$argsN] (optional) Any number of arguments that will be passed down to the Callback
268	*
269	* @return callable A PHP Callable based on the Slug and Methods passed
270	*/
271	function callback( $slug, $method ) {
272	$arguments = func_get_args();
273	$is_empty = 2 === count( $arguments );
274
275	if ( $is_empty ) {
276	$callable = Container::init()->callback( $slug, $method );
277	} else {
278	$callback = Container::init()->callback( 'callback', 'get' );
279	$callable = call_user_func_array( $callback, $arguments );
280	}
281
282	return $callable;
283	}
284