Dependency injection means that you pass an "external" object into a "receiving" object. This allows the receiving" object use the external object functionality. The receiving object is said to be dependent on the external object; thus, the "external" object is the "dependency" object.
The Solar::dependency() method standardizes dependency injections for Solar. It uses the object given to it, or retrieves the dependency object from the Solar_Registry, or creates it using Solar::factory() as needed. (Technically, this make the Solar::dependency() method a combination of a "service locator" and a dependency-injection tool.)
In general, Solar::dependency() is used for flexibility; we don't necessarily know, in advance, if the dependency object itself is going to be passed in, or if it should be retrieved from the registry, or if it should be created on-the-fly. As such, the method has two parameters:
A "class hint" to say what kind of object the dependency should be (although not required to be), and
A "specification" that determines how the dependency object will be retrieved:
If an object, that object is itself the dependency object.
If a string, it's treated as a registry key, and the dependency object is retrieved using Solar::registry().
Otherwise, the "class hint" is used as the class name, and the dependency object is created using Solar::factory(). The specification is used as the second parameter (i.e., the $config parameter) for the factory method.
The following is an example of passing the object itself as the dependency:
<?php
$obj = Solar::factory('Solar_Example');
$example = Solar::dependency('Solar_Example', $obj);
?>The following retrieves a the dependency from the registry using the key 'example':
<?php
$example = Solar::dependency('Solar_Example', 'example');
?>Finally, the following creates a Solar_Example dependency object on the fly.
<?php
$config = array(...);
$example = Solar::dependency('Solar_Example', $config);
?>