Dice

https://github.com/level-2/dice
Admin
Dice is a dependency injection container for PHP that creates objects and resolves their constructor...
Tokens:21,297
Snippets:158
Trust Score:5.9
Update:3 days ago
Show doc for...
Tokens:
Raw
### JSON rules file with constants and superglobals

Source: https://github.com/level-2/dice/blob/master/README.md

Example rules.json demonstrating passing $_SERVER superglobal and PDO constants via Dice::GLOBAL and Dice::CONSTANT.

```json
{
	"Router": {
		"constructParams": [
			{"Dice::GLOBAL": "_SERVER"}
		]
	},
	"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"}
						]
					]
		]
	}
}
```

--------------------------------

### Basic Dice usage with constructor injection

Source: https://github.com/level-2/dice/blob/master/README.md

Shows minimal setup: define classes A and B, include Dice.php, create container, and instantiate A with B auto-injected. Requires PHP 7.0+ and Dice.php in the project. Output is a B object as shown by var_dump.

```php
<?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); //B object

?>
```

--------------------------------

### Object method chaining example with HTTPRequest

Source: https://github.com/level-2/dice/blob/master/README.md

Illustrates a fluent interface object that Dice can now construct using the call rule and Dice::CHAIN_CALL constant.

```php
$httpRequest = new HTTPRequest();
$httpRequest = $httpRequest->url('http://example.org')->method('POST')->postdata('foo=bar');
```

--------------------------------

### Old 'instance' key usage (deprecated)

Source: https://github.com/level-2/dice/blob/master/README.md

Shows the pre-3.0 way of passing a named instance using the 'instance' key, which is no longer supported.

```php
$dice->addRule('ClassName', [
	'constructParams' => ['instance' => '$NamedPDOInstance']
]);
```

--------------------------------

### getRule usage example

Source: https://github.com/level-2/dice

Shows how to retrieve a rule after adding it, and that missing rules return an empty array.

```php
$dice = $dice->addRule('A', ['shared' => true]);

$rule = $dice->getRule('A');   // ['shared' => true]
$none = $dice->getRule('B');   // []
```

--------------------------------

### Loading rules from a JSON file with addRules

Source: https://github.com/level-2/dice/blob/master/README.md

Shows how to load rules from a JSON file using json_decode and file_get_contents, replacing the removed JSON loader.

```php
$dice->addRules(json_decode(file_get_contents('rules.json')));
```

--------------------------------

### Factory pattern with Dice::CHAIN_CALL for MyDatabase

Source: https://github.com/level-2/dice/blob/master/README.md

Uses a factory class to create a Database instance. Dice replaces the MyDatabase object with the result of the chained get call.

```php
$dice = $dice->addRule('MyDatabase',
                [
                	'instanceOf' => 'DatabaseFactory',
                	'call' => [
                		['get', ['Database'], Dice::CHAIN_CALL]
                 ]
                ]
);

$database = $dice->create('MyDatabase');
//Equivalent of:

$factory = new DatabaseFactory();
$database = $factory->get('Database');
```

--------------------------------

### Adding multiple rules with addRules method

Source: https://github.com/level-2/dice/blob/master/README.md

Shows the new addRules method for defining multiple rules at once, replacing the removed JSON loader.

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

--------------------------------

### New \Dice\Dice::INSTANCE constant usage

Source: https://github.com/level-2/dice/blob/master/README.md

Replaces the removed 'instance' key with the \Dice\Dice::INSTANCE constant to pass named instances.

```php
$dice->addRule('ClassName', [
	'constructParams' => [\Dice\Dice::INSTANCE => '$NamedPDOInstance']
]);
```

--------------------------------

### Namespace migration find/replace for Dice classes

Source: https://github.com/level-2/dice/blob/master/README.md

Find/replace pairs to migrate to the new namespace structure introduced on 28/02/2014. These changes are not backwards compatible.

```php
new Dice => new \Dice\Dice
```

```php
new DiceInstance => new \Dice\Instance
```

```php
new DiceRule => new \Dice\Rule
```

--------------------------------

### Named instance inheriting rules from instanceOf class

Source: https://github.com/level-2/dice/blob/master/README.md

Shows how named instances using instanceOf inherit rules from the class they are instances of, with shared rule applied.

```php
$rule = [];
$rule['shared'] = true;

$dice->addRule('MyClass', $rule);

$rule = [];
$rule['instanceOf'] = 'MyClass';
$rule['constructParams'] = ['Foo', 'Bar'];

$dice->addRule('$MyNamedInstance', $rule);
```

--------------------------------

### Define shared rule and named instance with inherit=false

Source: https://github.com/level-2/dice/blob/master/README.md

Shows how to add a shared rule for a class and create a named instance with construct parameters while preventing inheritance from the class rule using 'inherit' => false.

