Download the PHP package phossa2/di without Composer

phossa2/di [ABANDONED]

PLEASE USE phoole/di library instead

phossa2/di is a fast and powerful Container-Interop or PSR-11 implementation of dependency injection library for PHP. It builds upon the versatile phossa2/config library and supports container delegation, object scope and more.

It requires PHP 5.4, supports PHP 7.0+ and HHVM. It is compliant with PSR-1, PSR-2, PSR-4, and proposed PSR-5, PSR-11.

Installation

Install via the composer utility.

or add the following lines to your composer.json

Usage

• With autowiring of classes.

  A couple of simple classes as follows,

  Instead of creating MyCacheDriver and MyCache instances manually, you may get the both instances automatically using the DI container,

  With autowiring is turned on by default, the container will look for the MyCache class if no service defined as 'MyCache', and resolves its dependency injection (here, is the MyCacheDriver instance) automatically when creating the MyCache instance.

• With manual service addition using set()

  Services can be added to the container manually by using set() method.

  A service reference '${#driver}' used in the constructor arguments here indicating it is the driver service instance from the container.

• With configuration from files or array

  Container uses a Phossa2\Config\Interfaces\ConfigInterface instance as its definition resolver for parameter and service definitions. The config instance may either read configs from files or get configs from an array as follows,

  By default, container related configurations are under the node di and service definitions are under the di.service node.

Features

• References

  References in the form of '${reference}' can be used to refer to predefined parameters from the config or services in the container.

  Characters of '$', '{', '}', '.' are not allowed in reference name. Characters of '#', '@' have special meanings, such that should not be part of normal service names.

  • Parameter references

  See phossa2/config reference for detail. Parameter references are read from configuration files or can be defined by container method param() as follows,

  • Service references

  Service reference in the form of '${#service_id}' can be used to referring a service instance in the container (or in the delegator).

  Two reserved service references are '${#container}' and '${#config}'. These two are refering the container instance itself and the config instance it is using. These two can be used just like other service references.

  • Using references

  References can be used anywhere in the configs or as the arguments for all container methods (except for the paramter $id of the methods).

• Autowiring and mapping

  Autowiring is the ability of container instantiating objects and resolving its dependencies automatically by their classname. The base for autowiring is the PHP function parameter type-hinting.

  By reflecting on class, constructor and methods, phossa2/di is able to find the right class for the instance (user need to use the classname as the service id) and right classes for its dependencies (type-hinted with the classnames).

  If interface name is used for dependency type-hint, users may set up the mapping of interfaces to the right classnames as follows,

  Or define mappings in the config node di.service as follows,

  Autowiring can be turned on/off. Turning off autowiring will enable user to check any defintion errors without automatic loading.

• Object decorating

  Object decorating is to apply decorating changes (executing methods etc.) right after the instantiation of a service instance.

  • Decorating methods for individual instance only

  By adding methods section into the cache service definition in the form of [ callableOrMethodName, OptionalArgumentArray ], these methods will be executed right after cache instantiation.

  callableOrMethodName here can be,

  • method name of current instance

  • a valid callable

  • a psedudo callable with references (after resolving the references, it is a valid callable).

  OptionalArgumentArray here can be,

  • empty

  • array of values or references

  • Common decorating methods for all instances

  Common methods can be configured in the 'di.common' node to apply to all the instances right after their instantiation. The definition consists of two parts, the first is a tester callable takes current instance and the container as parameters and returns a boolean value. The second part is in the same method format as in the service definition 'methods'.

  To skip execution of common methods for one service, define it with skip as follows,

• Container delegation

  According to Interop Container Delegate Lookup, container may register a delegate container (the delegator), and

  • Calls to the get() method should only return an entry if the entry is part of the container. If the entry is not part of the container, an exception should be thrown (as requested by the ContainerInterface).

  • Calls to the has() method should only return true if the entry is part of the container. If the entry is not part of the container, false should be returned.

  • If the fetched entry has dependencies, instead of performing the dependency lookup in the container, the lookup is performed on the delegate container (delegator).

  • Important By default, the lookup SHOULD be performed on the delegate container only, not on the container itself.

  phossa2/di fully supports the delegate feature.

