Extra
5 years ago
Loader
5 years ago
tests
2 years ago
.gitignore
3 years ago
Dice.php
2 years ago
README.md
5 years ago
composer.json
5 years ago
phpunit.xml
5 years ago
README.md
366 lines
| 1 | [](https://r.je/dice.htmlDice PHP Dependency Injection Container](https://r.je/dice.html](https://r.je/dice.html) |
| 2 | ====================================== |
| 3 | |
| 4 | Dice is a minimalist Dependency Injection Container for PHP with a focus on being lightweight and fast as well as requiring as little configuration as possible. |
| 5 | |
| 6 | |
| 7 | Project Goals |
| 8 | ------------- |
| 9 | |
| 10 | 1) To be lightweight and not a huge library with dozens of files (Dice is a single 100 line class) yet support all features (and more) offered by much more complex containers |
| 11 | |
| 12 | 2) To "just work". Basic functionality should work with zero configuration |
| 13 | |
| 14 | 3) Where configuration is required, it should be as minimal and reusable as possible as well as easy to use. |
| 15 | |
| 16 | 4) Speed! (See [](#performancethe section on performance](#performance](#performance)) |
| 17 | |
| 18 | |
| 19 | Installation |
| 20 | ------------ |
| 21 | |
| 22 | Just include the lightweight `Dice.php` in your project and it's usable without any further configuration: |
| 23 | |
| 24 | Simple example: |
| 25 | |
| 26 | ```php |
| 27 | <?php |
| 28 | class A { |
| 29 | public $b; |
| 30 | |
| 31 | public function __construct(B $b) { |
| 32 | $this->b = $b; |
| 33 | } |
| 34 | } |
| 35 | |
| 36 | class B { |
| 37 | |
| 38 | } |
| 39 | |
| 40 | require_once 'Dice.php'; |
| 41 | $dice = new \Dice\Dice; |
| 42 | |
| 43 | $a = $dice->create('A'); |
| 44 | |
| 45 | var_dump($a->b); //B object |
| 46 | |
| 47 | ?> |
| 48 | ``` |
| 49 | |
| 50 | |
| 51 | Full Documentation |
| 52 | ------------------ |
| 53 | |
| 54 | For complete documentation please see the [Dice PHP Dependency Injection container home page](https://r.je/dice.html) |
| 55 | |
| 56 | |
| 57 | PHP version compatibility |
| 58 | ------------------------- |
| 59 | |
| 60 | Dice is compatible with PHP 7.0 and up, there are archived versions of Dice which support PHP 5.6 however this is no longer maintanied. |
| 61 | |
| 62 | |
| 63 | Performance |
| 64 | ----------- |
| 65 | |
| 66 | Dice uses reflection which is often wrongly labelled "slow". Reflection is considerably faster than loading and parsing a configuration file. There are a set of benchmarks [here](https://rawgit.com/TomBZombie/php-dependency-injection-benchmarks/master/test1-5_results.html) and [here](https://rawgit.com/TomBZombie/php-dependency-injection-benchmarks/master/test6_results.html) (To download the benchmark tool yourself see [this repository](https://github.com/TomBZombie/php-dependency-injection-benchmarks)) and Dice is faster than the others in most cases. |
| 67 | |
| 68 | In the real world test ([test 6](https://rawgit.com/TomBZombie/php-dependency-injection-benchmarks/master/test6_results.html)) Dice is neck-and-neck with Pimple (which requires writing an awful lot of configuration code) and although Symfony\DependencyInjection is faster at creating objects, it has a larger overhead and you need to create over 500 objects on each page load until it becomes faster than Dice. The same is true of Phalcon, the overhead of loading the Phalcon extension means that unless you're creating well over a thousand objects per HTTP request, the overhead is not worthwhile. |
| 69 | |
| 70 | |
| 71 | Credits |
| 72 | ------------ |
| 73 | |
| 74 | Originally developed by Tom Butler (@TomBZombie), with many thanks to daniel-meister (@daniel-meister), Garrett W. (@garrettw), maxwilms (@maxwilms) for bug fixes, suggestions and improvements. |
| 75 | |
| 76 | |
| 77 | Updates |
| 78 | ------------ |
| 79 | |
| 80 | ### 15/11/2018 4.0 Release - Backwards incompatible |
| 81 | |
| 82 | Dice is now immutable and has better support for other immutable objects. |
| 83 | |
| 84 | **New Features** |
| 85 | |
| 86 | #### 1. Dice is Immutable |
| 87 | |
| 88 | This avoids [issues surrounding mutability](https://www.yegor256.com/2014/06/09/objects-should-be-immutable.html) where a Dice instance is passed around the application and reconfigured. The only difference is that `addRules` and `addRule` return a new Dice instance with the updated rules rather than changing the state of the existing instance. |
| 89 | |
| 90 | ```php |
| 91 | |
| 92 | // Pre-4.0 code: |
| 93 | $dice->addRule('PDO', ['shared' => true]); |
| 94 | |
| 95 | $db = $dice->create('PDO'); |
| 96 | |
| 97 | // 4.0 code: |
| 98 | $dice = $dice->addRule('PDO', ['shared' => true]); |
| 99 | |
| 100 | $db = $dice->create('PDO'); |
| 101 | ``` |
| 102 | |
| 103 | From a practical perspective in most cases just put `$dice = ` in front of any `$dice->addRule()` call and it will work as before. |
| 104 | |
| 105 | #### 2. Support for Object Method Chaining |
| 106 | |
| 107 | One feature some immutable objects have is they offer object chaining. |
| 108 | |
| 109 | Consider the following Object: |
| 110 | |
| 111 | ```php |
| 112 | |
| 113 | $httpRequest = new HTTPRequest(); |
| 114 | $httpRequest = $httpRequest->url('http://example.org')->method('POST')->postdata('foo=bar'); |
| 115 | ``` |
| 116 | |
| 117 | It was not possible for Dice to consturuct the configured object in previous versions. As of 4.0 Dice supports chaining method call using the `call` rule and the `Dice::CHAIN_CALL` constant: |
| 118 | |
| 119 | ```php |
| 120 | $dice = $dice->addRule('HTTPRequest', |
| 121 | ['call' => [ |
| 122 | ['url', ['http://example.org'], Dice::CHAIN_CALL], |
| 123 | ['method', ['POST'], Dice::CHAIN_CALL ], |
| 124 | ['postdata', ['foo=bar'], Dice::CHAIN_CALL] |
| 125 | ] |
| 126 | ] |
| 127 | ); |
| 128 | ``` |
| 129 | |
| 130 | Dice will replace the HTTPRequest object with the result of the chained call. This is also useful for factories: |
| 131 | |
| 132 | |
| 133 | ```php |
| 134 | $dice = $dice->addRule('MyDatabase', |
| 135 | [ |
| 136 | 'instanceOf' => 'DatabaseFactory', |
| 137 | 'call' => [ |
| 138 | ['get', ['Database'], Dice::CHAIN_CALL] |
| 139 | ] |
| 140 | ] |
| 141 | ); |
| 142 | |
| 143 | $database = $dice->create('MyDatabase'); |
| 144 | //Equivalent of: |
| 145 | |
| 146 | $factory = new DatabaseFactory(); |
| 147 | $database = $factory->get('Database'); |
| 148 | ``` |
| 149 | |
| 150 | |
| 151 | ### 06/03/2018 3.0 Release - Backwards incompatible |
| 152 | |
| 153 | **New Features** |
| 154 | |
| 155 | #### 1. The JSON loader has been removed in favour of a new `addRules` method. |
| 156 | |
| 157 | ```php |
| 158 | $dice->addRules([ |
| 159 | '\PDO' => [ |
| 160 | 'shared' => true |
| 161 | ], |
| 162 | 'Framework\Router' => [ |
| 163 | 'constructParams' => ['Foo', 'Bar'] |
| 164 | ] |
| 165 | ]); |
| 166 | ``` |
| 167 | |
| 168 | The purpose of this addition is to make the JSON loader redundant. Loading of rules from a JSON file can easily be achieved with the code: |
| 169 | |
| 170 | ```php |
| 171 | $dice->addRules(json_decode(file_get_contents('rules.json'))); |
| 172 | ``` |
| 173 | |
| 174 | #### 2. Better JSON file support: constants and superglobals |
| 175 | |
| 176 | In order to improve support for rules being defined in external JSON files, constants and superglobals can now be passed into objects created by Dice. |
| 177 | |
| 178 | For example, passing the `$_SERVER` superglobal into a router instance and calling PDO's `setAttribute` with `PDO::ATTR_ERRMODE` and `PDO::ERRMODE_EXCEPTION` can be achieved like this in a JSON file: |
| 179 | |
| 180 | _rules.json_ |
| 181 | |
| 182 | ```json |
| 183 | { |
| 184 | "Router": { |
| 185 | "constructParams": [ |
| 186 | {"Dice::GLOBAL": "_SERVER"} |
| 187 | ] |
| 188 | }, |
| 189 | "PDO": { |
| 190 | "shared": true, |
| 191 | "constructParams": [ |
| 192 | "mysql:dbname=testdb;host=127.0.0.1", |
| 193 | "dbuser", |
| 194 | "dbpass" |
| 195 | ], |
| 196 | "call": [ |
| 197 | [ |
| 198 | "setAttribute", |
| 199 | [ |
| 200 | {"Dice::CONSTANT": "PDO::ATTR_ERRMODE"}, |
| 201 | {"Dice::CONSTANT": "PDO::ERRMODE_EXCEPTION"} |
| 202 | ] |
| 203 | ] |
| 204 | ] |
| 205 | } |
| 206 | } |
| 207 | ``` |
| 208 | |
| 209 | ```php |
| 210 | $dice->addRules(json_decode(file_get_contents('rules.json'))); |
| 211 | ``` |
| 212 | |
| 213 | **Backwards incompatible changes** |
| 214 | |
| 215 | 1. Dice 3.0 requires PHP 7.0 or above, PHP 5.6 is no longer supported. |
| 216 | |
| 217 | 2. Dice no longer supports `'instance'` keys to signify instances. For example: |
| 218 | |
| 219 | ```php |
| 220 | $dice->addRule('ClassName', [ |
| 221 | 'constructParams' => ['instance' => '$NamedPDOInstance'] |
| 222 | ]); |
| 223 | ``` |
| 224 | |
| 225 | As noted in issue #125 this made it impossible to pass an array to a constructor if the array had a key `'instance'`. Instead, the new `\Dice\Dice::INSTANCE` constant should be used: |
| 226 | |
| 227 | ```php |
| 228 | $dice->addRule('ClassName', [ |
| 229 | 'constructParams' => [\Dice\Dice::INSTANCE => '$NamedPDOInstance'] |
| 230 | ]); |
| 231 | ``` |
| 232 | _to make the constant shorter to type out, you can `use PrestoPlayer\\Dice\Dice;` and reference `Dice::INSTANCE`_ |
| 233 | |
| 234 | 10/06/2016 |
| 235 | |
| 236 | ** Backwards incompatible change ** |
| 237 | |
| 238 | Based on [Issue 110](https://github.com/Level-2/Dice/pull/110) named instances using `instanceOf` will now inherit the rules applied to the class they are instances of: |
| 239 | |
| 240 | ```php |
| 241 | |
| 242 | $rule = []; |
| 243 | $rule['shared'] = true; |
| 244 | |
| 245 | $dice->addRule('MyClass', $rule); |
| 246 | |
| 247 | $rule = []; |
| 248 | $rule['instanceOf'] = 'MyClass'; |
| 249 | $rule['constructParams'] = ['Foo', 'Bar']; |
| 250 | |
| 251 | $dice->addRule('$MyNamedInstance', $rule); |
| 252 | |
| 253 | |
| 254 | ``` |
| 255 | |
| 256 | `$dice->create('$MyNamedInstance')` will now create a class following the rules applied to both `MyClass` and `$MyNamedInstance` so the instance will be shared. |
| 257 | |
| 258 | Previously only the rules applied to the named instance would be used. |
| 259 | |
| 260 | To restore the old behaviour, set `inherit` to `false` on the named instance: |
| 261 | |
| 262 | ```php |
| 263 | $rule = []; |
| 264 | $rule['shared'] = true; |
| 265 | |
| 266 | $dice->addRule('MyClass', $rule); |
| 267 | |
| 268 | $rule = []; |
| 269 | $rule['instanceOf'] = 'MyClass'; |
| 270 | $rule['constructParams'] = ['Foo', 'Bar']; |
| 271 | |
| 272 | |
| 273 | //Prevent the named instance inheriting rules from the class named in `instanceOf`: |
| 274 | $rule['inherit'] = false; |
| 275 | |
| 276 | $dice->addRule('$MyNamedInstance', $rule); |
| 277 | |
| 278 | ``` |
| 279 | |
| 280 | |
| 281 | |
| 282 | |
| 283 | 29/10/2014 |
| 284 | * Based on [Issue #15](https://github.com/TomBZombie/Dice/issues/15), Dice will now only call closures if they are wrapped in \Dice\Instance. **PLEASE NOTE: THIS IS BACKWARDS INCOMPATIBLE **. |
| 285 | |
| 286 | Previously Dice ran closures that were passed as substitutions, constructParams and when calling methods: |
| 287 | |
| 288 | ```php |
| 289 | |
| 290 | $rule->substitutions['A'] = function() { |
| 291 | return new A; |
| 292 | }; |
| 293 | |
| 294 | $rule->call[] = ['someMethod', function() { |
| 295 | // '2' will be provided as the first argument when someMethod is called |
| 296 | return 2; |
| 297 | }]; |
| 298 | |
| 299 | $rule->constructParams[] = function() { |
| 300 | //'abc' will be providedas the first constructor parameter |
| 301 | return 'abc'; |
| 302 | }; |
| 303 | ``` |
| 304 | |
| 305 | This behaviour has changed as it makes it impossible to provide a closure as a construct parameter or when calling a method because the closure was always called and executed. |
| 306 | |
| 307 | To overcome this, Dice will now only call a closures if they're wrapped in \Dice\Instance: |
| 308 | |
| 309 | ```php |
| 310 | $rule->substitutions['A'] = ['instance' => function() { |
| 311 | return new A; |
| 312 | }]; |
| 313 | |
| 314 | $rule->call[] = ['someMethod', ['instance' => function() { |
| 315 | // '2' will be provided as the first argument when someMethod is called |
| 316 | return 2; |
| 317 | }]]); |
| 318 | |
| 319 | $rule->constructParams[] = ['instance' => function() { { |
| 320 | //'abc' will be providedas the first constructor parameter |
| 321 | return 'abc'; |
| 322 | }]); |
| 323 | ``` |
| 324 | |
| 325 | |
| 326 | |
| 327 | |
| 328 | |
| 329 | 04/09/2014 |
| 330 | * Pushed PHP5.6 branch live. This is slightly more efficient using PHP5.6 features. For PHP5.4-PHP5.5 please see the relevant branch. This version will be maintained until PHP5.6 is more widespread. |
| 331 | |
| 332 | |
| 333 | 26/08/2014 |
| 334 | * Added PHP5.6 branch. Tidied up code by using PHP5.6 features. This will be moved to master when PHP5.6 is released |
| 335 | |
| 336 | 28/06/2014 |
| 337 | * Greatly improved efficienty. Dice is now the fastest Dependency Injection Container for PHP! |
| 338 | |
| 339 | 06/06/2014 |
| 340 | * Added support for cyclic references ( https://github.com/TomBZombie/Dice/issues/7 ). Please note this is poor design but this fix will stop the infinite loop this design creates. |
| 341 | |
| 342 | 27/03/2014 |
| 343 | * Removed assign() method as this duplicated functionality available using $rule->shared |
| 344 | * Removed $callback argument in $dice->create() as the only real use for this feature can be better achieved using $rule->shareInstances |
| 345 | * Tidied up code, removing unused/undocumented features. Dice is now even more lightweight and faster. |
| 346 | * Fixed a bug where when using $rule->call it would use the substitution rules from the constructor on each method called |
| 347 | * Updated [Dice documentation](https://r.je/dice.html) to use shorthand array syntax |
| 348 | |
| 349 | 01/03/2014 |
| 350 | * Added test cases for the Xml Loader and Loader Callback classes |
| 351 | * Added a JSON loader + test case |
| 352 | * Added all test cases to a test suite |
| 353 | * Moved to PHP5.4 array syntax. A PHP5.3 compatible version is now available in the PHP5.3 branch. |
| 354 | * Fixed an issue where using named instances would trigger the autoloader with an invalid class name every time a class was created |
| 355 | |
| 356 | |
| 357 | 28/02/2014 |
| 358 | * Added basic namespace PrestoPlayer\support. Documentation update will follow shortly. Also moved the XML loader into its own file, you'll need to include it separately if you're using it. |
| 359 | * Please note: CHANGES ARE NOT BACKWARDS COMPATIBLE. However they are easily fixed by doing the following find/replaces: |
| 360 | |
| 361 | ```php |
| 362 | new Dice => new \Dice\Dice |
| 363 | new DiceInstance => new \Dice\Instance |
| 364 | new DiceRule => new \Dice\Rule |
| 365 | ``` |
| 366 |