Slick Dependency Container Injection Documentation · Slick Dependency Container Injection...

Slick Dependency Container InjectionDocumentation

Release v2.6.0

Slick Team

Mar 05, 2020

Contents

1 Getting started 31.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Basic usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2 Definitions 52.1 What’s a definition? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 Value definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.3 Factory definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.4 Alias definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.5 Object definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3 Container usage 93.1 Building a container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.2 Constructor injection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.3 Constructor auto-injection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103.4 Factory method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

4 API reference 134.1 Container class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.2 Container Injection interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144.3 ObjectDefinition class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

5 Contributing 175.1 Pull requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175.2 Running tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175.3 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

6 License 19

PHP Namespace Index 21

Index 23

i

Slick Dependency Container Injection Documentation, Release v2.6.0

slick/di is an easy dependency injection container for PHP 7.1+.

It aims to be very lightweight and tries to remove a lot of the guessing and magic stuff that dependency containers usethose days.

It also allows you to nest containers witch can become very useful if you have several packages that you reuse inyour applications, allowing you to define containers with default dependencies in those packages for later override andusage them in your application.

There are a lot of implementations of a dependency injection container out there and some of them are really good.Some examples are the Symfony Dependency Injection Component, Zend 2 Dependency Injection, The PHP leaguecontainer, or PHP-DI just to name a few.

This implementation is a result of what we thought it was the best to have in a dependency injection container.

Contents 1

https://symfony.com/doc/current/components/dependency_injection.html

https://framework.zend.com/manual/2.4/en/modules/zend.di.introduction.html

http://container.thephpleague.com/

http://container.thephpleague.com/

http://php-di.org/


2 Contents

CHAPTER 1

Getting started

1.1 Introduction

Dependency injection is a concept that has been talked about all over the web. You probably have done it withoutknowing that is called dependency injection. Simply put the next line of code can describe what it is:

$volvo = new Car(new Engine());

Above, Engine is a dependency of Car, and Enginewas injected into Car. If you are not familiar with DependencyInjection please read this Fabien Pontencier’s great series about Dependency injection.

Dependency injection and dependency injection containers are tow different things. Dependency injection is a designpattern that implements inversion of control for resolving dependencies. On the other hand Dependency InjectionContainer is a tool that will help you create, reuse and inject dependencies.

A dependency container can also be used to store object instances that you create and values that you may need to userepeatedly. A good example of this are configuration settings.

1.2 Basic usage

To create a dependency container we need to create at least a services.php file with all our dependency definitions:

use Slick\Di\Definition\ObjectDefinition;

/*** Dependency injection object definition example

*/return [

'config' => ['color' => 'blue','gear' => 'manual'

],

(continues on next page)

3

http://fabien.potencier.org/what-is-dependency-injection.html

https://en.wikipedia.org/wiki/Inversion_of_control


(continued from previous page)

'engineService' => ObjectDefinition::create(Engine::class)->with('@config')->call('setMode')->with('simple')

];

Now to build the dependency container we need to use the ContainerBuilder factory class like this:

use Slick\Di\ContainerBuilder;

$definitionsFile = __DIR__ . '/services.php';$container = (new ContainerBuilder($definitionsFile))->getContainer();

With that, we are ready to create and inject dependencies with our container:

class Car{

/*** @var EngineInterface

*/protected $engine;

public function __construct(EngineInterface $engine){

$this->engine = $engine;}

}

$myCar = $container->make(Car::class);

1.3 Installation

slick/di is a php 7.1+ library that you’ll have in your project development environment. Before you begin, ensure thatyou have PHP 7.1 or higher installed.

You can install slick/di with all its dependencies through Composer. Follow instructions on the composer website ifyou don’t have it installed yet.

You can use this Composer command to install slick/di:

$ composer require slick/di

4 Chapter 1. Getting started

https://getcomposer.org/download/

CHAPTER 2

Definitions

2.1 What’s a definition?

Definitions are entries in an array that instruct the container on how to create the correspondent object instance orvalue.

Attention: Every container MUST have a definition list (associative array) in order to be created and youSHOULD always use the Slick\Di\ContainerBuilder to create your container.

Lets create our dependencies.php file that will contain our dependencies definitions:

/*** Dependency injection definitions file

*/$services['timezone'] = 'UTC';$services['config'] = function() {

return Configuration::get('config');};

return $services;

Note: Why use PHP arrays?

