You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add comprehensive documentation for FastForward Container
- Introduced API reference documentation including core concepts, factories, providers, and exceptions.
- Added compatibility section detailing runtime compatibility and integration guidance.
- Enhanced examples for basic usage, frameworks integration, feature toggles, and testing with providers.
- Created FAQ section addressing common questions and best practices for new users.
- Expanded getting started guide with installation instructions and a quickstart tutorial.
- Updated links section to include dependencies and related standards.
- Improved providers documentation with detailed descriptions of built-in providers and their usage.
Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
Copy file name to clipboardExpand all lines: docs/advanced/container-helper.rst
+56-48Lines changed: 56 additions & 48 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,24 +1,31 @@
1
1
Container Helper Function
2
2
========================
3
3
4
-
The ``container()`` helper is the main entry point for building a fully-featured, autowire-enabled container in FastForward Container. It is designed to be flexible and convenient, supporting multiple initialization patterns and advanced composition.
4
+
The ``container()`` helper is the main entry point for building a fully-featured,
5
+
autowire-enabled container in FastForward Container. It is intentionally flexible so
You can pass any combination of the following as arguments:
16
+
Supported initializers
17
+
----------------------
15
18
16
-
- **ConfigInterface**: A configuration object (for advanced setups)
17
-
- **Psr\Container\ContainerInterface**: Any PSR-11 compatible container
18
-
- **ServiceProviderInterface**: Any service provider
19
-
- **string**: The fully qualified class name of a ConfigInterface, ServiceProviderInterface, or PSR-11 container (it will be instantiated automatically)
All arguments are optional and variadic. You can mix and match them as needed.
28
+
All arguments are optional and variadic. You can mix them freely.
22
29
23
30
How It Works
24
31
------------
@@ -30,18 +37,17 @@ How It Works
30
37
- If it's a string, the class is instantiated and then resolved as above.
31
38
- Any unsupported type throws an InvalidArgumentException.
32
39
2. All resolved containers are appended to an AggregateContainer.
33
-
3. If a ConfigContainer is present, it may provide nested initializers (via a special config key), which are also resolved and appended.
40
+
3. If a ConfigContainer is present, it may provide nested initializers, which are also resolved and appended.
34
41
4. The final result is always an AutowireContainer wrapping the aggregate.
35
42
36
-
Supported Initializers
37
-
----------------------
43
+
Resolution order
44
+
----------------
38
45
39
-
- ``ConfigInterface``
40
-
- ``Psr\Container\ContainerInterface``
41
-
- ``ServiceProviderInterface``
42
-
- ``string`` (class name of any of the above)
46
+
The aggregate container resolves services from left to right. In practice, this means:
43
47
44
-
If you pass a string, the function will instantiate the class and treat it as if you had passed the object directly.
48
+
- earlier initializers take precedence over later initializers when both can resolve the same ID
49
+
- explicit registrations win before autowiring is attempted
50
+
- ``container($tests, $defaults)`` is a simple override pattern for tests and local development
45
51
46
52
Examples
47
53
--------
@@ -51,11 +57,12 @@ Basic usage with a service provider:
51
57
.. code-block:: php
52
58
53
59
use FastForward\Container\ServiceProvider\ArrayServiceProvider;
54
-
use FastForward\Container\container;
60
+
use function FastForward\Container\container;
55
61
56
62
$provider = new ArrayServiceProvider([
57
63
'foo' => fn() => new FooService(),
58
64
]);
65
+
59
66
$container = container($provider);
60
67
$foo = $container->get('foo');
61
68
@@ -73,53 +80,54 @@ Composing multiple providers and containers:
73
80
$containerB = container(ProviderB::class);
74
81
$main = container($containerA, $containerB);
75
82
76
-
Using a config object:
83
+
Using a config object with nested providers:
77
84
78
85
.. code-block:: php
79
86
80
-
$config = new MyConfig();
87
+
use FastForward\Config\ArrayConfig;
88
+
use FastForward\Container\ContainerInterface;
89
+
use FastForward\Container\ServiceProvider\ArrayServiceProvider;
90
+
91
+
$config = new ArrayConfig([
92
+
'app' => [
93
+
'name' => 'FastForward',
94
+
],
95
+
ContainerInterface::class => [
96
+
new ArrayServiceProvider([
97
+
Banner::class => static fn($container): Banner => new Banner(
98
+
$container->get('config.app.name'),
99
+
),
100
+
]),
101
+
],
102
+
]);
103
+
81
104
$container = container($config);
105
+
$banner = $container->get(Banner::class);
82
106
83
107
Error Handling
84
108
--------------
85
109
86
-
If you pass an unsupported type, or a string that does not correspond to a valid class, the function will throw an InvalidArgumentException.
87
-
88
-
89
-
Advanced: Using Config to Register Providers
90
-
--------------------------------------------
110
+
If you pass an unsupported value, or a string that does not correspond to a valid class,
111
+
the function throws ``InvalidArgumentException``.
91
112
92
-
If you use a ConfigContainer (from the `fast-forward/config` library), it can provide a special config key (``ConfigContainer::ALIAS.ContainerInterface::class``) containing an array of service providers or containers. The container() helper will automatically resolve and append each of these to the AggregateContainer.
113
+
Configuration note
114
+
------------------
93
115
94
-
This allows you to register providers or containers via configuration, making your setup more modular and dynamic.
116
+
When you use ``fast-forward/config``, keep this distinction in mind:
95
117
96
-
Example:
118
+
- raw config uses ``FastForward\Container\ContainerInterface::class`` as the key for nested providers
119
+
- the wrapped ``ConfigContainer`` exposes normal values through ``config.*`` IDs
97
120
98
-
.. code-block:: php
99
-
100
-
use FastForward\Config\ArrayConfig;
101
-
use FastForward\Container\ServiceProvider\ArrayServiceProvider;
102
-
use FastForward\Container\container;
103
-
use FastForward\Container\ContainerInterface;
104
-
105
-
$config = new ArrayConfig([
106
-
ContainerInterface::class => [
107
-
new ArrayServiceProvider([
108
-
'foo' => fn() => 'bar',
109
-
]),
110
-
],
111
-
]);
112
-
113
-
$container = container($config);
114
-
$foo = $container->get('foo'); // 'bar'
115
-
116
-
In this example, the config provides the special key for providers (using the fully qualified class name as the key). The container() helper will extract and register all providers listed there, just as if you had passed them directly.
121
+
The helper internally asks the ``ConfigContainer`` for
122
+
``config.FastForward\Container\ContainerInterface`` and the config container translates that
123
+
into the raw config key for you.
117
124
118
125
Return Value
119
126
------------
120
127
121
-
122
-
The function always returns an ``AutowireContainer`` that wraps an ``AggregateContainer`` composed of all resolved sources. This means you get autowiring and aggregation out of the box, regardless of how you initialize the container.
128
+
The function always returns an ``AutowireContainer`` that wraps an ``AggregateContainer``
129
+
composed of all resolved sources. This gives you autowiring and aggregation out of the box,
130
+
regardless of how you initialize the container.
123
131
124
132
**Autowiring is powered internally by `PHP-DI <https://php-di.org/>`_.**
0 commit comments