```php
$rule = [];
$rule['shared'] = true;

$dice->addRule('MyClass', $rule);

$rule = [];
$rule['instanceOf'] = 'MyClass';
$rule['constructParams'] = ['Foo', 'Bar'];


//Prevent the named instance inheriting rules from the class named in `instanceOf`:
$rule['inherit'] = false;

$dice->addRule('$MyNamedInstance', $rule);
```

--------------------------------

### New closure behavior wrapped in \Dice\Instance

Source: https://github.com/level-2/dice/blob/master/README.md

Updated syntax requiring closures to be wrapped in an array with 'instance' key so they are only called when explicitly wrapped. This replaces the old automatic closure execution.

```php
$rule->substitutions['A'] = ['instance' => function() {
	return new A;
}];

$rule->call[] = ['someMethod', ['instance' => function() {
// '2' will be provided as the first argument when someMethod is called
return 2;
}]]);

$rule->constructParams[] =  ['instance' => function() { {
	//'abc' will be providedas the first constructor parameter
	return 'abc';
}]);
```

--------------------------------

### create usage: delegate to wrapped Dice

Source: https://github.com/level-2/dice

Calls create() on the validator, which delegates to the wrapped Dice instance. The example creates an instance of 'PDO' with no extra arguments.

```php
$obj = $validator->create('PDO');
```

--------------------------------

### Old closure behavior for substitutions, calls, and constructParams

Source: https://github.com/level-2/dice/blob/master/README.md

Deprecated behavior where closures passed as substitutions, call arguments, or construct params were automatically executed. This changed in version 29/10/2014 and is backwards incompatible.

```php
$rule->substitutions['A'] = function() {
	return new A;
};

$rule->call[] = ['someMethod', function() {
// '2' will be provided as the first argument when someMethod is called
return 2;
}];

$rule->constructParams[] = function() {
	//'abc' will be providedas the first constructor parameter
	return 'abc';
};
```

--------------------------------

### Dice rule for chaining method calls with Dice::CHAIN_CALL

Source: https://github.com/level-2/dice/blob/master/README.md

Configures Dice to build an HTTPRequest by chaining url, method, and postdata calls. Dice replaces the object with the result of the chained call.

```php
$dice = $dice->addRule('HTTPRequest',
                ['call' => [
                    ['url', ['http://example.org'], Dice::CHAIN_CALL],
                    ['method', ['POST'], Dice::CHAIN_CALL ],
                    ['postdata', ['foo=bar'], Dice::CHAIN_CALL]
                 ]
                ]
);
```

--------------------------------

### Pre-4.0 vs 4.0 addRule usage for immutability

Source: https://github.com/level-2/dice/blob/master/README.md

Shows the change from mutable to immutable Dice. In 4.0, addRule returns a new Dice instance, so assign the result back to $dice.

```php
// Pre-4.0 code:
$dice->addRule('PDO', ['shared' => true]);

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

// 4.0 code:
$dice = $dice->addRule('PDO', ['shared' => true]);

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

--------------------------------

### Catch Rule option must be true or false exception

Source: https://github.com/level-2/dice

Triggered when addRule() sets 'inherit' or 'shared' to a non-boolean value. The exception message includes the offending key.

```php
try {
    $validator->addRule('A', ['shared' => 'maybe']);
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // "Rule option shared must be true or false"
}
```

--------------------------------

### Catch Rule option must be a sequential array exception

Source: https://github.com/level-2/dice

Triggered when addRule() sets 'constructParams', 'shareInstances', or 'call' to an associative array. The exception message includes the offending key and the typo 'seqential' as in the source.

```php
try {
    $validator->addRule('A', ['constructParams' => ['x' => 1, 'y' => 2]]);
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // "Rule option constructParams must be a seqential array not an associative array"
}
```

--------------------------------

### Catch ErrorException for non-existent class

Source: https://github.com/level-2/dice

Use when Dice::create() references a class that cannot be loaded by reflection. This causes a PHP-level ErrorException (or E_ERROR), not a caught exception. The catch block handles the reflection failure.

```php
try {
    $dice->create('ClassThatDoesNotExist');
} catch (\ErrorException $e) {
    // PHP could not reflect/construct the class
}
```

--------------------------------

### addRule basic usage: validate and apply a rule

Source: https://github.com/level-2/dice

Validates the rule array (checking keys, booleans, and numeric arrays) then applies it to the wrapped Dice container. The example adds a rule for 'PDO' with shared=true and constructor parameters.

```php
$dice = new \Dice\Dice;
$validator = new \Dice\Extra\RuleValidator($dice);