This question has a very simple answer. If you use other markup/style to create the container definitions file, forexample .ini or .yml you will need to parse those settings and then apply them. If you use PHP arrays there is noneed to parse it and the code can be directly executed, enhancing performance.

5


2.2 Value definition

A value or scalar definition is used as is. The following example is a value definition:

/*** Dependency injection value definition example

*/$services['timezone'] = 'UTC';

return $services;

Value definitions are good to store application wide constants.

2.3 Factory definition

With factory definition we can compute and/or control the object or value creation:

/*** Dependency injection callable definition example

*/$services['general.config'] = function() {

return Configuration::get('config');}

return $services;

It is possible to have the container instance available in the closure by defining an input argument. See the followingexample:

/*** Dependency injection callable definition example

*/$services['general.config'] = function(ContainerInterface $container) {

$foo = $container->get('foo');return Configuration::get('config')->get('bar', $foo);

}

return $services;

2.4 Alias definition

Alias definition is a shortcut for another defined entry:

/*** Dependency injection alias definition example

*/$services['config'] = '@general.config';

return $services;

The alias points to an entry key and is always prefixed with an @

6 Chapter 2. Definitions


2.5 Object definition

Objects are what makes dependency containers very handy, and fun! Lets have a look at an object definition insideour dependencies.php file:

namespace Services;

use Services\SearchService;use Slick\Configuration\Configuration:use Slick\Di\Definition\ObjectDefinition;

/*** Dependency injection object definition example

*/$services['siteName'] => 'Example site';$services['config'] => function() {

return Configuration::get('config');};

// Object definition$services['search.service'] = ObjectDefinition::create(SearchService::class)

->with('@config')->call('setMode')->with('simple')->call('setSiteName')->with('@siteName')->assign(20)->to('rowsPerPage')

;

return $services;

Defining how an object is instantiated is the most important feature of a dependency container. 'search.service'is an object definition on how to instantiate a SearchService. It uses a fluent api that can easily describe thenecessary steps to create a service or object.

Tip: If you want to reference the container itself you can use the @container tag in the object definition file.

Please check the ObjectDefinition API for a better understanding of all methods on ObjectDefinition definition.

2.5. Object definition 7


8 Chapter 2. Definitions

CHAPTER 3

Container usage

Now that we have defined all of our dependencies its time to create a container that will use them.

3.1 Building a container

Even though Container can be instantiated as normal PHP objects do, it is advisable to use theContainerBuilder factory to do so. It translates the definitions file(s) into DefinitionInterface objectsthat dependency container uses to resolve its dependencies. It also chains all the created container so that if you tryto get an entry it will search over all containers in the chain. This is a very handy feature if you want, for example,to create a package that you will reuse in your applications and in that package you define a container with defaultdependencies and later on your application also defines a dependency container. Definitions can be overridden and theentries from your package are also available in your application container.

Now lets create our container:

use Slick\Di\ContainerBuilder;

$container = (new ContainerBuilder(__DIR__ . '/dependencies.php'))->getContainer();

That’s it! We now have a new created dependency container ready to create objects and inject their dependencies.

3.2 Constructor injection

Constructor dependency injection is considered the way we should do dependency injection and it is just passing thedependencies as arguments in the constructor. With this you do not need to created setters and your object is ready tobe used right away. You can also test it in isolation by passing mocks of those dependencies.

Consider the following class:

9


class Car{


*/private $engine;



}

This is a basic class. The car needs an engine to work, right!?

Tip: In constructor dependency injection and in dependency injection in general, it is a good practice to type hintyour arguments. This practice guarantees that the arguments are from that given type and PHP’s core will trigger afatal error if they are not.

Now that we have a container with all its dependency definitions lets create the car using and engine that is store inthe container under the diesel.engine name:

$dieselCar = $container->make(Car::class, '@diesel.engine');

This line of code is instructing the container that it should instantiate a Car object and it will inject the dependencythat was stored under the diesel.engine name in its constructor.

Take a look at Container class reference page for more information on Container::make() method.

3.3 Constructor auto-injection

It is also possible to have dependencies injected on objects created by Container::make() only by type hintingthe parameters in the constructor:

public function __construct(EngineInterface $engine)......$dieselCar = $container->make(Car::class);...// As __construct(EngineInterface $engine) is type hinted the container will look// for '@EngineInterface::class' definition and inject it.

You can mix the arguments sent on Container::make() second parameter with constructor auto-injection. Inthis case the arguments used in this late array will override the ones container has figure out.

