Dice PHP Dependency Injection Container

As of version 4.0, Dice is immutable. Methods that modify the container configuration, such as addRule() and addRules(), do not change the existing instance but instead return a new Dice instance containing the updated rules. You must reassign the result to your variable to persist configuration changes.

// Correct way to add rules in 4.0+
$dice = $dice->addRule('PDO', ['shared' => true]);

$db = $dice->create('PDO');

To prevent Dice from immediately executing a closure passed as a parameter (such as in constructParams or call), you must wrap the closure in a \Dice\Instance object. This tells Dice to treat the closure as a provider for a value rather than a value to be executed immediately.

use \Dice\Instance;

$rule->constructParams[] = [
    'instance' => function() {
        return 'abc';
    }
];

Dice is a lightweight, single-file dependency injection container. To use it, simply include the Dice.php file in your project. It requires no further configuration to start working with basic class dependencies.

<?php
class A {
	public $b;
	public function __construct(B $b) {
		$this->b = $b;
	}
}

class B {}

require_once 'Dice.php';
$dice = new \Dice\Dice;

$a = $dice->create('A');

var_dump($a->b); // Returns B object

Instead of adding rules one by one, use addRules() to pass an associative array of multiple configurations. This is the preferred method for bulk configuration and is often used in conjunction with json_decode to load rules from an external file.

$dice->addRules([
	'\PDO' => [
		'shared' => true
	],
	'Framework\Router' => [
		'constructParams' => ['Foo', 'Bar']
	]
]);

// Loading from a JSON file
$dice = $dice->addRules(json_decode(file_get_contents('rules.json')));

The primary method for retrieving objects from the container is create(string $className). Dice will automatically resolve dependencies by inspecting the constructor of the requested class via reflection. If no rules are defined, it attempts to instantiate the class with zero configuration.

$dice = new \Dice\Dice;
$instance = $dice->create('YourClassName');

Dice supports object method chaining (fluent interfaces) using the call rule combined with the Dice::CHAIN_CALL constant. This allows Dice to construct an object and then immediately call a sequence of methods on it, replacing the initial object with the result of the final call in the chain.

// Example: Configuring an HTTPRequest with a fluent interface
$dice = $dice->addRule('HTTPRequest', [
    'call' => [
        ['url', ['http://example.org'], \Dice\Dice::CHAIN_CALL],
        ['method', ['POST'], \Dice\Dice::CHAIN_CALL],
        ['postdata', ['foo=bar'], \Dice\Dice::CHAIN_CALL]
    ]
]);

$request = $dice->create('HTTPRequest');

When defining rules (especially via JSON), you can inject superglobals and PHP constants into object construction or method calls using special placeholders:

• Dice::GLOBAL: Used to reference superglobals like $_SERVER, $_GET, etc.
• Dice::CONSTANT: Used to reference PHP constants (e.g., PDO::ATTR_ERRMODE).

{
	"PDO": {
		"shared": true,
		"constructParams": [
			"mysql:dbname=testdb;host=127.0.0.1",
			"dbuser",
			"dbpass"
		],
		"call": [
			[
				"setAttribute",
				[
					{"Dice::CONSTANT": "PDO::ATTR_ERRMODE"},
						{"Dice::CONSTANT": "PDO::ERRMODE_EXCEPTION"}
				]
			]
		]
	}
}