https://github.com/yiisoft/definitions
The package provides definition syntax. Definition is describing a way to create and configure a service or an object.
https://github.com/yiisoft/definitions
di-container factory hacktoberfest yii3
Last synced: about 1 year ago
JSON representation
The package provides definition syntax. Definition is describing a way to create and configure a service or an object.
- Host: GitHub
- URL: https://github.com/yiisoft/definitions
- Owner: yiisoft
- License: bsd-3-clause
- Created: 2021-08-25T21:36:07.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2024-10-27T21:22:49.000Z (over 1 year ago)
- Last Synced: 2024-10-29T14:35:34.805Z (over 1 year ago)
- Topics: di-container, factory, hacktoberfest, yii3
- Language: PHP
- Homepage: https://www.yiiframework.com/
- Size: 296 KB
- Stars: 12
- Watchers: 19
- Forks: 6
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
Yii Definitions
[](https://packagist.org/packages/yiisoft/definitions)
[](https://packagist.org/packages/yiisoft/definitions)
[](https://github.com/yiisoft/definitions/actions/workflows/build.yml)
[](https://codecov.io/gh/yiisoft/definitions)
[](https://dashboard.stryker-mutator.io/reports/github.com/yiisoft/definitions/master)
[](https://github.com/yiisoft/definitions/actions/workflows/static.yml?query=branch%3Amaster)
[](https://shepherd.dev/github/yiisoft/definitions)
The package provides syntax constructs describing a way to create and configure a service or an object.
It is used by [yiisoft/di](https://github.com/yiisoft/di) and [yiisoft/factory](https://github.com/yiisoft/factory)
but could be used in other [PSR-11](https://www.php-fig.org/psr/psr-11/) compatible packages as well.
The following are provided:
- Definitions describing services or objects to create. This includes syntax, its validation and resolving it to objects.
- References and dynamic references to point to other definitions. These include additional utility to refer to multiple
definitions at once.
## Requirements
- PHP 8.1 or higher.
## Installation
The package could be installed with [Composer](https://getcomposer.org):
```shell
composer require yiisoft/definitions
```
## General usage
### Definitions
Definition is describing a way to create and configure a service, an object
or return any other value. It must implement `Yiisoft\Definitions\Contract\DefinitionInterface`
that has a single method `resolve(ContainerInterface $container)`. References are
typically stored in the container or a factory and are resolved into an object
at the moment of getting a service instance or creating an object.
#### `ArrayDefinition`
Array definition allows describing a service or an object declaratively:
```php
use \Yiisoft\Definitions\ArrayDefinition;
$definition = ArrayDefinition::fromConfig([
'class' => MyServiceInterface::class,
'__construct()' => [42],
'$propertyName' => 'value',
'setName()' => ['Alex'],
]);
$object = $definition->resolve($container);
```
In the above:
- `class` contains the name of the class to be instantiated.
- `__construct()` holds an array of constructor arguments.
- The rests of the config are property values (prefixed with `$`)
and method calls, postfixed with `()`. They are set/called
in the order they appear in the array.
For multiple method call postfix key with unique string, for example:
```php
[
'class' => Collector::class,
'add()' => ['Alex'],
'add()2' => ['Mike'],
]
```
#### `CallableDefinition`
Callable definition builds an object by executing a callable injecting
dependencies based on types used in its signature:
```php
use \Yiisoft\Definitions\CallableDefinition;
$definition = new CallableDefinition(
fn (SomeFactory $factory) => $factory->create('args')
);
$object = $definition->resolve($container);
// or
$definition = new CallableDefinition(
fn () => MyFactory::create('args')
);
$object = $definition->resolve($container);
// or
$definition = new CallableDefinition(
[MyFactory::class, 'create']
);
$object = $definition->resolve($container);
```
In the above, we use a closure, a static call and a static
method passed as array-callable. In each case, we determine
and pass dependencies based on the types of arguments in
the callable signature.
#### `ParameterDefinition`
Parameter definition resolves an object based on information from `ReflectionParameter` instance:
```php
use \Yiisoft\Definitions\ParameterDefinition;
$definition = new ParameterDefinition($reflectionParameter);
$object = $definition->resolve($container);
```
It is mostly used internally when working with callables.
#### `ValueDefinition`
Value definition resolves value passed as is:
```php
use \Yiisoft\Definitions\ValueDefinition;
$definition = new ValueDefinition(42, 'int');
$value = $definition->resolve($container); // 42
```
### References
References point to other definitions, so when defining a definition, you can use other definitions as its
dependencies:
```php
[
InterfaceA::class => ConcreteA::class,
'alternativeForA' => ConcreteB::class,
MyService::class => [
'__construct()' => [
Reference::to('alternativeForA'),
],
],
]
```
Optional reference returns `null` when there's no corresponding definition in container:
```php
[
MyService::class => [
'__construct()' => [
// If a container doesn't have definition for `EventDispatcherInterface` reference returns `null`
// when resolving dependencies
Reference::optional(EventDispatcherInterface::class),
],
],
]
```
The `DynamicReference` defines a dependency to a service not defined in the container:
```php
[
MyService::class => [
'__construct()' => [
DynamicReference::to([
'class' => SomeClass::class,
'$someProp' => 15
])
]
]
]
```
To pass an array of IDs as references to a property or an argument, `Yiisoft\Definitions\ReferencesArray` or
`Yiisoft\Definitions\DynamicReferencesArray` could be used:
```php
//params.php
return [
'yiisoft/data-response' => [
'contentFormatters' => [
'text/html' => HtmlDataResponseFormatter::class,
'application/xml' => XmlDataResponseFormatter::class,
'application/json' => JsonDataResponseFormatter::class,
],
],
];
//web.php
ContentNegotiator::class => [
'__construct()' => [
'contentFormatters' => ReferencesArray::from($params['yiisoft/data-response']['contentFormatters']),
],
],
```
### Class aliases
To define another instance of a class with specific configuration, you can
use native PHP `class_alias()`:
```php
class_alias(Yiisoft\Db\Pgsql\Connection::class, 'MyPgSql');
return [
MyPgSql::class => [ ... ]
];
```
### Definition storage
Definition storage could be used to hold and get definitions and check if a certain definition could be instantiated.
Usually it is used by an implementation using the definitions:
```php
use Yiisoft\Definitions\DefinitionStorage;
$storage = new DefinitionStorage([
MyInterface::class => MyClass::class,
]);
$storage->setDelegateContainer($fallbackContainer);
if (!$storage->has(MyInterface::class)) {
$buildStack = $storage->getBuildStack();
// ...
}
```
In the above `$buildStack` will contain a stack with definition IDs in the order the latest dependency obtained would be
built.
By default, if a class is checked in `has()` and it is not explicitly defined, the storage tries to autoload it first
before failing. The storage may also work in a strict mode when everything in it should be defined explicitly:
```php
use Yiisoft\Definitions\DefinitionStorage;
$storage = new DefinitionStorage([], true);
var_dump($storage->has(EngineMarkOne::class));
```
`has()` will return `false` even if `EngineMarkOne` exists.
## Documentation
- [Internals](docs/internals.md)
If you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/63) is a good place for
that. You may also check out other [Yii Community Resources](https://www.yiiframework.com/community).
## License
The Yii Definitions is free software. It is released under the terms of the BSD License.
Please see [`LICENSE`](./LICENSE.md) for more information.
Maintained by [Yii Software](https://www.yiiframework.com/).
## Support the project
[](https://opencollective.com/yiisoft)
## Follow updates
[](https://www.yiiframework.com/)
[](https://twitter.com/yiiframework)
[](https://t.me/yii3en)
[](https://www.facebook.com/groups/yiitalk)
[](https://yiiframework.com/go/slack)