• Object scope

  • Shared or single scope

  By default, service instances in the container are shared inside the container. Actually they have the scope of Container::SCOPE_SHARED. If users want different instance each time, they may either use the method one() or define the service with Container::SCOPE_SINGLE scope.

  Or define the service as Container::SCOPE_SINGLE

  Set the container's default scope to Container::SCOPE_SINGLE will cause each get() returns a new instance (unless 'scope' is explicitly defined as for this service).

  • Use your own scope

  You may get an instance in your own scope as follows, no matter whatever the default scope or the defined scope for this instance,

  Service references can also have scope defined as follows,

  • Share instance only in certain object

  Sometimes, user may want to share one instance only inside certain object.

  In previous code, C is not only shared under the A, but also shared among different instances of A. What if user want to share C only under the A but not between A ?

  By setting scope of C to '#A' as follows,

• Array access and read only

  Both Phossa2\Di\Container and Phossa2\Di\Delegator implements \ArrayAccess interface.

  By default Phossa2\Di\Container is writable which means user can add new service definitions to the container manually by using set().

  Note If container is set readonly, auto wiring is turned off automatically.

  To get a readonly container,

APIs

• Container related

  • get(string $id): object from ContainerInterface

  If not found, Phossa2\Di\Exception\NotFoundException is thrown. $id may have '@scope' appended. An array can be used as the second parameter for object constructor's arguments.

  • has(string $id): bool from ContainerInterface

  $id may have '@scope' appended.

  • one(string $id, array $args = []): object from ExtendedContainerInterface

  Get a new instance for this $id. May provide new arguments for the object constructor.

  • run(mixed $callable, array $args = []): mixed from ExtendedContainerInterface

  Execute a callable or pseduo callable (with references) with provided arguments (may contain references also)

  • param(string $name, mixed $value): bool from ExtendedContainerInterface

  Set a parameter in the container's config tree for later to be used as a reference. Returns a bool value to indicate status.

  • alias(string $id, object|string $object): bool from ExtendedContainerInterface

  Aliasing an object as $id in the container. Difference with set() method is that getting this object will skip the execution of common methods.

  Returns true on success and false on failure.

  • auto(bool $flag): $this from AutoWiringInterface

  Set container autowiring ON or OFF.

  • isAuto(): bool from AutoWiringInterface

  Test container is auto wiring ON or OFF.

  • resolve(mixed &$data): $this from ReferenceResolveInterface

  Recursively resolving references in the $data. $data might be string or array. Other data type will be untouched.

  • share(bool $flag = true): $this from ScopeInterface

  Make container default scope to Container::SCOPE_SHARED or Container::SCOPE_SINGLE.

  • set(string $id, mixed $value): bool from WritableInterface

  Set a service with $id into the container. $value can be an array in the form of array as follows,

  or $value can be classname, object, callback etc. Returns true on success or false on failure. Container has to be writable, otherwise a LogicException will be thrown.

  • isWritable(): bool from WritableInterface

  Is this container writable ?

  • setWritable(bool $writable): bool from WritableInterface

  Set this container writable or readonly.

• Delegator related

  • get(string $id): object from ContainerInterface

  Get service from the delegator. If not found, Phossa2\Di\Exception\NotFoundException is thrown. $id may have '@scope' appended as long as underlying container supports this feature.

  • has(string $id): bool from ContainerInterface

  $id may have '@scope' appended as long as underlying container supports this feature.

  • set(string $id, mixed $value): bool from WritableInterface

  Set a service with $id into the delegator as long as the delegator is writable.

  • isWritable(): bool from WritableInterface

  Is this delegator writable ?

  • setWritable(bool $writable): bool from WritableInterface

  Set this delegator writable or readonly.

  • addContainer(ContainerInterface $container): $this from DelegatorInterface

  Add a container to the delegator.

Change log

Please see CHANGELOG from more information.

Testing

Contributing

Please see CONTRIBUTE for more information.

Dependencies

• PHP >= 5.4.0

• phossa2/config >= 2.0.12

• phossa2/shared >= 2.0.21

License

MIT License