twogood / pebble

Dependency Injection system for PHP

Pebble Dependency Injection for PHP - https://github.com/twogood/pebble


Simple Pebble usage
-------------------

1. require_once 'Pebble.php';

2. annotate properties with /** @Pebble(name) */, where name has a
corresponding @SharedPebble or @PebbleFactory

    /** @Pebble(name) */
    private $property;

3. classes that use @Pebble must either inherit from PebbleDash, or call
PebbleDash::dashObject($this) in their constructor (or similar)

    class Example1 extends PebbleDash 
    { 
    }
    
    class Example2 extends OtherClass
    { 
      public function __construct()
      {
        parent::__construct();
        PebbleDash::dashObject($this);
      }
    }


Simple PebbleCollector usage
-------------------------------------

1. Same as "Simple Pebble Usage" above 

2. require_once 'PebbleCollector.php';

3. annotate classes that will become shared objects (singletons) with 

    /** @SharedPebble(name) */
    class Foo {}

4. annotate classes that always return a new instance with 

    /** @PebbleFactory(name) */
    class Bar {}

5. call PebbleCollector::collectPebbles()



Annotations
-----------

o Annotations are enclosed in /** and */

o Valid class annotations are @SharedPebble and @PebbleFactory (requires PebbleCollector)

o If no pebble name is supplied within parenthesis after the annotation, the
class name is used

o Valid property annotation is @Pebble

o If no pebble name is supplied within parenthesis after the class annotation,
the property name is used

o Constructor arguments are not supported


Usage notes
-----------

o Pebble names are case-insensitive

o Pebble is viral; i.e. Pebble::dash will be called on all objects
that are set by dependency injection, i.e. have an @Pebble annotation.


Using PebbleCollection
----------------------

The PebbleCollection contains all registered pebbles. 

There is not (yet) support in Pebble for loading a PebbleCollection from a file.

The PebbleCollection::set method is used to explicitly pebbles to the
collection. The first parameter is the name of the pebble. The second parameter
is either an anonymous function (closure) that will be evaluated on injection,
or a value that will be injected as-is.


Pebble and class autoloading
----------------------------

When using Pebble with a project that uses PHP's Autoloading of Classes (for
example if you use Zend Framework), the @PebbleFactory and @SharedPebble
annotations are probably not useful. This is because the classes you want to
inject are not yet loaded!

In this case you use the setShared and/or setFactory methods of
PebbleCollection, as documented above.


Example for Zend Framework (1.x)
--------------------------------

In Bootstrap.php:

  class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
  {
    protected function _initServices()
    {
      $options = $this->getOptions();
      PebbleCollection::set('webServiceOptions', $options['webService']);
      PebbleCollection::once('webServiceClient', function () { return new Application_Model_WebServiceClient(); } );
      /* ... */
    }


In models/WebServiceClient.php:

  class Application_Model_WebServiceClient
  {
    /** @Pebble(webServiceOptions) */
    private $options;

    /* ... */
}


In models/MyController.php:

class MyController extends Zend_Controller_Action
{
  /** @Pebble */
  private $webServiceClient;

  public function init()
  {
    PebbleDash::dashObject($this);
  }
    
  /* ... */
}