Important: Since v2.3.0 this is the behavior of Container::make() method and an exception will be thrownwhenever a parameter hint results in a missing definition, otherwise why should you create object with the dependencycontainer?

10 Chapter 3. Container usage


3.4 Factory method

one other possibility to create classes that the container can instantiate is by implementing theContainerInjectionInterface interface. This is a simple interface that forces the creation of theobject trough a factory method.

Take a look at the Car class with dependency injection implementation:

use Slick\Di\ContainerInjectionInterface;use slick\Di\ContainerInterface;

class Car implements ContainerInjectionInterface{


*/private $engine;



/*** Creates a diesel car

** @param ContainerInterface $container

* @return Car

*/public static function create(ContainerInterface $container){

$car = new Car($container->get('diesel.engine'));return $car;

}}

Creating the car:

$dieselCar = $container->make(Car::class);

The container will call the ContainerInjectionInterface::create() method passing itself as argument.Note that the responsibility for object creation is on the class itself.

Form more information check the Container Injection Interface reference page.

3.4. Factory method 11


12 Chapter 3. Container usage

CHAPTER 4

API reference

4.1 Container class

class Slick\Di\ContainerContainer is where your dependencies live. It holds a list of DefinitionInterface objects that can beresolved into objects or values.

Slick\Di\Container::get($id)Finds an entry of the container by its identifier and returns it.

Parameters

• $id (string) – Identifier of the entry to look for.

Throws NotFoundException – No entry was found for this identifier.

Returns An object or value that was stored or has its definition under the provided $id identifier.

Slick\Di\Container::has($id)Returns true if the container can return an entry for the given identifier

Parameters

• $id (string) – Identifier of the entry to look for.

Returns True if container can return an entry or false otherwise.

Slick\Di\Container::register($name, $definition[, $scope, $params])Adds a definition or a value to the container with the $name as identifier.

Parameters

• $name (string) – Identifier where the entry will be stored in.

• $definition (mixed) – The definition or value to store.

• $scope (string|Scope) – The resolution scope. Please see Definitions page for details.Defaults to Scope::SINGLETON.

13


• $params (array) – An array of arguments to pass to callable (Factory) definitions. De-faults to an empty array.

Returns Container itself. Useful for chaining more container calls.

Tip: $definition can be any value and the container will evaluate it in order to determine what strategy itwill use to resolve it latter on. The possibilities are:

• scalar|objects: scalar values or objects are store as Value definition;

• @<identifier>: this is an Alias definition that will point to the definition stored under the identifiername;

• callable: a callable is stored as Factory definition. It will be executed when Container::get()is called for the first time and the result value will be returned in the subsequent calls. $params will bepassed when executing the callable;

• Slick\Di\DefinitionInterface: Definition interface handle the entry resolution. In this casethe container will return the resolved value of the definition.

Slick\Di\Container::make($className[, ...$arguments])Creates an instance of provided class injecting its dependencies.

Parameters

• $className (string) – The class name that the container will use to create the object.

• $arguments (array) – An optional list of arguments to pass to the constructor.

Returns An object from the type passed in the $className argument.

Tip: If you create a class that implements the Slick\Di\ContainerInjectionInterface all the$arguments that you may pass to this method will be ignored as the container will call the create()method and pass himself as an argument to that method. Please see ContainerInjectionInterface reference

4.2 Container Injection interface

interface Slick\Di\ContainerInjectionInterfaceThis is an easy way of creating a class that the dependency container will know how to instantiate. It has a singlemethod and it enforces the constructor dependency injection pattern.

static create($container)Instantiates a new instance of this class.

Parameters

• $container (Interop\Container\ContainerInterface) – The servicecontainer this instance should use.

Returns A new instance of this class.

Tip: This is a factory method that returns a new instance of this class. The factory should pass any neededdependencies into the constructor of this class, but not the container itself. Every call to this method must returna new instance of this class; that is, it may not implement a singleton.

14 Chapter 4. API reference


4.3 ObjectDefinition class

class Slick\Di\Definition\ObjectDefinitionAn object instantiation definition that wraps the necessary steps so that a dependency container can instantiate agiven class.

__construct($className)Creates a definition for provided class name.

Parameters

• $className (string) – The class name that will be instantiated.

static create($className)Factory method to create an object definition.

Parameters

• $className (string) – The class name that will be instantiated.

Returns ObjectDefinition definition object

with(...$arguments)Set the arguments for the last defined method call. If no method call was defined yet it will set theconstructor argument list