$validator->addRule('PDO', ['shared' => true, 'constructParams' => ['dsn', 'user', 'pass']]);
```

--------------------------------

### Catch XML loader deprecation warning with custom handler

Source: https://github.com/level-2/dice

Use set_error_handler() to intercept the E_USER_WARNING emitted by Xml::load() and handle it with a custom callback. Remember to call restore_error_handler() after loading to revert to the previous handler.

```php
// Or catch to a custom handler
set_error_handler(function ($severity, $message) {
    echo "Warning: $message\n";
});
$rules = $loader->load('rules.xml');
restore_error_handler();
```

--------------------------------

### Catch InvalidArgumentException for interface instantiation

Source: https://github.com/level-2/dice

Use when Dice::create() targets an interface. Dice substitutes a closure that throws \InvalidArgumentException('Cannot instantiate interface') instead of a PHP fatal error. The catch block prints the exception message.

```php
try {
    $dice->create('SomeInterface');
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // "Cannot instantiate interface"
}
```

--------------------------------

### \InvalidArgumentException('Rule option ' . $key . ' must be true or false')

Source: https://github.com/level-2/dice

Thrown when Dice\Extra\RuleValidator::addRule() sets 'inherit' or 'shared' to a non-boolean value. Catch this exception to handle invalid boolean rule options.

```APIDOC
## \InvalidArgumentException('Rule option ' . $key . ' must be true or false')

### Description
Thrown when `Dice\Extra\RuleValidator::addRule()` sets `inherit` or `shared` to a non-boolean value.

### Trigger Condition
`Dice\Extra\RuleValidator::addRule()` sets `inherit` or `shared` to a non-boolean value (`checkBoolean()` first checks `inherit`, then `shared`).

### Source Location
`Dice\Extra\RuleValidator::checkBoolean()`, `Extra/RuleValidator.php:31-35`.

### How to Catch
```php
try {
    $validator->addRule('A', ['shared' => 'maybe']);
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // "Rule option shared must be true or false"
}
```
```

--------------------------------

### Suppress XML loader deprecation warning

Source: https://github.com/level-2/dice

Pass false as the third argument to Xml::load() to suppress the E_USER_WARNING about the XML loader's pending removal. The warning is emitted by default when $displayWarning is true.

```php
// Suppress the warning entirely
$rules = $loader->load('rules.xml', $dice, false);
```

--------------------------------

### Catch Invalid rule option exception

Source: https://github.com/level-2/dice

Triggered when addRule() receives a rule with a key not in the valid set ['call', 'shared', 'substitutions', 'instanceOf', 'inherit', 'shareInstances', 'constructParams']. The exception message includes the invalid key.

```php
try {
    $validator->addRule('A', ['notARealOption' => 1]);
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // "Invalid rule option: notARealOption"
}
```

--------------------------------

### \InvalidArgumentException('Rule option ' . $key . ' must be a seqential array not an associative array')

Source: https://github.com/level-2/dice

Thrown when Dice\Extra\RuleValidator::addRule() sets 'constructParams', 'shareInstances', or 'call' to an associative array instead of a sequential array. Catch this exception to handle invalid array rule options.

```APIDOC
## \InvalidArgumentException('Rule option ' . $key . ' must be a seqential array not an associative array')

### Description
Thrown when `Dice\Extra\RuleValidator::addRule()` sets `constructParams`, `shareInstances`, or `call` to an associative array (contains any string key) rather than a sequential array.

### Trigger Condition
`Dice\Extra\RuleValidator::addRule()` sets `constructParams`, `shareInstances`, or `call` to an associative array. Check order: `constructParams`, then `shareInstances`, then `call`. *(Note: "seqential" is a typo in the source, reproduced verbatim.)*

### Source Location
`Dice\Extra\RuleValidator::checkNumericArray()`, `Extra/RuleValidator.php:37-42`.

### How to Catch
```php
try {
    $validator->addRule('A', ['constructParams' => ['x' => 1, 'y' => 2]]);
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // "Rule option constructParams must be a seqential array not an associative array"
}
```
```

--------------------------------

### \InvalidArgumentException('Invalid rule option: ' . $name)

Source: https://github.com/level-2/dice

Thrown when Dice\Extra\RuleValidator::addRule() receives a rule containing a key not in the valid set ['call', 'shared', 'substitutions', 'instanceOf', 'inherit', 'shareInstances', 'constructParams']. Catch this exception to handle invalid rule options.

```APIDOC
## \InvalidArgumentException('Invalid rule option: ' . $name)

### Description
Thrown when `Dice\Extra\RuleValidator::addRule()` receives a rule containing a key not in the valid set `['call', 'shared', 'substitutions', 'instanceOf', 'inherit', 'shareInstances', 'constructParams']`.

### Trigger Condition
`Dice\Extra\RuleValidator::addRule()` receives a rule containing a key not in the valid set.

