Download the PHP package kelvinmo/lightcontainer without Composer

LightContainer

LightContainer is a simple PSR-11 compliant dependency injection container that supports autowiring.

Table of contents

• Requirements
• Installation
• Basic Usage
• Configuration
  • Introduction
  • Instantiation options
  • Aliases
  • Constructor arguments
  • Setter injection
  • Modifying resolved instances
  • Shared instances
  • Options for autowired resolvers
  • Global aliases
  • Multiple shared instances
  • Custom instantiation
  • Storing arbitrary values
  • Configuring services
  • Loading configurations
• Reference
  • Resolvers
  • Autowiring
  • Instantiation options reference
• Licence

Requirements

• PHP 7.2 or later

Installation

You can install via Composer.

Basic Usage

Consider the following set of classes:

Normally, if you want to create C, you will need to do the following:

However, with LightContainer you can do this:

Note that absolutely no configuration of the container is required. LightContainer figures out the dependencies based on the type hints provided by the constructor parameters, and then configures itself to create the necessary objects. This is autowiring.

Further details on how autowiring works can be found in the reference.

Configuration

Introduction

You can configure the container through the set method. This method can be called with up to two parameters: a string entry identifier, and an optional value. The main ways you can use this method is used to configure the container are set out in this section, with further details can be found in the reference section below.

Instantiation options

You can set instantiation options for a particular class by calling the set method with the name of the class. This returns a class resolver object, which then allows you to specify options.

Multiple options can be set by chaining up the methods.

Certain instantiation options can be set using attributes.

Instantiation options are cleared every time you call the set method on the container object. To set additional options on the same resolver, use the getResolver method to retrieve the existing resolver.

Aliases

Consider the following declarations:

D cannot be instantiated by autowiring as FooInterface is an interface. We need to specify which concrete class that implements the interface we want. We can do this by using the alias method on the resolver.

You can set multiple aliases with a single call by passing an array.

Aliases can refer to other aliases. In the example below, when the container looks for FooInterface, it finds FooInterfaceImpl as an alias, but that in turn references FooInterfaceSubclass. In the end, FooInterfaceSubclass is created. It can also be seen that aliases can be made for classes as well as interfaces.

If you want to define an alias applicable for all classes in the container, consider using a global alias.

Constructor arguments

Consider the following set of classes:

G cannot be instantiated by autowiring as we need to, as a minimum, specify $host. We can do this by using the args method on the resolver.

The args method can only be used to specify parameters that:

• do not have a type hint; or
• have a type hint for an internal type (e.g. int, string, bool); or
• for PHP 8, have a type hint that is a union type.

Other parameters (i.e. those with type hints for classes or interfaces) are ignored when processing the args method. To manipulate how these parameters are treated, use aliases or global aliases.

