Service Definitions

A service definition is a plain description of how to build one service: its class name, the constructor arguments, and any method calls to make afterwards. It deliberately knows nothing about the container around it — not the name the service is registered under, nor whether it will be shared or rebuilt each time. That separation is what lets the same definition be reused, compiled, or handed to a factory.

You may reach for definitions directly when you want to describe services in PHP rather than in a .ctn file — for example when building a container from your own data source. The package ships with a ready implementation of ServiceDefinitionInterface, simply called ServiceDefinition.

Constructor

MethodArguments / Return

Construct a new service definition with the given classname and optional arguments as array.

Method definition:

final public function __construct(string $className, array $arguments = [])

Arguments

Data type	Variable name	Comment
class-string	$className	The full class name of the desired service.
array<mixed>	$arguments	An array of constructor arguments for the service.

Create a new service definition:

use ClanCats\Container\ServiceDefinition;

$logger = new ServiceDefinition(MyLogger::class);

You can also directly pass the constructor arguments as an array:

$logger = new ServiceDefinition(MyLogger::class, ['@some_dependency', ':some_parameter', 42]);

Keep in mind when passing arguments as an array prefixing a string with @ will be interpreted as a dependency and : as parameter. This applies everywhere arguments are defined as array. Service Arguments

Static factory

There is also a static method to construct new service definition instance allowing a more expressive syntax.

MethodArguments / Return

Static instance constructor to allow eye candy like:

ServiceDefinition::for('\Acme\SessionService')
   ->addDependencyArgument('storage')
   ->addParameterArgument('session_token')
   ->addRawArgument(600)

Or the shorter way

ServiceDefinition::for('\Acme\SessionService', ['@storage', ':session_token', 600])

Method definition:

public static function for(string $serviceClassName, array $arguments = []): self

Arguments

Data type	Variable name	Comment
class-string	$serviceClassName	The full class name of the desired service.
array<mixed>	$arguments	An array of constructor arguments for the service.

Returns

static

Construct from array

MethodArguments / Return

Construct a single service definition object from an array

ServiceDefinition::fromArray([
    'class' => '\Acme\Demo',
    'arguments' => ['@foo', ':bar'],
    'calls' => [
        ['method' => 'setName', [':demo.name']]
    ]
])

Method definition:

public static function fromArray(array $serviceConfiguration)

Arguments

Data type	Variable name	Comment
array<mixed>	$serviceConfiguration

Returns

static

Constructor Arguments

You can pass additional constructor arguments any time:

$QA = new ServiceDefinition(QA::class);

$QA
    ->addRawArgument('The Answer to the Ultimate Question of Life, The Universe, and Everything.')
    ->addRawArgument(42)
    ->addDependencyArgument('database')
    ->addParameterArgument('priority.default');

Using the arguments method you can also pass them as an array.

$auth = (new ServiceDefinition(MyAuth::class))
    ->arguments([
        '@repository.users',
        ':auth.secret'
    ]);

Add raw argument

MethodArguments / Return

Add a simple raw constructor argument.

Method definition:

public function addRawArgument($argumentValue) : ServiceDefinition

Arguments

Data type	Variable name	Comment
mixed	$argumentValue

Returns

self

$def = ServiceDefinition::for('\Acme\SqlConnection')
    ->addRawArgument('localhost')
    ->addRawArgument('root')
    ->addRawArgument('pleaseDontUseRoot');

Add dependency argument

MethodArguments / Return

Add a dependency constructor argument.

Method definition:

public function addDependencyArgument($argumentValue) : ServiceDefinition

Arguments

Data type	Variable name	Comment
mixed	$argumentValue

Returns

self

$def = ServiceDefinition::for('\Acme\Blog\PostRepository')
    ->addDependencyArgument('db.connection');

Add parameter argument

MethodArguments / Return

Add a simply parameter constructor argument.

Method definition:

public function addParameterArgument($argumentValue) : ServiceDefinition

Arguments

Data type	Variable name	Comment
mixed	$argumentValue

Returns

self

$def = ServiceDefinition::for('\Acme\Session')
    ->addParameterArgument('session.secret');

Get all arguments

MethodArguments / Return

Returns the constructor arguments object

Method definition:

public function getArguments() : ServiceArguments

Arguments

This method takes no arguments.

Returns

ServiceArguments

$definition->getArguments(); // ServiceArguments instance

Get service class name

MethodArguments / Return

Returns the service class name

Method definition:

public function getClassName() : string

Arguments

This method takes no arguments.

Returns

class-string

Method Calls

A service definition can hold method calls that have to be called on construction, these can set dependencies, parameters or raw values just like the constructor arguments.

Add a method call (with array)

MethodArguments / Return

Adds a method call to the service definition, the arguments should be set as an array.

Method definition:

public function calls(string $method, array $arguments = []) : ServiceDefinition

Arguments

Data type	Variable name	Comment
string	$method	The name of the method to be called.
array<mixed>	$arguments	The method arguments as array.

Returns

self

$def = ServiceDefinition::for('\Acme\Session')
    ->calls('setEventDispatcher', ['@event_dispatcher']);

Add a method call

MethodArguments / Return

Adds a method call to the service definition, the arguments must be set with a ServiceArguments instance.

Method definition:

public function addMethodCall(string $methodName, ServiceArguments $arguments) : ServiceDefinition

Arguments

Data type	Variable name	Comment
string	$methodName	The name of the method to be called.
ServiceArguments	$arguments	An `ServiceArguments` instance for the method call.

Returns

self

$eventDispatcherArgs = (new ServiceArguments())
    ->addDependency('event_dispatcher');

$sessionDefinition = ServiceDefinition::for('\Acme\Session')
    ->addMethodCall('setEventDispatcher', $eventDispatcherArgs);

Interface

Any class that will be used as a service definition must implement the ServiceDefinitionInterface which requires the following methods:

Return the service class name

public function getClassName() : string;

---

Return the constructor arguments object

public function getArguments() : ServiceArguments;

---

Return the registered method calls

public function getMethodCalls() : array;

The format of the returned array should look like [string => ServiceArguments].