### Source Location
`Dice\Extra\RuleValidator::checkValidKeys()`, `Extra/RuleValidator.php:20-25`.

### How to Catch
```php
try {
    $validator->addRule('A', ['notARealOption' => 1]);
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // "Invalid rule option: notARealOption"
}
```
```

--------------------------------

### Basic auto-wiring with create()

Source: https://github.com/level-2/dice

Creates an instance of class A, automatically injecting a B instance into its constructor. The var_dump confirms the injection works.

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

$dice = new \Dice\Dice;
$a = $dice->create('A');
var_dump($a->b instanceof B); // true
```

--------------------------------

### Shared instance and extra args with create()

Source: https://github.com/level-2/dice

Shows that when a rule marks A as shared, create() returns the same instance each time. Also demonstrates passing extra constructor arguments at call time.

```php
$dice = $dice->addRule('A', ['shared' => true]);

$a1 = $dice->create('A');
$a2 = $dice->create('A');
var_dump($a1 === $a2); // true

// Constructor arguments can be passed at call time
$obj = $dice->create('CheckConstructorArgs', ['extraArg']);
```

--------------------------------

### Error handling for interface with create()

Source: https://github.com/level-2/dice

Attempting to create an interface throws an InvalidArgumentException with the message 'Cannot instantiate interface'. The try/catch block catches and prints that message.

```php
$dice = $dice->addRule('MyInterface', []);

try {
    $dice->create('MyInterface');
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // "Cannot instantiate interface"
}
```

--------------------------------

### Create a new Dice container with no configuration

Source: https://github.com/level-2/dice

Instantiates the container with no arguments, requiring no configuration. Objects are constructed by reflection-based auto-wiring.

```php
$dice = new \Dice\Dice;
```

--------------------------------

### create($name, array $args = [], array $share = [])

Source: https://github.com/level-2/dice

Thin delegation to the wrapped Dice container's create method. Constructs an instance with optional extra arguments and shared instances.

```APIDOC
## create($name, array $args = [], array $share = [])

### Description
Thin delegation to `$this->dice->create($name, $args, $share)`.

### Method
create

### Parameters
- **$name** (mixed) - Required - Class name or named instance.
- **$args** (array) - Optional - Extra constructor arguments. Default: `[]`.
- **$share** (array) - Optional - Shared instances. Default: `[]`.

### Returns
object - the constructed instance

### Usage
```php
$obj = $validator->create('PDO');
```
```

--------------------------------

### create(string $name, array $args = [], array $share = [])

Source: https://github.com/level-2/dice

Constructs or returns an existing shared object for the given class name or named instance. Supports auto-wiring, shared instances, extra constructor arguments, and shared instances for injection.

```APIDOC
## `create`

### Description
Constructs (or returns an existing shared) object for `$name`. Shares are instances available for injection by type higher up the object graph; they are intended for internal use but are legal public arguments.

### Method
`create`

### Signature
```php
public function create(string $name, array $args = [], array $share = [])
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$name` | `string` | yes | — | Class name or named instance to create. |
| `$args` | `array` | no | `[]` | Additional positional constructor arguments. |
| `$share` | `array` | no | `[]` | Shared instances (from `shareInstances` higher up the object graph). |

### Returns
`object` — a fully constructed object.

### Throws / Rejects
- `\ErrorException`/fatal-notice — when `$name` does not resolve to an existing class (reflection cannot load it).
- `\InvalidArgumentException('Cannot instantiate interface')` — when `$name` (or its `instanceOf`) resolves to an interface.

### Request Example
```php
class A { public $b; public function __construct(B $b) { $this->b = $b; } }
class B {}

$dice = new \Dice\Dice;
$a = $dice->create('A');
var_dump($a->b instanceof B); // true
```

### Request Example (shared instance and extra args)
```php
$dice = $dice->addRule('A', ['shared' => true]);

$a1 = $dice->create('A');
$a2 = $dice->create('A');
var_dump($a1 === $a2); // true

// Constructor arguments can be passed at call time
$obj = $dice->create('CheckConstructorArgs', ['extraArg']);
```

### Request Example (error handling - interface)
```php
$dice = $dice->addRule('MyInterface', []);

try {
    $dice->create('MyInterface');
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // "Cannot instantiate interface"
}
```
```

--------------------------------

### Add a shared rule for PDO and verify shared instances

Source: https://github.com/level-2/dice

Uses addRule() to mark the 'PDO' class as shared, then creates two instances and confirms they are identical. addRule() returns a new container; the original is unchanged.

```php
$dice = $dice->addRule('PDO', ['shared' => true]);

$db1 = $dice->create('PDO');
$db2 = $dice->create('PDO');
var_dump($db1 === $db2); // true (shared)
```

--------------------------------

### create() method signature

Source: https://github.com/level-2/dice

