Factories

{note:title=draft}Many of the ideas and possibilities below were synthesized from discussions with the community, Andi, Darby, and Stas. However, much of the typing is mine, so flaws, typos, etc. can be credited to me :){note}

h1. Motivation: Why use factory patterns?

* Simplicity: simplify use of a plugin by encapsulating construction and management details exposed in the plugin API.
* Automation: auto-find/load the plugin source file, and auto-instantiate.
* Exceptions: throw exceptions in the factory on failure to load or instantiate the plugin.
* Bookkeeping: if we need to enforce singleton, or centrally manage instances, a factory provides a single point at which to collect processes associated with recording information about (and using) created instances.

h1. ZF Goals Relating to Factories

# Set the Zend Framework standard and best practice for coding factories.
# Support code analysis tools (e.g. parsing code to determine which methods are called where and by which classes, etc.)
# Support direct instantiation of plugins via {{new classname()}}, when a factory pattern is not needed or desired by the developer
# Support code completion by IDEs while developers are writing code, to help avoid spelling mistakes and reduce effort required to find and use classes, methods, and configuration options
# Switch: reduce the code required for mapping input choices to plugins (see "Convenience Factories" below).
{tip}Directly instantiating classes wherever possible, practical, and reasonable improves the benefits of using tools like IDEs.{tip}

Currently, the ZF has preferred using strings and mapping the strings to concrete classes within the factory -e.g. {{$adapter = new Zend_Db('PDO_MYSQL', $optionsArray);}}

h1. ZF Proposed Coding Standard Addition

No one proposed a solution to the dilemma posed by using constants in conjunction with developer created subclasses. So, in this case, a Zend Framework's key objective takes precedence: *consistency*

Thus, we expect to continue using strings as parameters to factory methods, like Zend_Db::factory($adapterString). The adapter strings should contain all uppercase letters. However, the factory method should ignore the case of the strings. The strings should follow a simple convention of joining compound words (if needed), using underscore characters ('_').

If the strings correlate to classes, then the strings should be unique enough to enable identifying and constructing the class name, by making the rightmost "word" in the string correspond directly to the class name of the instance object resulting from the factory method. Factory methods should follow a convention of checking a well-known location for user-supplied adapter/plugin classes, if the supplied string does not match a class included with the Zend Framework.

Factories ought to know by convention where to find the adapters, including a userland "plugin" directory, where developers can drop in their own, custom adapters.

h1. Types of Factories

h2. Convenience Factories

If the factory method is more of a convenience method that simplifies the process of constructing and/or initializing the plugin, then the factory can simply return an instance of the plugin.

If the factory method only encapsulates a "switch" contruct, then the factory can simply return an instance of the plugin.

{code:title=Factory Switch Construct}
switch($pluginType)
{
case PLUGIN_A: return new pluginA(); break;
case PLUGIN_B: return new pluginB(); break;
case PLUGIN_C: return new pluginC(); break;
default: throw new Zend_Exception('Unknown plugin type: '.$pluginType);
}
{code}

If userland code dynamically chooses $pluginType based on input, then there must still be some sort of mapping between input values and values for $pluginType, so embedding the {{switch()}} in the factory does not, by itself, result in significantly simpler code, and might actually result in duplication of the exception/error checking.

h2. Composition Factories

These factories provide additional methods beyond those of convenience factories, and return an instance of the factory, instead of an instance of the plugin, although an instance of the plugin remains a private member of the object returned by the factory. This form of run-time subclassing has been named dependency injection by

A convenience factory might be used to create the plugin instance stored in the object returned by the composition factory.

Composition factories are equivalent to creating a common superclass from which plugins can inherit, but lack the "switch construct" and bookkeeping. Additionally, multiple or mixin style inheritance are needed if the plugins are not all related by a common superclass. {tip}For simpler cases, using single inheritance with a common superclass often yields simpler code than using a composition factory.{tip}

We prefer supporting code completion, when practical.

Simplicity is our mantra, so the default preference of the Zend Framework should take the form of:
$instance = Zend_Class_Subclass($config_array); # direct

instead of:

$instance = Zend_Class_Factory('Subclass', $config_array); # needed for dependency injection

h1. Syntactical Ways to Achieve Factory Patterns

{code:title=Without Factory}
require 'PluginName.php';
$pluginInstance = new Zend_PluginName();
{code}

h2. Factory Methods Using Options Array

{code:title=Using Factory Methods}
$pluginInstance = Factory::getInstance('Plugin_Name', $optionsArray); #1

$pluginInstance = Factory::getInstance(new Plugin($optionsArray)); #2

$pluginInstance = Factory::getInstance($optionsArray); #3

# We also need an algorithm for #1 and #3 to map the input data onto a set of plugins.
{code}

h2. Factory Methods Using func_get_args()

Instead of {code}
$options = array();
if ($flag1) $options['param1'] = 'something';
elseif ($flag2 || $flag3 && !$flag4) $options['param2'] = 'foobar';
{code}

using {{func_get_args()}} allows us to do:
{code}
$foo = new PluginClass(1,2);
$bar = FactoryClass::factory("PluginClass", 3,4);
{code}

