cookiebot / addons / lib / ioc / container-interop / container-interop / docs / ContainerInterface-meta.md

ContainerInterface-meta.md in Cookiebot by Usercentrics – Automatic Cookie Banner for GDPR/CCPA & Google Consent Mode 3.11.1, at addons/lib/ioc/container-interop/container-interop/docs/ContainerInterface-meta.md

115 lines 5.2 KB

Raw Download Zip

1	# ContainerInterface Meta Document
2
3	## Introduction
4
5	This document describes the process and discussions that lead to the `ContainerInterface`.
6	Its goal is to explain the reasons behind each decision.
7
8	## Goal
9
10	The goal set by `ContainerInterface` is to standardize how frameworks and libraries make use of a
11	container to obtain objects and parameters.
12
13	By standardizing such a behavior, frameworks and libraries using the `ContainerInterface`
14	could work with any compatible container.
15	That would allow end users to choose their own container based on their own preferences.
16
17	It is important to distinguish the two usages of a container:
18
19	- configuring entries
20	- fetching entries
21
22	Most of the time, those two sides are not used by the same party.
23	While it is often end users who tend to configure entries, it is generally the framework that fetch
24	entries to build the application.
25
26	This is why this interface focuses only on how entries can be fetched from a container.
27
28	## Interface name
29
30	The interface name has been thoroughly discussed and was decided by a vote.
31
32	The list of options considered with their respective votes are:
33
34	- `ContainerInterface`: +8
35	- `ProviderInterface`: +2
36	- `LocatorInterface`: 0
37	- `ReadableContainerInterface`: -5
38	- `ServiceLocatorInterface`: -6
39	- `ObjectFactory`: -6
40	- `ObjectStore`: -8
41	- `ConsumerInterface`: -9
42
43	[](https://github.com/container-interop/container-interop/wiki/%231-interface-name:-VoteFull results of the vote](https://github.com/container-interop/container-interop/wiki/%231-interface-name:-Vote](https://github.com/container-interop/container-interop/wiki/%231-interface-name:-Vote)
44
45	The complete discussion can be read in [](https://github.com/container-interop/container-interop/issues/1the issue #1](https://github.com/container-interop/container-interop/issues/1](https://github.com/container-interop/container-interop/issues/1).
46
47	## Interface methods
48
49	The choice of which methods the interface would contain was made after a statistical analysis of existing containers.
50	The results of this analysis are available [](https://gist.github.com/mnapoli/6159681in this document](https://gist.github.com/mnapoli/6159681](https://gist.github.com/mnapoli/6159681).
51
52	The summary of the analysis showed that:
53
54	- all containers offer a method to get an entry by its id
55	- a large majority name such method `get()`
56	- for all containers, the `get()` method has 1 mandatory parameter of type string
57	- some containers have an optional additional argument for `get()`, but it doesn't have the same purpose between containers
58	- a large majority of the containers offer a method to test if it can return an entry by its id
59	- a majority name such method `has()`
60	- for all containers offering `has()`, the method has exactly 1 parameter of type string
61	- a large majority of the containers throw an exception rather than returning null when an entry is not found in `get()`
62	- a large majority of the containers don't implement `ArrayAccess`
63
64	The question of whether to include methods to define entries has been discussed in
65	[](https://github.com/container-interop/container-interop/issues/1issue #1](https://github.com/container-interop/container-interop/issues/1](https://github.com/container-interop/container-interop/issues/1).
66	It has been judged that such methods do not belong in the interface described here because it is out of its scope
67	(see the "Goal" section).
68
69	As a result, the `ContainerInterface` contains two methods:
70
71	- `get()`, returning anything, with one mandatory string parameter. Should throw an exception if the entry is not found.
72	- `has()`, returning a boolean, with one mandatory string parameter.
73
74	### Number of parameters in `get()` method
75
76	While `ContainerInterface` only defines one mandatory parameter in `get()`, it is not incompatible with
77	existing containers that have additional optional parameters. PHP allows an implementation to offer more parameters
78	as long as they are optional, because the implementation does satisfy the interface.
79
80	This issue has been discussed in [](https://github.com/container-interop/container-interop/issues/6issue #6](https://github.com/container-interop/container-interop/issues/6](https://github.com/container-interop/container-interop/issues/6).
81
82	### Type of the `$id` parameter
83
84	The type of the `$id` parameter in `get()` and `has()` has been discussed in
85	[](https://github.com/container-interop/container-interop/issues/6issue #6](https://github.com/container-interop/container-interop/issues/6](https://github.com/container-interop/container-interop/issues/6).
86	While `string` is used in all the containers that were analyzed, it was suggested that allowing
87	anything (such as objects) could allow containers to offer a more advanced query API.
88
89	An example given was to use the container as an object builder. The `$id` parameter would then be an
90	object that would describe how to create an instance.
91
92	The conclusion of the discussion was that this was beyond the scope of getting entries from a container without
93	knowing how the container provided them, and it was more fit for a factory.
94
95	## Contributors
96
97	Are listed here all people that contributed in the discussions or votes, by alphabetical order:
98
99	- [](https://github.com/AmyStephenAmy Stephen](https://github.com/AmyStephen](https://github.com/AmyStephen)
100	- [](https://github.com/moufmoufDavid Négrier](https://github.com/moufmouf](https://github.com/moufmouf)
101	- [](https://github.com/dongilbertDon Gilbert](https://github.com/dongilbert](https://github.com/dongilbert)
102	- [](https://github.com/judgejJason Judge](https://github.com/judgej](https://github.com/judgej)
103	- [](https://github.com/jeremeamiaJeremy Lindblom](https://github.com/jeremeamia](https://github.com/jeremeamia)
104	- [](https://github.com/OcramiusMarco Pivetta](https://github.com/Ocramius](https://github.com/Ocramius)
105	- [](https://github.com/mnapoliMatthieu Napoli](https://github.com/mnapoli](https://github.com/mnapoli)
106	- [](https://github.com/pmjonesPaul M. Jones](https://github.com/pmjones](https://github.com/pmjones)
107	- [](https://github.com/shochdoerferStephan Hochdörfer](https://github.com/shochdoerfer](https://github.com/shochdoerfer)
108	- [](https://github.com/taylorotwellTaylor Otwell](https://github.com/taylorotwell](https://github.com/taylorotwell)
109
110	## Relevant links
111
112	- [](https://github.com/container-interop/container-interop/blob/master/src/Interop/Container/ContainerInterface.php`ContainerInterface.php`](https://github.com/container-interop/container-interop/blob/master/src/Interop/Container/ContainerInterface.php](https://github.com/container-interop/container-interop/blob/master/src/Interop/Container/ContainerInterface.php)
113	- [](https://github.com/container-interop/container-interop/issues?labels=ContainerInterface&milestone=&page=1&state=closedList of all issues](https://github.com/container-interop/container-interop/issues?labels=ContainerInterface&milestone=&page=1&state=closed](https://github.com/container-interop/container-interop/issues?labels=ContainerInterface&milestone=&page=1&state=closed)
114	- [](https://github.com/container-interop/container-interop/wiki/%231-interface-name:-VoteVote for the interface name](https://github.com/container-interop/container-interop/wiki/%231-interface-name:-Vote](https://github.com/container-interop/container-interop/wiki/%231-interface-name:-Vote)
115