FF-Factories/readme.md

FF\Factories | Fast Forward Family

by Marco Stoll

• marco.stoll@rocketmail.com
• http://marcostoll.de
• https://github.com/marcostoll
• https://github.com/marcostoll/FF
• https://github.com/marcostoll/FF-Factories

---

What is the Fast Forward Family?

Fast Forward, in short FF, is a template for building web applications. The FF Family is a series of basic repositories on which FF depends on but may also be used independently if desired.

FF is not a framework in and of itself and therefore should not be called so. But you may orchestrate multiple FF components to build an web application skeleton that provides the most common tasks.

Introduction - What if FF\Factories?

FF\Factories provides an factory pattern implementation for generic object instantiation.

Installation

via Composer

@todo

manual Installation

@todo

The Factories

The AbstractFactory provides logic to introduce factory-style object instantiation. By configuring it with a designated class locator you may invoke its create() method with a class identifier and the necessary constructor arguments to get a fresh instance of this class.

The factory will instruct the its class locator to detect a suitable class definition and after that will invoke the class's constructor and return the object.

An example:

namespace MyProject\Views\Helpers;

use FF\Factories\AbstractFactory;
use FF\Factories\ClassLocators\NamespaceClassLocator;

/**
 * Definition of Helpers Factory
 */
class MyHelpersFactory extends AbstractFactory
{
    public function __construct()
    {
        // configure the factory with its own namespace
        // to search for Helper class
        parent::__construct(new NamespaceClassLocator(__NAMESPACE__));
    }
}

...

// Will get a MyViewHelper instance assumed the a MyProject\Views\Helpers\MyViewHelper class exists.
// In this example $arg1 and $arg2 will be passed to the MyViewHelper class's constructor in the given order.
$myHelper = $myHelpersFactory->create('MyViewHelper', $arg1, $arg2);

The AbstractSingletonFactory extends this behaviour by adding a singleton pattern to its implementation that will ensure that an instance of a class identified by its identifier will only be instantiated a single time.
So any additional call to its create() method will return the same instance as the first time.

Beware: Only the class identifier will be taken into account for identifying already instantiated objects. Varying any constructor arguments will not lead to generating new object instances.

The Class Locators

Class locators implement various strategies to derive full-qualified class names based on a shorter class identifier. Each class locator defines a different convention for specifying class identifiers and the logic to detect suitable class definitions based on this.

The Namespace Class Locator

This class locator can be configured with a list of base namespaces ro search for class definitions with a class identifier relative to one of its base namespaces. The base namespaces wil be search in the give order. So the locator will return the first match of an existing class.

An example:

use FF\Factories\ClassLocators\NamespaceClassLocator;

$myLocator = new NamespaceClassLocator('MyProject\Sub1', 'MyProject\Sub2');

// This will find MyProject\Sub1\MyClass or MyProject\Sub2\MyClass in this order.
// If none of the above exist, $class will be null.
$class = $myLocator->locateClass('MyClass');

// This will find MyProject\Sub1\Foo\MyClass or MyProject\Sub2\Foo\MyClass in this order.
// If none of the above exist, $class will be null.
$class = $myLocator->locateClass('Foo\MyClass');

The Base Namespace Class Locator

This class locator can be configured with a list of base namespaces and a common suffix ro search for class definitions with a class identifier relative to one of its base namespaces. The base namespaces wil be search in the give order. So the locator will return the first match of an existing class.

An example:

use FF\Factories\ClassLocators\BaseNamespaceClassLocator;

$commonSuffix = 'Some\Suffix';
$myLocator = new NamespaceClassLocator($commonSuffix, MyProject\Sub1', 'MyProject\Sub2');

// This will find MyProject\Sub1\Some\Suffix\MyClass or MyProject\Sub2\Some\Suffix\MyClass in this order.
// If none of the above exist, $class will be null.
$class = $myLocator->locateClass('MyClass');

// This will find MyProject\Sub1\Some\Suffix\Foo\MyClass or MyProject\Sub2\Some\Suffix\Foo\MyClass in this order.
// If none of the above exist, $class will be null.
$class = $myLocator->locateClass('Foo\MyClass');    

The Namespace Prefixed Class Locator

Sometimes you want to distribute class definitions of a certain kind (say Event classes) over various packages. To provide a factory capable of creating this events objects you may use the NamespacePrefixedClassLocator. This locator enforces you to place your various class definitions within a common class namespace prefix.

An example:

    use FF\Factories\ClassLocators\NamespacePrefixedClassLocator;
    
    // The first argumens ('Events') is the common class namespace prefix.
    // The following argumentgs are the base namespaces to inspect.
    $myLocator = new NamespaceClassLocator('Events', MyProject\Sub1', 'MyProject\Sub2');
    
    // This will find MyProject\Sub1\Events\MyEvent or MyProject\Sub2\Events\MyEven in this order.
    // If none of the above exist, $class will be null.
    $class = $myLocator->locateClass('MyEvent');
    
    // This will find MyProject\Sub1\Foo\Events\MyEvent or MyProject\Sub2\Foo\Events\MyEvent in this order.
    // If none of the above exist, $class will be null.
    $class = $myLocator->locateClass('Foo\MyEvent');

Road map

The extend of the Factories component is mainly driven by the needs of other FF components, so not concrete features are planned at this time. The component surely will grow as other FF components require additional logic that is not part of their domain.