Signature of the Dice create() method. Constructs or returns a shared object for the given name, with optional extra constructor arguments and shared instances.

```php
public function create(string $name, array $args = [], array $share = [])
```

--------------------------------

### Constructor: __construct(\Dice\Dice $dice)

Source: https://github.com/level-2/dice

Wraps a Dice instance. All create() calls are delegated to that instance, and validated addRule() calls are applied to it.

```APIDOC
## Constructor: __construct(\Dice\Dice $dice)

### Description
Wraps a `Dice` instance. All `create()` calls are delegated to that instance, and validated `addRule()` calls are applied to it.

### Method
Constructor

### Parameters
- **$dice** (\Dice\Dice) - Required - The container this validator configures and queries.

### Usage
```php
$dice = new \Dice\Dice;
$validator = new \Dice\Extra\RuleValidator($dice);
```
```

--------------------------------

### getRule

Source: https://github.com/level-2/dice

Returns the effective rule that `create()` will use for a given name, or an empty array when no rule matches. The rule lookup follows a specific order: exact match, parent class match, then default rule.

```APIDOC
## `getRule`

### Description
Returns the effective rule that `create()` will use for `$name`, or `[]` when no rule matches. Rule lookup order: exact rule, parent class rule, then default rule `'*'`.

### Method
`getRule`

### Parameters
- `$name` (string) - Required - Class name or named instance to look up.

### Returns
`array` — the merged rule for `$name` (may be empty).

### Request Example
```php
$dice = $dice->addRule('A', ['shared' => true]);

$rule = $dice->getRule('A');   // ['shared' => true]
$none = $dice->getRule('B');   // []
```
```

--------------------------------

### Constructor usage: wrap a Dice instance

Source: https://github.com/level-2/dice

Creates a Dice container and wraps it with RuleValidator. All create() calls are delegated to the wrapped instance, and validated addRule() calls are applied to it.

```php
$dice = new \Dice\Dice;
$validator = new \Dice\Extra\RuleValidator($dice);
```

--------------------------------

### addRules usage with JSON-like array using constants and superglobals

Source: https://github.com/level-2/dice

Demonstrates using Dice::GLOBAL and Dice::CONSTANT to reference superglobals and PHP constants in rules.

```php
$dice = $dice->addRules([
    'Router' => ['constructParams' => [[\Dice\Dice::GLOBAL => '_SERVER']]],
    'PDO' => [
        'shared' => true,
        'constructParams' => ['mysql:dbname=testdb;host=127.0.0.1', 'user', 'pass'],
        'call' => [
            ['setAttribute', [[\Dice\Dice::CONSTANT => 'PDO::ATTR_ERRMODE'], [\Dice\Dice::CONSTANT => 'PDO::ERRMODE_EXCEPTION']]],
        ],
    ],
]);
```

--------------------------------

### convert($xml, $outputJson)

Source: https://github.com/level-2/dice

Loads rules from XML and writes them as pretty-printed JSON to the specified output file. This is the recommended migration path over the deprecated loader.

```APIDOC
## convert($xml, $outputJson)

### Description
Loads rules from `$xml` (using the default, warning-emitting `load()`) and writes them as pretty-printed JSON to `$outputJson`. This is the migration path recommended over the deprecated loader.

### Method
`convert`

### Parameters
- **$xml** (string / \SimpleXmlElement) - Required - XML source (file path or element).
- **$outputJson** (string) - Required - Output filename/path for the JSON rules.

### Returns
`void` (writes a file). The JSON can subsequently be loaded with `$dice->addRules(json_decode(file_get_contents($outputJson), true))`.

### Request Example
```php
$loader = new \Dice\Loader\Xml;
$loader->convert('old_rules.xml', 'rules.json');

$dice = new \Dice\Dice;
$dice = $dice->addRules(json_decode(file_get_contents('rules.json'), true));
```
```

--------------------------------

### addRules usage with array of rules

Source: https://github.com/level-2/dice

Shows how to pass an associative array of rules to addRules, setting shared and constructParams.

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

--------------------------------

### load($xml, $dice = null, $displayWarning = true)

Source: https://github.com/level-2/dice

Parses an XML rules document and registers all rules on a Dice container. Returns the parsed rules array and applies them via addRule() on each iteration.

```APIDOC
## load($xml, $dice = null, $displayWarning = true)

### Description
Parses the XML source and registers all rules on the given container (or a fresh one if `$dice` is `null`). Returns the parsed rules array and applies them via `$dice->addRule()` on each iteration (so rules in the same document are visible to later rules through `getRule()`).

### Method
`load`

### Parameters
- **$xml** (string / \SimpleXmlElement) - Required - XML file path or parsed element.
- **$dice** (\Dice\Dice) - Optional - Container to configure; a new one is created when `null`. Default: `null`.
- **$displayWarning** (bool) - Optional - Whether to emit the deprecation warning. Default: `true`.

### Returns
`array` — the map of loaded rules (`[name => rule]`) for v1 and v2 alike.

### Side Effects
Emits `trigger_error(..., E_USER_WARNING)` with a deprecation message whenever `$displayWarning` is true.

### Request Example
```php
$loader = new \Dice\Loader\Xml;
$dice = new \Dice\Dice;