Parameters

• $arguments (array) – Arguments passed to object constructor

Returns The object definition itself. Useful for other method calls.

withConstructorArgument(...$arguments)Set the arguments used to create the object.

Parameters

• $arguments (array) – Arguments passed to object constructor.


call($methodName)Define a method call in the freshly created object.

Parameters

• $methodName (string) – The method name to call.


assign($value)Set the value that will be assigned to a property.

Parameters

• $value (mixed) – The value to be assigned.


to($propertyName)Assign the last defined value to the provided property. The value will be reset after its assigned.

Parameters

• $property (string) – The property name where last value will be assigned.


4.3. ObjectDefinition class 15


callMethod($methodName, ...$arguments)Define a method call to the method with provided name.

Parameters

• $methodName (string) – The method name to call.

• $arguments (array) – The list of arguments to use when calling the method.

Throws Slick\Exception\MethodNotFoundException if called method does not exists.


assignProperty($name, $value)Assigns a value to the property with provided name.

Parameters

• $name (string) – The property name.

• $value (mixed) – The value to assign to the property.


resolve()Resolves the definition into an object.

Returns The object as described in the definition

16 Chapter 4. API reference

CHAPTER 5

Contributing

Contributions are welcome and will be fully credited. We accept contributions via Pull Requests on Github.

5.1 Pull requests

• PSR-2 Coding Standard - The easiest way to apply the conventions is to install PHP Code Sniffer.

• Add tests! - Your patch won’t be accepted if it doesn’t have tests.

• Document any change in behaviour - Make sure the README.md and any other relevant documentation arekept up-to-date.

• Consider our release cycle - We try to follow SemVer v2.0.0. Randomly breaking public APIs is not an option.

• Create feature branches - Don’t ask us to pull from your master branch.

• One pull request per feature - If you want to do more than one thing, send multiple pull requests.

• Send coherent history - Make sure each individual commit in your pull request is meaningful. If you had tomake multiple intermediate commits while developing, please squash them before submitting.

5.2 Running tests

We use Behat to describe features and and for acceptance tests and PHPUnit for integration and unit testing.

# unit tests$ vendor/bin/phpspec run

# acceptance tests$ vendor/bin/behat

17

https://github.com/slickframework/di

https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md

http://pear.php.net/package/PHP_CodeSniffer

http://semver.org

http://behat.org/en/latest/index.html

https://phpunit.de/


5.3 Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

18 Chapter 5. Contributing

mailto:[email protected]

CHAPTER 6

License

Licensed using the MIT license.

Copyright (c) 2014-2020 The Slick Team <https://github.com/orgs/slickframework/people>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documen-tation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use,copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whomthe Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of theSoftware.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PAR-TICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHTHOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTIONOF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFT-WARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

19

http://opensource.org/licenses/MIT

https://github.com/orgs/slickframework/people


20 Chapter 6. License

PHP Namespace Index

sSlick\Di, 14Slick\Di\Definition, 15

21


22 PHP Namespace Index

Index

Symbols__construct() (Slick\Di\Definition\ObjectDefinition

method), 15

Aassign() (Slick\Di\Definition\ObjectDefinition

method), 15assignProperty() (Slick\Di\Definition\ObjectDefinition

method), 16

Ccall() (Slick\Di\Definition\ObjectDefinition method),

15callMethod() (Slick\Di\Definition\ObjectDefinition

method), 15Container (class in Slick\Di), 13ContainerInjectionInterface (interface in

Slick\Di), 14create() (Slick\Di\ContainerInjectionInterface

method), 14create() (Slick\Di\Definition\ObjectDefinition

method), 15

Gget() (Slick\Di\Container method), 13

Hhas() (Slick\Di\Container method), 13

Mmake() (Slick\Di\Container method), 14

OObjectDefinition (class in Slick\Di\Definition), 15

Rregister() (Slick\Di\Container method), 13resolve() (Slick\Di\Definition\ObjectDefinition

method), 16

SSlick\Di (namespace), 13, 14Slick\Di\Definition (namespace), 15

Tto() (Slick\Di\Definition\ObjectDefinition method), 15

Wwith() (Slick\Di\Definition\ObjectDefinition method),

15withConstructorArgument()

(Slick\Di\Definition\ObjectDefinition method),15

23

Slick Dependency Container Injection Documentation · Slick Dependency Container Injection...

Documents

Transcript of Slick Dependency Container Injection Documentation · Slick Dependency Container Injection...