-
Notifications
You must be signed in to change notification settings - Fork 0
Home
The purpose of this package is to standardize data retrieval by key. A container guarantees only a standard interface made for that purpose, and no enumeration, or particular use-case. A container can be used as a base for a map or data object, such as a model or scope context.
This package complies with dhii/dhii, which includes and supersedes PSR-1, PSR-2, PSR Naming Conventions where applicable, those described at keepachangelog.com, and SemVer. This means that it is readable, familiar, structured, clear, reliable.
This package also extends the PSR-11 standard to make it more useful, and to increase interface segregation and granularity.
There are many classes that allow retrieval of data by key, the most prominent of which are in the PSR-11 standard. There many similar implementations, such as Magento\Framework\DataObject, or PhpCollection\AbstractMap. Such close resemblance prompts for a unified interface.
- Check for and retrieve data using a familiar approach.
- Massively increase interoperability for your data containers.
- Write more generic, versatile, yet safe, predictable, and SOLID code.
In general, abstraction brings many benefits to the table, some of which are described in the wiki for dhii/wp-i18n. The particular benefits of this package is that code which relies on it can start treating all standard-compliant data containers in the same way, and this can greatly increase interoperability. So much so that code which retrieves data by key could be able to work with Symfony models in the same way as Joomla models, and in the same way as Magento models, or any other models, maps, or containers, including DI containers, such as dhii/di or pimple/pimple. In fact, it was the container standard targeted for DI containers, PSR-11, which serves as both the base and the inspiration for this package. It was quickly obvious that this approach is far too useful to be used only for DI containers; and at the same its monolithic nature prevented it from reaching its full potential.
Another benefit is that greater interface segregation can be achieved, allowing simpler implementations targeted for more narrow purposes. This means that vendors do not have to implement a whole model or map logic, which may imply some persistence, sorting, writability etc, just to be able to provide data in a structured and predictable way. Being relieved of the necessity to implement methods which are useless for the current scope, vendors or application authors can achieve their tasks more quickly, reliably, and with less effort.
This wiki mentions segregation and granularity quite a few times. This is because Psr\Container\ContainerInterface declares both get() and has() methods. And it's fair to assume that something which can retrieve a value can also check for it; but not the other way around. So, something that only wants to allow checking for a value by key, but not retrieval of that value, has no way to be interoperable and standards-compliant when only using the original PSR-11. This package solves that problem by declaring HasCapableInterface, which is separate from ContainerInterface.
Finally, this package contains interfaces for exceptions, extending the PSR-11 exceptions to make them more helpful - the former ones seem to serve merely as indicators of the type of problem they represent, but do not provide any additional data. As such, ContainerExceptionInterface is aware of the container, allowing the exception handling logic to know which container caused the problem without being aware of which container implementation is being used, and without having had any prior reference to it - something that was previously impossible.
The NotFoundExceptionInterface interface extends that, and adds the getDataKey() method, which allows the exception handlers to be programmatically aware of the key that is not found.
Data retrieval by key happens everywhere in Dhii code. Many times, it is the "glue code", or service providers, which use DI containers in this way. Other cases include retrieval of data from data objects for rendering.
One of the standards compatible with this one is the new dhii/config-interface, which allows structured retrieval of config values, as well as the ability to traverse the config tree, such as for copying or merging, and other features. Implementing ContainerInterface allows config instances to be used as any other key-value map, and retrieve configuration by key (or path, if hierarchical), similarly to how you would do it with data objects or DI containers.
Creating a whole implementation from scratch can get tedious, and if every compatible implementation would do that, it would create a lot of code duplication across unrelated packages. To aid with this, dhii/container-base provides some concrete implementations for exceptions, and a base abstract container implementation which can throw them, thus implementing the most common functionality in an abstract way. That package is based on dhii/container-abstract; the latter provides some common abstract functionality, and can be useful to those who wish to create a principally new standards-compliant implementation of a data container.