Service locator with explicit method names instead of a generic *get()* post

The Way to the Component

I had visited the php usergroup in hamburg and Arne Blankerts made a presentation called the flip side of dependency injection.

Inspired by that talk, I wrote a component with the following key benefits in mind:

  • use a configuration format like the big guys (zend of symfony) are using
  • generate a class that has explicit method names like getFoo()
  • generate a class that comes with instance pooling
  • the generated code must be easy to debug and to understand, no magic inside

With that in mind, I created the Locator Generator. While writing the component, I figured out that there is no suitable code generator out there, so I wrote one on my own - but thats a different story ;-).

An Example

Actions speak louder than words, so here is an example.

return array(
    //...
    'instances' => array(
        array(
            'alias'         => 'UniqueFactorizedInstance',
            'class_name'    => '\Application\Factory\ExampleUniqueFactorizedInstanceFactory',
            'is_factory'    => true,
            'is_shared'     => false,
            'return_value'  => '\Application\Model\ExampleUniqueFactorizedInstance'
        )
    ),
    //...

What you see above is the full power of the configuration file You can decide:

  • the alias which will be used to create method like getUniqueFactorizedInstance()
  • the full qualified class name to find the instance
  • a flag to determine if the provided class name is a factory
  • a flag to determine if the instance should be shared (created only once)
  • return value to help the generator adding the correct @return statement to the generated method

What does the generator generates for you? A fine php class, but lets have a look to the code.

//...
    /**
    * @return \Application\Factory\ExampleUniqueFactorizedInstanceFactory
    */
    public function getExampleUniqueFactorizedInstance()
    {
        return $this->fetchFromFactoryInstancePool('\Application\Factory\ExampleUniqueFactorizedInstanceFactory')->create();
    }
//...

Furthermore, it generates a FactoryInterface and a InvalidArgumentException for you, if needed.

API

The API is available at www.bazzline.net, thanks to apigen and the api document builder.

Terms

Benefits

  • on way of calling the locator generator "php bin/generate_locator "
  • assembler, method builder and file exists strategy are configuration based runtime variables
  • highly configurable
    • each configuration file needs to be a simple php array
    • mandatory array keys are
      • assembler
      • file_exists_strategy
    • optional array key is
      • boostrap_file
    • rest of configuration is based on the given assembler
  • shipped with two assembler implementations
    • FromArrayAssembler
      • mandatory array keys
        • class_name
        • file_path
    • optional array keys
      • extends (can be empty)
      • implements (can be empty)
      • instances (can be empty)
        • alias
        • is_factory
        • is_shared
        • method_body_builder
      • method_prefix
      • namespace (can be empty)
      • uses (can be empty)
        • alias
    • FromPropelSchemaXmlAssembler
      • mandatory array keys
        • class_name
        • file_path
      • optional array keys
        • extends (can be empty)
        • implements (can be empty)
        • method_prefix
        • namespace (can be empty)
        • path_to_schema_xml
        • uses (can be empty)
    • implement the AssemblerInterface to write your own assembler
  • shipped with two file exists strategies
  • shipped with five method body builder implementations
    • FetchFromFactoryInstancePoolBuilder used internally by the generated locator
    • FetchFromSharedInstancePoolBuilder used internally by the generated locator
    • FetchFromSharedInstancePoolOrCreateByFactoryBuilder used internally by the generated locator
    • NewInstanceBuilder used internally by the generated locator
    • PropelQueryCreateBuilder as an example to use your own method body builder
    • ValidatedInstanceCreationBuilder as an additional example how to use the power of the method body builder support to generate own instance creation code
    • implement the MethodBodyBuilderInterface to write your own method body builder
  • uses separate component for php code generation

Categories: components, english

Tags: bazzline, composer, english, free_as_in_freedom, github, opensource, packagist, generator, locator