Download the PHP package pyrsmk/chernozem without Composer

Chernozem 4.2.1

Chernozem is an advanced dependency injection container based on ArrayAccess. It has been primarily designed to be extended by another class, so it takes care of any option for you. But it can also be used as a simple container.

Concretely, Chernozem can register any value you want and create services. Services are simple closures, used to initialize objects and return their instance. It's really useful for, per example, loading a logger when we need it, with all required options and dependencies it could need.

If you want to learn more about dependency injection, Fabien Potencier has written an article about that : http://fabien.potencier.org/article/11/what-is-dependency-injection.

Features

• interoperability with container-interop
• factory closures
• inflectors
• delegate containers
• service providers
• type hinting
• and more...

Note about the v4

Chernozem has been completely rewritten and the API has changed. Please read the whole documentation before upgrading from v3.

Installing

Basics

Let's see quickly how it works :

Alternatively, and for interoperability, you can access to Chernozem with this API :

Or also with this API :

You can instantiate Chernozem with some values too :

You can add values to the container without specifying keys (like with a normal array) :

Chernozem also supports objects as keys :

If you need to clear all your container values, do :

Factory closures

With factory closures you can create services. The factory() method creates a service that will always return a new instance of the service :

The service() method creates a service that will return the same instance of itself :

Service providers

Service providers are a way to organize and reuse your services with classes. Let's see how we write a service provider :

Service providers are run directly when they are registered, with :

Type hinting

Type hinting is a cool feature of Chernozem that let you define the type of a value in the container. It avoids issues in your application because it could happen that a wrong type is set.

The following basic types are supported :

• boolean/bool
• integer/int
• float/double
• string
• array
• any class name

Read only values

You can mark your values as read only if needed with :

Inflectors

All previous features are available thanks to inflectors. Inflectors are a way to alter a value when it's set or got. Note that setter inflectors are usually used for data validation, and getter inflectors for data filtering. For the next example, let's say we have previously set some random service that we don't want to be overwritten further in our application, and we want to run some actions each time the service is retrieved :

Now, setting 'foo_service' will throw an exception and each time 'foo_service' is retrieved, two actions will be run on our service. It's that simple!

Delegate and composite container

A delegate container is a container that will be used to load dependencies for services. You may see that factory() and service() pass Chernozem as parameter. It's used for the service to load some dependencies on the container. But in big applications, you could deal with many different containers and your dependencies could be on another container than Chernozem.

If you have a lot of containers to manage,, Chernozem has a Composite class to take care of that :

Now that all your containers are registered, you can get a value as always :

Calling foo on the composite class will get the first foo value found in the registered containers. You can verify if a key exist too :

Note that the Composite class is based on container-interop, and it also supports a delegate() method so you can chain things, if needed.

Loops

Chernozem container also implements Iterator and Countable. That means that you can iterate over the container and count how many elements are in it.

Alternative ways to get data

You can retrieve all container values with :

If you need to get a raw value that has not been modified by inflectors, like the base closure of a service, call raw() :

Chaining arrays

You can't chain arrays to modify or retrieve a value with Chernozem, this is due to a PHP limitation with ArrayAccess. The basic way to handle this case is :

But to simplify this, you can declare a Chernozem\Container object instead of an array as your container value, then you'll be able to chain things :

Last notes

If you want to overwrite a factory closure (created with factory() or service()), you must unset the value before setting it :

License

Chernozem is published under the MIT license.