$rules = $loader->load('path/to/rules.xml', $dice, false);

$obj = $dice->create('PDO');
```

### Request Example (suppressing deprecation warning)
```php
$loader = new \Dice\Loader\Xml;
// Third argument false suppresses the E_USER_WARNING
$rules = $loader->load('rules.xml', null, false);
```
```

--------------------------------

### Dice\Extra\RuleValidator::create

Source: https://github.com/level-2/dice

Creates an instance by delegating to Dice::create after validation.

```APIDOC
## Dice\Extra\RuleValidator::create

### Description
Creates an instance by delegating to Dice::create after validation.

### Method
create

### Signature
create(mixed $name, array $args = [], array $share = [])

### Parameters
- **$name** (mixed) - Required - The class name or alias.
- **$args** (array) - Optional - Constructor arguments.
- **$share** (array) - Optional - Instances to share.
```

--------------------------------

### Add a named instance rule inheriting shared from class A

Source: https://github.com/level-2/dice

Adds a rule for class 'A' with 'shared' => true, then adds a named instance '$MyA' that inherits the shared rule via 'instanceOf' => 'A'. Creating two instances of '$MyA' returns the same object.

```php
$dice = $dice->addRule('A', ['shared' => true]);
// Named instances inherit the rules of the class in 'instanceOf'
$dice = $dice->addRule('$MyA', ['instanceOf' => 'A', 'constructParams' => ['x']]);

$one = $dice->create('$MyA');
$two = $dice->create('$MyA');
var_dump($one === $two); // true — the 'shared' rule from 'A' was inherited
```

--------------------------------

### Converting XML rules to JSON with Dice\Loader\Xml::convert

Source: https://github.com/level-2/dice

Loads rules from an XML file and writes them as pretty-printed JSON to the specified output file. The resulting JSON can be loaded with $dice->addRules(json_decode(file_get_contents($outputJson), true)).

```php
$loader = new \Dice\Loader\Xml;
$loader->convert('old_rules.xml', 'rules.json');

$dice = new \Dice\Dice;
$dice = $dice->addRules(json_decode(file_get_contents('rules.json'), true));
```

--------------------------------

### Dice\Dice::create

Source: https://github.com/level-2/dice

Creates an instance of the given class using the container's rules and parameters.

```APIDOC
## Dice\Dice::create

### Description
Creates an instance of the given class using the container's rules and parameters.

### Method
create

### Signature
create(string $name, array $args = [], array $share = []): object

### Parameters
- **$name** (string) - Required - The class name or alias to create.
- **$args** (array) - Optional - Constructor arguments.
- **$share** (array) - Optional - Instances to share.

### Return Value
- **object** - The created instance.
```

--------------------------------

### Dice\Loader\Xml::load

Source: https://github.com/level-2/dice

Loads rules from XML and applies them to the container.

```APIDOC
## Dice\Loader\Xml::load

### Description
Loads rules from XML and applies them to the container.

### Method
load

### Signature
load(mixed $xml, ?\Dice\Dice $dice = null, bool $validate = false)

### Parameters
- **$xml** (mixed) - Required - XML string or file path.
- **$dice** (?\Dice\Dice) - Optional - Dice instance to apply rules to.
- **$validate** (bool) - Optional - Whether to validate the XML.
```

--------------------------------

### Dice\Loader\Xml::convert

Source: https://github.com/level-2/dice

Converts XML rules to JSON format.

```APIDOC
## Dice\Loader\Xml::convert

### Description
Converts XML rules to JSON format.

### Method
convert

### Signature
convert(mixed $xml, string $output)

### Parameters
- **$xml** (mixed) - Required - XML string or file path.
- **$output** (string) - Required - Output file path for JSON.
```

--------------------------------

### Dice\Extra\RuleValidator::__construct

Source: https://github.com/level-2/dice

Constructs a RuleValidator with a Dice instance.

```APIDOC
## Dice\Extra\RuleValidator::__construct

### Description
Constructs a RuleValidator with a Dice instance.

### Method
__construct

### Signature
__construct(\Dice\Dice $dice)

### Parameters
- **$dice** (\Dice\Dice) - Required - The Dice container instance.
```

--------------------------------

### addRule error handling: invalid boolean and unknown key

Source: https://github.com/level-2/dice