There may be times where you need to use something from the container as an argument. This may occur if the parameter in the declaration is not type hinted (and so you can't use alias), or if you want to specify a particular named instance. In these cases you will need to wrap the entry identifier with Container::ref().

Setter injection

In addition to dependency injection via the constructor, LightContainer also supports injecting dependencies via setter methods. Consider this declaration:

To get the container to call setA to inject A whenever J is created, use the call method to specify the method to call. Autowiring works in the same way as for constructor injection.

The call method also takes additional arguments, which will be passed on to the setter method. The rules for specifying additional arguments are the same as for constructors. In addition, global aliases are also resolved in the same way as for constructor injection.

NOTE. Aliases apply to the constructor and all setter methods. You cannot define aliases that only applies to a particular setter method.

Modifying resolved instances

In addition to setter injection, LightContainer supports other forms of modifying the resolved object before passing it back to the caller.

To do this, create an instance of a class that implements LightContainer\InstanceModifierInterface, then pass it to the container using the modify method.

Shared instances

There may be times where you want the same instance of a class to be returned by the container no matter how many times it is resolved. This may be the case if the object is meant to be used as a singleton.

To do this, call the shared method on the resolver.

You can also switch off this behaviour by calling shared(false). However, this only works if the shared instance has not been created (i.e. if get hasn't been called). Otherwise this will throw an exception.

You can also set this option using the LightContainer\Attributes\Shared attribute:

Options for autowired resolvers

Autowired resolvers are created automatically by the container as part of the autowiring process. As autowired resolvers do not have an explicit entry in the container, they inherit the instantiation options for the immediate ancestor class that have an entry in the container.

For example, in the declaration below, the resolver for N is autowired as there is no explicit entry in the container for N. Because L is an ancestor class for N and it has an entry in the container, N inherits all the instantiation options from L.

To control this behaviour, call propagate(false) on the resolver. This will stop instantiation options from being propagated to autowired resolvers created for its subclasses. For example, in the example below, N is an autowired resolver, but does not inherit the options from L because propagate for L is set to false. Therefore L retains the default behaviour of not creating shared instances.

You can also set this option using the LightContainer\Attributes\Propagate attribute:

To set instantiation options for all autowired resolvers, you can use the special wildcard resolver *.

Global aliases

Instead of defining aliases at the class level, you can define a global alias, which applicable for all classes created by the container. This can be done by calling the set method with the name of the class or interface to be replaced in the first argument, and the name of the concrete class as the second argument.

Note that the class or interface does not actually need to exist. LightContainer only checks whether the first argument only contains characters that can be used as the fully qualified name of a type (i.e. including the namespace), and if it does, it treats the entry as a global alias. Otherwise it treats the entry as a named instance.

If an alias is also defined at the class level, that definition takes precedence over the global alias.

Unlike aliases defined at the class level, you can set instantiation options for global aliases. These are applied to objects instantiated by referring to the identifier of the global alias instead of the concrete class. The following instantiation options are supported:

• alias (additional class aliases)
• args (constructor arguments)
• call (setters)
• shared (shared instances)

Instantiation options specified in the global alias takes precedence over the options defined for the concrete class.

Multiple shared instances

The shared instantiation option will provide a single shared instance of a class for the entire container. However, you may want to have multiple instances of the same class that are shared across the container.

Named instances are simply a special kind of global aliases, so they can be used anywhere where an alias is accepted. In particular, they are injected into constructors and setter methods using alias, not args.

Furthermore, because named instances are simply a special kind of global aliases, you can set instantiation options for them (other than shared).

Custom instantiation

Instead of using LightContainer's default instantiation function with autowiring, you can specify a custom factory function to create objects of a particular class. This is done by calling set method with a callable pointing to the factory function as the second argument.

The container is passed on as the first parameter to the factory function.

Instantiation options are not available to custom factory functions. Named instances are also not available, as sharing is not supported for factory functions. Calls to named instances will simply result in the factory function being called, which may result in a different instance of the object being returned.

Storing arbitrary values

You can store arbitrary values in the container by calling the set method with a non-string, non-callable value as the second argument.

It is recommended that you use an identifier that cannot be confused with a class name (e.g. by adding an invalid character for a class name, like @ in the example above).

WARNING. If you want to store null, a string or a callable, you will need to wrap it with using Container::value(). Otherwise LightContainer will treat it as a global alias or a custom instantiation function.

Configuring services

In certain situations, concrete classes are used to implement services, which are defined using interfaces. Containers are then used to link the services to their implementations.

Services are identified by either:

• using the LightContainer\Attributes\Service attribute; or
• extending LightContainer\ServiceInterface.

Instead of calling the set method for each service separately, you can call the populate method on the concrete class. This method uses reflection to determine which services the class implements, and then creates container entries accordingly.

Loading configurations

Instead of configuring the container programmatically, you can also load a pre-defined configuration directly into the container using the load method. This method takes the container configuration as a plain PHP array, which you can populate using whichever method you want (e.g. loading from a JSON or YAML file).

See the configuration format documentation for details on how the configuration array should be structured. Note that only a subset of LightContainer's features are supported by this format.

Reference

Resolvers

At its core, LightContainer stores a mapping between an entry identifier and a resolver. A resolver is an object that implements LightContainer\Resolvers\ResolverInterface, which the container uses to resolve to an object or some other value whenever the get method is called.

The main kind of resolver is a class resolver, which resolves to an object by instantiating it from the specified class. Other key kinds of resolvers include a reference resolver, which looks up another entry in the container, and a value resolver, which simply returns a specified value.

The set method takes the string entry identifier and the specified value, creates and registers a resolver, and then returns it to the user. The kind of resolver the method creates depends on the format of the entry identifier, and the type of value that is specified. These are set out in the table below.

The class resolver returned for * is a special kind of class resolver. It cannot be called to resolve to an actual object.

Autowiring

Autowiring works by using PHP reflection to examine the parameters of the constructor (or setter method). If any parameter has a type hint, and the hinted type is not a built-in literal type, it looks up the container to see if there is an existing entry with the type as the entry identifier. If an entry does not exist, but the specified type is a class and the class exists, the container then creates a class resolver (the autowired resolver) for that type automatically. The instantiation options for this autowired resolver are set based on the propagation rules described above.

Note that when injecting parameters into the constructor or setter method, the nullable market (?) and default value declarations are initially ignored. The container will try to create and inject an instance of a particular type even it is declared nullable or contain a default value. Only if the container cannot create an instance will a null or default value be used.

In order to pass a null as an argument to a nullable type, you have to use alias to explicitly declare an alias to null.

Instantiation options reference

The following instantiation options are available for class resolvers. These options (apart from propagate) are also available for global aliases.

Licence

BSD 3 clause