lorenzo / piping-bag
CakePHP 4 plugin for using Ray.Di as a Dependency Injection Container
Installs: 104 773
Dependents: 1
Suggesters: 1
Security: 0
Stars: 35
Watchers: 5
Forks: 9
Open Issues: 1
Type:cakephp-plugin
Requires
- ray/di: ^2.1
Requires (Dev)
README
This plugin adds the ability to configure object instances and their dependencies before they are used, and to store them into a container class to easy access.
It uses the clean and flexible Ray.Di Library which is a PHP dependency injection framework in the style of "Google Guice".
Ray.Di also allows you to program using AOP
, that is, decorating the configured instances so some logic
can be run before or after any of their methods.
Installation
You can install this plugin into your CakePHP application using composer.
composer require lorenzo/piping-bag=dev-master
Configuration
Upgrading from library version 1.x (Cake 3.x)
DEPRECATED:
ControllerFactoryFilter.php
for injecting controllersShellDispatcher.php
for injecting shell classes
Remove the following lines in your:
config/bootstrap.php
:
DispatcherFactory::add('PipingBag\Routing\Filter\ControllerFactoryFilter'); Plugin::load('PipingBag', ['bootstrap' => true]);
Controller Injection
For getting injection in your controllers to work you need to add the following line in the bootstrap
method
of your Application.php
:
$this->addPlugin('PipingBag', ['bootstrap' => true]); $this->controllerFactory = new \PipingBag\Controller\DIControllerFactory();
Shell Injection
For getting injection in your controllers to work you need to add the following line of your bin/cake.php
:
$commandFactory = new \PipingBag\Console\DICommandFactory(); $runner = new CommandRunner(new Application(dirname(__DIR__) . '/config'), 'cake', $commandFactory);
Additionally, you can configure the modules to be used and caching options in your config/app.php
file.
'PipingBag' => [ 'modules' => ['MyWebModule', 'AnotherModule', 'APlugin.SuperModule'], 'cacheConfig' => 'default' ]
Modules can also be returned as instances in the configuration array:
'PipingBag' => [ 'modules' => [new App\Di\Module\MyWebModule()], 'cacheConfig' => 'default' ]
Finally, if you wish to tune your modules before they are registered, you can use a callable function:
'PipingBag' => [ 'modules' => function () { return [new MyWebModule()]; }, 'cacheConfig' => 'default' ]
What is a Module anyway?
Modules are classes that describe how instances and their dependencies should be constructed, they provide a natural way of grouping configurations. An example module looks like this:
// in app/src/Di/Module/MyModule.php namespace App\Di\Module; use Ray\Di\AbstractModule; class MyModule extends AbstractModule { public function configure() { $this->bind('MovieApp\FinderInterface')->to('MovieApp\Finder'); $this->bind('MovieApp\HttpClientInterface')->to('Guzzle\HttpClient'); $this->install(new OtherModule()); // Modules can install other modules } }
Modules are, by convention, placed in your src/Di/Module
folder. Read more about creating modules and
how to bind instances to names in the Official Ray.Di Docs.
Usage
After creating and passing the modules in the configuration, you can get instance of any class and have their dependencies resolved following the rules created in the modules:
use PipingBag\Di\PipingBag; $httpClient = PipingBag::get('MovieApp\HttpClientInterface');
Injecting Dependencies in Controllers
Ray.Di is able to inject instances to your controllers based on annotations:
// in src/Controller/ArticlesController.php use App\Controller\AppController; use MovieApp\HttpClientInterface; use Ray\Di\Di\Inject; // This is important class ArticlesController extends AppController { /** * @Inject */ public function setHttpClient(HttpClientInterface $connection) { $this->httpClient = $connection; } }
As soon as the controller is created, all methods having the @Inject
annotation will get
instances of the hinted class passed. This works for constructors as well.
Injecting Dependencies in Controller Actions
It is also possible to inject dependencies directly in the controller actions. When doing this,
add the type-hinted dependency to the end of the arguments and set the default value to null
,
it is also required to annotate the method using @Assisted
// in src/Controller/ArticlesController.php use App\Controller\AppController; use MovieApp\HttpClientInterface; use PipingBag\Annotation\Assisted; // This is important class ArticlesController extends AppController { /** * @Assisted */ public function edit($id, HttpClientInterface $connection = null) { $article = $this->Articles->get($id) $connection->post(...); } }
Injecting Dependencies in Shells
Shells are also able to receive dependencies via the @Inject
annotation. But first, you need
to change the cake console executable to use PipingBag. Open your bin/cake.php
file and make
it look like this:
// bin/cake.php ... exit(PipingBag\Console\ShellDispatcher::run($argv)); // Changed namespace of ShellDispatcher
Then you can apply annotations to your shells:
use Cake\Console\Shell; use Ray\Di\Di\Inject; // This is important class MyShell extends Shell { /** * @Inject */ public function setHttpClient(HttpClientInterface $connection) { $this->httpClient = $connection; } }