Shows exceptions thrown by addRule for invalid rule options. The first try block triggers 'Rule option shared must be true or false' for a non-boolean 'shared' value; the second triggers 'Invalid rule option: typoOption' for an unknown key.

```php
try {
    $validator->addRule('A', ['shared' => 'yes']); // not a boolean
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // "Rule option shared must be true or false"
}

try {
    $validator->addRule('B', ['typoOption' => 1]);
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // "Invalid rule option: typoOption"
}
```

--------------------------------

### Dice\Dice::getRule

Source: https://github.com/level-2/dice

Retrieves a rule from the container by name.

```APIDOC
## Dice\Dice::getRule

### Description
Retrieves a rule from the container by name.

### Method
getRule

### Signature
getRule(string $name): array

### Parameters
- **$name** (string) - Required - The rule name.

### Return Value
- **array** - The rule configuration array.
```

--------------------------------

### getRule method signature

Source: https://github.com/level-2/dice

Declares the getRule method that returns the effective rule for a class name or named instance.

```php
public function getRule(string $name): array
```

--------------------------------

### Basic usage of Dice\Loader\Xml::load

Source: https://github.com/level-2/dice

Loads rules from an XML file into a Dice container. The third argument false suppresses the deprecation warning. Returns the parsed rules array and applies them via $dice->addRule().

```php
$loader = new \Dice\Loader\Xml;
$dice = new \Dice\Dice;

$rules = $loader->load('path/to/rules.xml', $dice, false);

$obj = $dice->create('PDO');
```

--------------------------------

### addRules method signature

Source: https://github.com/level-2/dice

Declares the addRules method that accepts an array or JSON file path and returns a new Dice instance.

```php
public function addRules($rules): self
```

--------------------------------

### addRule

Source: https://github.com/level-2/dice

Adds a rule for a class, named instance, or default rule. Returns a new container with the rule applied; the original instance is unchanged.

```APIDOC
## addRule

### Description
Adds a rule (associative array of options) for class `$name`. Returns a **new** container; the receiving instance is unchanged.

### Method
`addRule`

### Signature
```php
public function addRule(string $name, array $rule): self
```

### Parameters
- `$name` (string) - Required - Class name, named instance (leading `$`), or `'*'` for the default rule.
- `$rule` (array) - Required - Associative array of rule options.

### Returns
A new `Dice` instance with the rule applied.

### Throws
None directly; however rule content may cause `\InvalidArgumentException` at `create()` time.

### Request Example
```php
$dice = $dice->addRule('PDO', ['shared' => true]);

$db1 = $dice->create('PDO');
$db2 = $dice->create('PDO');
var_dump($db1 === $db2); // true (shared)
```

### Request Example (Named instance with inherited rule)
```php
$dice = $dice->addRule('A', ['shared' => true]);
// Named instances inherit the rules of the class in 'instanceOf'
$dice = $dice->addRule('$MyA', ['instanceOf' => 'A', 'constructParams' => ['x']]);

$one = $dice->create('$MyA');
$two = $dice->create('$MyA');
var_dump($one === $two); // true — the 'shared' rule from 'A' was inherited
```
```

--------------------------------

### Suppressing deprecation warning while loading

Source: https://github.com/level-2/dice

Loads rules from an XML file without emitting the E_USER_WARNING deprecation warning by passing false as the third argument to load().

```php
$loader = new \Dice\Loader\Xml;
// Third argument false suppresses the E_USER_WARNING
$rules = $loader->load('rules.xml', null, false);
```

--------------------------------

### addRules

Source: https://github.com/level-2/dice

Adds many rules in a single [name => rule] array, useful when loading from a JSON file. Returns a new container with all rules applied.

```APIDOC
## `addRules`

### Description
Adds many rules in a single `[name => rule]` array, useful when loading from a JSON file. `$rules` may be an associative array of `name => rule`, or a string path to a JSON file whose contents are decoded to `true` and iterated. Returns a new container.

### Method
`addRules`

### Parameters
- `$rules` (array/string) - Required - Associative `[name => rule]` array, or a string filename containing JSON rules.

### Returns
A new `Dice` instance with all rules applied.

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

```php
$dice = $dice->addRules([
    'Router' => ['constructParams' => [[\Dice\Dice::GLOBAL => '_SERVER']]],
    'PDO' => [
        'shared' => true,
        'constructParams' => ['mysql:dbname=testdb;host=127.0.0.1', 'user', 'pass'],
        'call' => [
            ['setAttribute', [[\Dice\Dice::CONSTANT => 'PDO::ATTR_ERRMODE'], [\Dice\Dice::CONSTANT => 'PDO::ERRMODE_EXCEPTION']]],
        ],
    ],
]);
```
```

--------------------------------

### Internal validation helpers

Source: https://github.com/level-2/dice

