Download the PHP package phossa/phossa-di without Composer

phossa-di [ABANDONED]

See new lib at phoole/di Introduction

Phossa-di is a fast, feature-rich and full-fledged dependency injection library for PHP. It supports auto wiring, object decorating, definition tagging, object scope and more.

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

Getting started

• Installation

  Install via the composer utility.

  or add the following lines to your composer.json

• Simple usage

  You might have serveral simple classes like these or third party libraries, and want to make avaiable as services.

  Now do the following,

  With auto wiring is turned on by default, the container will look for the MyCache class and resolves its dependency injection automatically when creating the $cache instance.

• Use with definitions

  Complex situations may need extra configurations. Definition related methods add(), set(), map(), addMethod() and setScope() etc. can be used to configure services.

  • Service definitions

  Service is defined using API add($id, $classOrClosure, array $arguments) and later can be refered in other definition with service reference @service_id@

  Service reference in the format of @service_id@ can be used anywhere where an object is appropriate, such as in the argument array or construct a pseudo callable,

  • Parameter definitions

  Parameter can be set with API set($name, $value). Parameter reference is '%parameter.name%'. Parameter reference can point to a string, another parameter or even a service reference.

• Callable instead of class name

  Callable can be used instead of class name to instantiate a service.

• Definition files

  Instead of configuring $container in the code, you may put your service and parameter definitions into one definition file or several seperated files (seperating parameter definitions from service definitions will give you the benefit of loading different parameters base on different situations.).

  PHP, JSON, XML file formats are supported, and will be detected automatically base on the filename suffixes.

  A service definition file definition.serv.php

  The parameter definition file definition.param.php

  Or you may combine these files into one definition.php,

  You may load definitions from files now,

Features

• Auto wiring

  Auto wiring is the ability of container instantiating objects and resolving its dependencies automatically. The base for auto wiring is the PHP function parameter type-hinting.

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

  To fully explore the auto wiring feature, users may map interfaces to classnames or service ids as follows,

  Or load mapping files,

  Auto wiring can be turned on/off. Turn off auto wiring will enable user to check any defintion errors without automatically loading.

• 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.

  phossa-di fully supports the delegate feature.

• Object decorating

  Object decorating is to apply decorating changes (run methods etc.) right after the instantiation of a service object base on certain criteria such as it implements an interface.

  Object decorating saves user a lot of definition duplications and will apply to future service definitions. Phossa-di also supports a tester callable and a decorate callable as follows,

• Definition tagging

  Most developers use different defintions or configurations for development or production environment. This is achieved by put definitions in different files and load these files base on the container tags.

  Tag is also used in definition provider.

• Definition provider

  Definition provider is used to wrap logic related definitions into one entity. These definitions will be loaded into container automaitcally if a call to container's has() or get() and found the definition in this provider.

  The provider ProductionDbProvider should be added into container before any calls to has() or get().

  Or during the container instantiation

• Object scope

  By default, service objects in the container is shared inside the container, namely 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 it as Container::SCOPE_SINGLE

  To make all service objects non-shared, set the container's default scope to Container::SCOPE_SINGLE as follows,

Public APIs

• PSR-11 compliant APIs

  • get(string $id): object

  Getting the named service from the container.

  • has(string $id): bool

  Check for the named service's existence in the container.

• Extended APIs by phossa-di

  • __construct(string|array $definitionArrayOrFile = '', array $definitionProviders = [])

  $defintionArrayOrFile can be a defintion file or definition array.

  $definitionProviders can be array of ProviderAbstract objects or provider classnames.

  • get(string $id, array $constructorArguments = [], string $inThisScope = ''): object

  If extra arguments are provided, new instance will be generated even if it was configured with a Container::SCOPE_SHARED scope.

  If $inThisScope is not empty, new instance will be specificly shared in the provided scope.

  Arguments may contain references like @service_id@ or %parameter%.

  • has(string $id, bool $withAutowiring = CONTAINER_DEFAULT_VALUE)

  If $withAutowiring is explicitly set to true or false, auto registering of this service $id if classname matches will be turned ON or OFF for this specific checking. Otherwise, use the container's auto wiring setting.

  • one(string $id, array $constructorArguments = []): object

  Get a new instance even if it is configured as a shared service with or without new arguments.

  • run(callable|array $callable, array $callableArguments = []): mixed

  Execute a callable with the provided arguments. Pseudo callable like ['@cacheDriver@', '%cache.setroot.method%'] is supported.

• Definition related APIs

  • add(string|array $id, string|callable $classOrClosure, array $constructorArguments = []): this

  Add a service definition or definitions(array) into the container. Callable can be used instead of classname to create an instance.

  $constructorArguments is for the constructor.

  Aliasing can be achieved by define $classOrClosure as a service reference, namely @serviceId@.

  • set(string|array $nameOrArray, string|array $valueStringOrArray = ''): this

  Set a parameter or parameters(array) into the container. Parameter name can be the format of 'parameter.name.string', it will be converted into multi-dimention array.

  • map(string|array $nameOrArray, string $toName = ''): this

  Map an interface name to a classname. Also mapping of a classname to another classname (child class), map to a service reference or to a parameter reference is ok. Batch mode if $nameOrArray is an array.

  Note No leading backslash for the $nameOrArray, if it is a classname or interface name.

  • load(string|array $fileOrArray): this

  Load a definition array or definition file into the container. Definition filename with the format of *.s*.php will be considered as a service definition file in PHP format. *.p*.php is a parameter file in PHP format. *.m*.php is a mapping file.

  File suffixes '.php|.json|.xml' are known to this library.

  • share(bool $status = true): this

  Set container-wide default scope. true to set to Container::SCOPE_SHARED and false set to Container::SCOPE_SINGLE

  • auto(bool $switchOn): this

  Turn on (true) or turn off (false) auto wiring.

  • addMethod(string $methodName, array $methodArguments = []): this

  Execute this $methodName right after the service instantiation. This addMethod() has to follow a add() or another addMethod() or setScope() call. Multiple addMethod()s can be chained together.

  $methodName can be a parameter reference. $methodArguments can have parameter or service references.

  • setScope(string $scope): this

  Set scope for the previous added service in the chain of add() or addMethod(). There are two predefined scope contants, shared scope Container::SCOPE_SHARED and single scope Container::SCOPE_SINGLE.

  • dump(bool $toScreen = true): true|string

  Will print out all the definitions and mappings or return the output.

• Extension related APIs

  • addExtension(ExtensionAbstract $extension): this

  Explicitly load an extension into the container.

  Note Calling extension related methods will automatically load corresponding extensions.

  • setTag(string|array $tagOrTagArray): this

  TaggableExtension set/replace container tag(s). Tags can be used to selectly load definition files or definition providers.

  • hasTag(string|array $tagOrTagArray): bool

  TaggableExtension check the existence of tag(s) in the container. One tag match will return true, otherwise return false

  • setDelegate(DelegatorInterface $delegator): this

  DelegateExtension set the delegator. Dependency will be looked up in the delegator instead of in the container. The container itself will be injected into delegator's container pool.

  Since auto wiring is conflict with the delegation design, auto wiring will be turned off automatically for containers in the pool except for the last one.

  • addDecorate(string $ruleName, string|callable $interfaceOrClosure, array|callable $decorateCallable): this

  DecorateExtension adding object decorating rules to the container.

  • addProvider(string|ProviderAbstract $providerOrClass): this

  ProviderExtension add definition provider to the container either by provider classname or a provider object.

Dependencies

• PHP >= 5.4.0

• phossa/phossa-shared >= 1.0.6

• container-interop/container-interop ~1.0

License

MIT License