italystrap / empress
Config driven for Auryn Injector the OOP way
Requires
- php: >=8.2
- italystrap/config: ^2.12
- overclokk/auryn: ^2.1
- psr/container: ^1.1 || ^2.0
Requires (Dev)
- dealerdirect/phpcodesniffer-composer-installer: ^1.0
- friendsofphp/proxy-manager-lts: ^1.0
- infection/infection: ^0.29 || ^0.35
- italystrap/debug: dev-master
- italystrap/finder: dev-master
- phpbench/phpbench: ^1.2
- phpcompatibility/php-compatibility: ^9.3
- phpmetrics/phpmetrics: ^2.8
- phpspec/prophecy-phpunit: ^2.3
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^11.5
- rector/rector: ^2.0
- rector/swiss-knife: ^2.3
- squizlabs/php_codesniffer: ^3.7
Suggests
- friendsofphp/proxy-manager-lts: Only if you want to add support for lazy loading classes
- italystrap/empress-cache: Only if you want to cache the aggregated providers configuration in a PHP file
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-21 13:12:53 UTC
README
Config driven for Auryn Injector the OOP way
In this library it is also included a bridge for the Auryn\Injector and ProxyManager for lazily initializes a "real" instance of the proxied class.
This library is still a WIP (work in progres)
Table Of Contents
Installation
The best way to use this package is through Composer:
composer require italystrap/empress
This package adheres to the SemVer specification and will be fully backward compatible between minor versions.
Basic Usage
- PhpFileProvider: loads config arrays from files.
- ModuleInterface: standard callable module contract.
- ProvidersCollection: executes providers/modules and aggregates their returned config.
- AurynConfig: applies the config array to Auryn.
- Container: PSR-11 adapter around Auryn.
- ContainerBuilder: coordinates the build process.
$providers->aggregate(); $aurynConfig->apply(); $containerBuilder->build();
This reads as: aggregate config, apply DI config, build container.
PSR-11 ContainerBuilder
ContainerBuilder is the quickest way to aggregate providers, apply the Auryn configuration, and receive a PSR-11 container.
use ItalyStrap\Config\Config; use ItalyStrap\Config\ConfigInterface; use ItalyStrap\Empress\AurynConfig; use ItalyStrap\Empress\AurynConfigInterface; use ItalyStrap\Empress\ContainerBuilder; use ItalyStrap\Empress\Extension; use Psr\Container\ContainerInterface; $builder = new ContainerBuilder(); $builder ->addProvider(static fn(): array => [ AurynConfig::ALIASES => [ ConfigInterface::class => Config::class, ], AurynConfig::SHARING => [ ConfigInterface::class, ], AurynConfig::DELEGATIONS => [ SomeService::class => static function (ContainerInterface $container): SomeService { return new SomeService($container->get(ConfigInterface::class)); }, ], ]) ->extend(new class implements Extension { public function name(): string { return 'my-extension'; } public function execute(AurynConfigInterface $application): void { // Add custom Auryn configuration logic here. } }); $container = $builder->build(); $service = $container->get(SomeService::class);
Post processors
Post processors transform the merged configuration, in the order they are added, before it is cached and applied. A post processor is a callable or an invokable class string, it receives the configuration array and must return an array. They do not run when the configuration comes from the cache.
$builder->addPostProcessor(static fn(array $config): array => $config + ['env' => 'production']);
A provider registered more than once throws a ProviderException.
Lazy proxies
Classes listed under AurynConfig::PROXY are created lazily through a ProxyFactoryInterface:
NativeProxyFactoryuses the PHP 8.4 native lazy objects, no extra dependency andfinalclasses are supported.ContainerBuilderuses it by default on PHP 8.4+.ProxyFactoryusesfriendsofphp/proxy-manager-lts, pass it explicitly on PHP 8.2 and 8.3.
$builder = new ContainerBuilder(null, null, null, new ProxyFactory());
Native lazy objects initialize on the first access to the object state, so a class without properties never calls its factory.
For more information on how to use Auryn\Injector see the Auryn README
Keep in mind that $injector->make(SomeClass::class) hides the word new and does the instantiation for you.
Do not use Injector as a service locator, or your server will blow up.
namespace MyApp; use ItalyStrap\Config\Config; use ItalyStrap\Config\ConfigFactory; use ItalyStrap\Config\ConfigInterface; use ItalyStrap\Empress\AurynConfigInterface; use ItalyStrap\Empress\AurynConfig; use ItalyStrap\Empress\Extension; use Auryn\Injector; /** * The better way to add keys to the array configuration is to use the * AurynConfig::<CONSTANT KEYS> * * Keys available are: * * AurynConfig::PROXY = 'proxies'; * AurynConfig::SHARING = 'sharing'; * AurynConfig::ALIASES = 'aliases'; * AurynConfig::DEFINITIONS = 'definitions'; * AurynConfig::DEFINE_PARAM = 'define_param'; * AurynConfig::DELEGATIONS = 'delegations'; * AurynConfig::FACTORIES = 'factories'; * AurynConfig::PREPARATIONS = 'preparations'; */ /** * First off all we need a configuration */ $config = [ /** * Example: * class MyCLass( ConfigInterface $config ) {} * You alias a `ConfigInterface::class` to `Config::class` * $injector->make(MyCLass::class); will be injected with a Config object * @see [Type-Hint Aliasing](https://github.com/rdlowrey/auryn#type-hint-aliasing) */ AurynConfig::ALIASES => [ ConfigInterface::class => Config::class, ], /** * Example: * class MyCLass( ConfigInterface $global_config, \stdClass $class ) {} * class MyOtherCLass( ConfigInterface $global_config, \stdClass $class ) {} * A new Config instance will be shared, think of it like a singleton but more better and OOP oriented (You can mock it ;-)) * The same instance of Config will be injected to MyCLass and MyOtherCLass * $injector->make(MyCLass::class); // Will have $global_config * $injector->make(MyOtherCLass::class); // Will have $global_config * @see [Instance Sharing](https://github.com/rdlowrey/auryn#instance-sharing) */ AurynConfig::SHARING => [ stdClass::class, ConfigInterface::class, ], /** * This is the new feature for the Auryn\Injector implemented in the bridge adapter * You usually need a lazy value holder in cases where the following applies: * * your object takes a lot of time and memory to be initialized (with all dependencies) * * your object is not always used, and the instantiation overhead is avoidable * * Example: * class HeavyComplexObject( ...HeavyDependency ){}; // Declared somewhere * $object = $injector->make(HeavyComplexObject::class); * add_{filter|action}( 'event_name', [ $object, 'doSomeStuff' ] ); * * You can proxies the `HeavyComplexObject::class` dependency * $injector->proxy(HeavyDependency::class); * Or the `HeavyComplexObject::class` * $injector->proxy(HeavyComplexObject::class); * * It depends on your business logic. * * Let see for example if you have proxies the HeavyComplexObject::class * * $proxy = $injector->make(HeavyComplexObject::class); * * Now $proxy will be the lazy version of the object (as a proxy) and when the event call it * add_{filter|action}( 'event_name', [ $proxy, 'doSomeStuff' ] ); * ::doSomeStuff() will just work as before. * * @see [Lazy Loading Value Holder Proxy](https://github.com/Ocramius/ProxyManager/blob/master/docs/lazy-loading-value-holder.md) */ AurynConfig::PROXY => [ Config::class, ], /** * Define global parameter * class SomeCLass(string $text) {} * class SomeOtherCLass(string $text) {} * $injector->make(SomeCLass::class); * $injector->make(SomeOtherCLass::class); * Now the `$text` param will be decorated with 'Some Text' * @see [Global Parameter Definitions](https://github.com/rdlowrey/auryn#global-parameter-definitions) */ AurynConfig::DEFINE_PARAM => [ 'text' => 'Some Text' ], /** * Definition for class specific * Example: * class Example(int $param) {} * Now the `$param` will be decorated with 42 * class OtherExample(int $param) {} * This will not be decorated with 42 because you have defined only the Example::class parameter * @see [Injection Definitions](https://github.com/rdlowrey/auryn#injection-definitions) */ AurynConfig::DEFINITIONS => [ Example::class => [ ':param' => 42, ] ], /** * As soon as the instance is created you can prepare some action before use the new created instance * This is the same as: * $class = new \stdClass; * $class->param = 42; * echo $class->param; * @see [Prepares and Setter Injection](https://github.com/rdlowrey/auryn#prepares-and-setter-injection) */ AurynConfig::PREPARATIONS => [ stdClass::class => function ( stdClass $class, Injector $injector ) { $class->param = 42; }, ], /** * You can delegate the instantiation of an object to a some kind of callable factory * This will be always used to get the instance of a class. * @see [Instantiation Delegates](https://github.com/rdlowrey/auryn#instantiation-delegates) */ AurynConfig::DELEGATIONS => [ ConfigInterface::class => [ ConfigFactory::class, 'make'] ], ]; /** * Instantiate the Injector * Proxies need a ProxyFactoryInterface passed as third argument of AurynConfig. */ $injector = new Injector(); /** * Pass the $injector instance to the AurynConfig::class as first parameter and a * Config::class instance at the second parameters with the configuration array. */ $app = new AurynConfig( $injector, ( new ConfigFactory() )->make( $config ) ); /** * Call the AurynConfig::apply() method to do the autowiring of the application */ $app->apply(); /** * Now that you have autoload your application dependency you can call $injector for instantiating objects * when you need them */ $example = $injector->make( Example::class ); // $example instanceof Example::class
Advanced Usage
namespace MyApp; use ItalyStrap\Config\Config; use ItalyStrap\Config\ConfigFactory; use ItalyStrap\Config\ConfigInterface; use ItalyStrap\Empress\AurynConfigInterface; use ItalyStrap\Empress\AurynConfig; use ItalyStrap\Empress\Extension; use Auryn\Injector; $config = [ 'your-key' => [ 'Key' => 'Value', ], ]; $injector = new Injector(); $app = new AurynConfig( $injector, ( new ConfigFactory() )->make( $config ) ); /** * If you need more power you can extend the AurynConfig::class BEFORE calling the AurynConfig::apply() method * Create your custom configuration like the follow: * $config = [ * 'your-key' => [ * 'Key' => 'Value', * ], * ]; * * Now extend the AurynConfig: */ $app->extend( new class implements Extension { /** @var string */ const YOUR_KEY = 'your-key'; public function name(): string { return (string) self::YOUR_KEY; } /** * Called inside the AurynConfig instance * @param AurynConfigInterface $application */ public function execute( AurynConfigInterface $application ): void { /** * ::walk() accept: * self::YOUR_KEY will be a key to search against the config array * [ $this, 'doSomeStuff' ] will be a valid callable to do the work you need. */ $application->walk( (string) self::YOUR_KEY, [$this, 'doSomeStuff'] ); } /** * @param string $array_value Array value from yous configuration * @param int|string $array_key Array key from your configuration * @param Injector $injector An instance of the Injector::class */ public function doSomeStuff( string $array_value, $array_key, Injector $injector ) { // Do your logic here } } ); /** * You can add as many extensions as you need * Now you can call the ::apply() method */ $app->apply(); // Do the rest of your stuff
Contributing
All feedback / bug reports / pull requests are welcome.
License
Copyright (c) 2019 Enea Overclokk, ItalyStrap
This code is licensed under the MIT.
Notes
- Maintained under the Semantic Versioning Guide