Public validation sub-steps invoked internally by addRule(); can also be called directly.

```APIDOC
## checkBoolean($rule, $key)

### Description
If `$rule[$key]` is set and is not a boolean, throws `\InvalidArgumentException`.

### Method
checkBoolean

### Parameters
- **$rule** (array) - Required - The rule array.
- **$key** (string) - Required - The key to check.

### Throws
- \InvalidArgumentException - if the value is not a boolean

---

## checkNumericArray($rule, $key)

### Description
If `$rule[$key]` is set and contains any string array key, throws `\InvalidArgumentException` ("must be a sequential array").

### Method
checkNumericArray

### Parameters
- **$rule** (array) - Required - The rule array.
- **$key** (string) - Required - The key to check.

### Throws
- \InvalidArgumentException - if the array is associative

---

## checkAssocArray($rule, $key)

### Description
If `$rule[$key]` is set and contains **no** string array key (i.e. it is not associative), throws `\InvalidArgumentException`. Note: defined but **not** called by `addRule()`; no rule option is currently validated by it.

### Method
checkAssocArray

### Parameters
- **$rule** (array) - Required - The rule array.
- **$key** (string) - Required - The key to check.

### Throws
- \InvalidArgumentException - if the array is not associative

---

## checkValidKeys($rule)

### Description
Iterates the rule and throws for any key outside the valid-key list.

### Method
checkValidKeys

### Parameters
- **$rule** (array) - Required - The rule array.

### Throws
- \InvalidArgumentException - if an unknown key is present
```

--------------------------------

### Dice\Extra\RuleValidator::addRule

Source: https://github.com/level-2/dice

Validates and adds a rule to the container by delegating to Dice::addRule.

```APIDOC
## Dice\Extra\RuleValidator::addRule

### Description
Validates and adds a rule to the container by delegating to Dice::addRule.

### Method
addRule

### Signature
addRule(mixed $name, array $rule)

### Parameters
- **$name** (mixed) - Required - The rule name.
- **$rule** (array) - Required - The rule configuration array.
```

--------------------------------

### Dice\Dice::addRules

Source: https://github.com/level-2/dice

Adds multiple rules to the container. Returns a new Dice instance with all rules applied.

```APIDOC
## Dice\Dice::addRules

### Description
Adds multiple rules to the container. Returns a new Dice instance with all rules applied.

### Method
addRules

### Signature
addRules(mixed $rules): self

### Parameters
- **$rules** (mixed) - Required - An array of rules or a single rule.

### Return Value
- **self** - A new Dice instance with the rules added.
```

--------------------------------

### Dice\Dice::addRule

Source: https://github.com/level-2/dice

Adds a rule to the container. Returns a new Dice instance with the rule applied, as Dice instances are immutable.

```APIDOC
## Dice\Dice::addRule

### Description
Adds a rule to the container. Returns a new Dice instance with the rule applied, as Dice instances are immutable.

### Method
addRule

### Signature
addRule(string $name, array $rule): self

### Parameters
- **$name** (string) - Required - The rule name.
- **$rule** (array) - Required - The rule configuration array.

### Return Value
- **self** - A new Dice instance with the rule added.
```

--------------------------------

### addRule($name, array $rule)

Source: https://github.com/level-2/dice

Validates the rule array and applies it to the wrapped Dice container. Throws InvalidArgumentException on invalid rule options or types.

```APIDOC
## addRule($name, array $rule)

### Description
Validates `$rule` then applies it via `$this->dice->addRule($name, $rule)`. Validation performed, in order: checkValidKeys, checkBoolean for 'inherit' and 'shared', checkNumericArray for 'constructParams', 'shareInstances', and 'call'.

### Method
addRule

### Parameters
- **$name** (mixed) - Required - Class name, named instance, or `'*'`.
- **$rule** (array) - Required - Rule option array to validate and apply.

### Returns
void

### Throws
- \InvalidArgumentException('Invalid rule option: ' . $name) - unknown rule key
- \InvalidArgumentException('Rule option ' . $key . ' must be true or false') - inherit/shared not boolean
- \InvalidArgumentException('Rule option ' . $key . ' must be a seqential array not an associative array') - constructParams/shareInstances/call given as associative array

### Usage — basic
```php
$dice = new \Dice\Dice;
$validator = new \Dice\Extra\RuleValidator($dice);

$validator->addRule('PDO', ['shared' => true, 'constructParams' => ['dsn', 'user', 'pass']]);
```

### Usage — error handling
```php
try {
    $validator->addRule('A', ['shared' => 'yes']); // not a boolean
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // "Rule option shared must be true or false"
}

try {
    $validator->addRule('B', ['typoOption' => 1]);
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // "Invalid rule option: typoOption"
}
```
```
Tokens:
Raw