{code:title=How to Use funct_get_args() in Factory}<?php
echo '$foo = new PluginClass(1,2);'."\n";
$foo = new PluginClass(1,2);
echo "\n*************\n";
echo '$foo = new PluginSubClass(1,2,3);'."\n";
$foo = new PluginSubClass(1,2,3);
echo "\n*************\n";
echo '$bar = FactoryClass::factory("PluginClass", 3,4);'."\n";
$bar = FactoryClass::factory("PluginClass", 3,4);
echo "\n*************\n";
echo '$bar = FactoryClass::factory("PluginSubClass", 3,4,5);'."\n";
$bar = FactoryClass::factory("PluginSubClass", 3,4,5);

abstract class FactoryClass {
/**
* Create an object
* @param mixed args ...
*/
function __construct() {
$args = func_get_args();
if(count($args)) {
// we've got a call with arguments
call_user_func_array(array($this, "_init"), $args);
}
}

static public function factory($name) {
$plugin = new $name();
$args = func_get_args();
array_shift($args);
// Factories often interact with plugins that do not inherit from the FactoryClass.
// Thus, _init() must be a public function.
call_user_func_array(array($plugin,"_init"), $args);
}
}


class PluginClass {
/**
* Create an object
* @param mixed args ...
*/
function __construct() {
$args = func_get_args();
if(count($args)) {
// we've got a call with arguments
call_user_func_array(array($this, "_init"), $args);
}
}

/**
* Initializer
*
* @param int $arg1 parameter 1
* @param int $arg2 parameter 2
* @param string $arg3 parameter 3
*/
public function _init($arg1, $arg2) {
// do something with $arg1, $arg2
echo "arg1=$arg1, arg2=$arg2";
}
}

class PluginSubClass extends PluginClass{
/**
* Initializer
*
* @param int $arg1 parameter 1
* @param int $arg2 parameter 2
* @param string $arg3 parameter 3
*/
public function _init($arg1, $arg2, $arg3) {
// do something with $arg1, $arg2, $arg3
echo "arg1=$arg1, arg2=$arg2, arg3=$arg3";
}
}
?>

Results:

$foo = new PluginClass(1,2);
arg1=1, arg2=2
*************
$foo = new PluginSubClass(1,2,3);
arg1=1, arg2=2, arg3=3
*************
$bar = FactoryClass::factory("PluginClass", 3,4);
arg1=3, arg2=4
*************
$bar = FactoryClass::factory("PluginSubClass", 3,4,5);
arg1=3, arg2=4, arg3=5
{code}

h2. Ugly, but Works

h3. Games with Strings
{code:title=Ugly, but works}
$pluginName = "SomePlugin";
Zend::loadClass($pluginName); # not needed if using autoload, but best practices preclude autoload here
$pluginInstance = new "Factory$pluginName"($optionsArray);
{code}

h3. Eval

Some disadvantages of {{eval}}:
# Performance
# Eval cannot benefit from bytecode caches and optimizations
# Eval is very hard to debug

{code}<?php

class Factory
{
static public function createInstance($className)
{
/**
* @todo Class name validation must go here
*/

/**
* @todo Class loading logic could go here
*/

$args = func_get_args();
array_shift($args);

if ($args === null) {
return new $className();
}

$argsCount = count($args);
$argsString = '';
$comma = false;

for ($i = 0; $i < $argsCount; $i++) {
$argsString .= ($comma ? ', ' : '') . "\$args[$i]";
$comma = true;
}

return eval("return new $className($argsString);");
}
}

class ArgsNo
{
public function __construct()
{}
}

class ArgsYes
{
public function __construct($int, $bool, $string, $array, stdClass $obj)
{}
}

class ArgsOptional
{
public function __construct($first = 1, $second = 2)
{}
}

$argsNoNew = new ArgsNo();
$argsNoFactory = Factory::createInstance('ArgsNo');

$obj = new stdClass();
$argsYesNew = new ArgsYes(1, true, 'bar', array(4, 5, 6), $obj);
$argsYesFactory = Factory::createInstance('ArgsYes', 1, true, 'bar', array(4, 5, 6), $obj);

$argsOptionalNew = new ArgsOptional();
$argsOptionalFactory = Factory::createInstance('ArgsOptional');
{code}

Sometimes we have Zend_Class_Subclass1 and Zend_Class_Subclass2, and the code performing construction of both classes follow similar logic. Factories factor construction logic into the factory class. Inheritance also can help factor such construction logic into a common superclass, if all plugins can logically share a common superclass.

The facade pattern is not normally sufficient to justify the existence of a factory pattern.

Choosing between a factory and directly instantiating instances depends on many factors:
* Does the factory use logic to process inputs (e.g. settings in the registry, data provided to the constructor)?
*
* add more here


Factories can exist as standalone classes, or as static methods inside the class for which they are providing instances.

Factories can simply duplicate what could be accomplished by __construct(), or they might provide a facade to reduce the complexity of creating intances. Also, factories allow factoring shared logic out of __construct()'s, thus keeping the code of the instance &quot;pristine&quot; and clean of distracting code that might not directly relate to the focus of that class.

Choosing between a callback and a plugin:
*
*
*