Table Of Content

All PHP classes which are managed by the Component Manager are called Components. Because nearly all classes are managed by the Component Manager, almost all classes in FLOW3 - including third-party extensions - are used as components.

In contrast to plain, standalone classes which are probably only used in a project or two, the development of reusable components requires the author to pay more attention on proper documentation, testing and encapsulation. If a component is well designed, it doesn't expose the internal functions and properties of the class but only allows access through a well-thought API. By following this blackbox-principle, it is much easier to modify the internal behaviour of a component at a later time, because it is always known which functions can be used from outside.

In simple, self-contained applications, creating objects is as simple as using the new operator. However, as the program gets more complex, a developer is confronted with solving dependencies to other objects, make classes configurable (maybe through a factory method) and finally assure a certain scope for the object (such as Singleton or Prototype). Howard Lewis Shipexplained this circumstances nicely in his blog (quite some time ago):

We as PHP developers don't have to care about garbage collection and we surely wouldn't like to be responsible for it either. However, building objects can be even more complex than destructing them. Therefore the FLOW3 framework manages the whole lifecycle of components for you. The Component Manager is a so called Lightweight Container taking care of object building and dependency resolution. We'll discover shortly why dependency injection makes such a difference to your application design.

The Component Manager provides a lean API for registering, configuring and retrieving instances of components. Some of the methods provided are exclusively used within the FLOW3 package or in unit tests and should possibly not be used elsewhere. By offering Dependency Injection, the Component Manager helps you to avoid creating rigid interdependencies between components. It allows for writing code which is hardly or even not at all aware of the framework it is working in.

Although Dependency Injection is what you should strive for, it might happen that you need to retrieve component instances directly. Instead of using PHP's new operator, you must ask the Component Manager for the instance of a component.

First, you need an instance of the Component Manager itself and as you have seen in the shortcut example before, one way of getting it is adding a new parameter to your class constructor method:

public function __construct(F3_FLOW3_Component_ManagerInterface $componentManager) {
}

To explicitly retrieve the instance of a component use the getComponent() method:

$myComponentInstance = $componentManager->getComponent('F3_MyPackage_MyClassName');

It is possible to pass arguments to the constructor of the component class just by adding them to the getComponent() call:

$myComponentInstance = $componentManager->getComponent('F3_MyPackage_MyClassName', 'first argument', 'second argument');

By default, the name of a component is identical to the PHP class which implements the component's functions. A class called F3_MyPackage_MyImplementation will be automatically available as a component with the exact same name. Every part of the system which asks for a component instance with a certain name will therefore - by default - get an instance of the class of that name. It is possible to replace the original implementation of a component by another one. In that case the class name of the new implementation will naturally differ from the component name which stays the same at all times.

If the component name is the same as the name of a PHP interface, it is often referred to as a component type. An interface called F3_MyPackage_MyInterface will be available as a component name as long as there exists at least one class implemententing that interface.

An important prerequisite for resuable code is already met by encouraging encapsulation through the components approach. However, the components are still aware of their environment as they need to actively collaborate with other components and the framework itself: An authentication component will need a logger for logging intrusion attempts and the code of a shop system hopefully consists of more than just one class. Whenever a component refers to another directly, it adds more complexity and removes flexibility by opening new interdependencies. It is very difficult or even impossible to reuse such hardwired classes.

By introducing Dependency Injection, these interdependencies are minimized by inverting the control over resolving the dependencies: Instead of asking for the instance of a component actively, the depending component just gets one injected by the Component Manager. This methodology is also referred to as the "Hollywood Principle": “Don't call us, we'll call you.”. It helps in the development of code with loose coupling and high cohesion – or in short: It makes you a better programmer.

In the context of the previous example it means that the authentication component announces that it needs a logger which implements a certain PHP interface (eg. the F3_Log_LoggerInterface). The component itself has no control over what kind of logger (simple file logger, sms-logger, ...) it finally gets and it doesn't have to care about it anyway as long as it matches the expected API. As soon as the authentication component is instantiated, the component manager will resolve these dependencies, prepare an instance of a logger and inject it to the authentication component.

Dependencies on other components can be declared in the components configuration (see section about configuring components) or they can be solved automatically (so called autowiring). Generally there are two modes of dependency injection supported by FLOW3: Constructor Injection and Setter Injection.

public class F3_Authentication_LDAPAuthentication {

   protected $logger;

   public function __construct(F3_Log_LoggerInterface $logger) {
      $this->logger = $logger;
   }

   public function authenticate($credentials) {
      $this->logger->log('tried to authenticate');
   }
}

$c->F3_Authentication_LDAPAuthentication->
constructorArguments[1]->reference = 'F3_Log_ASpecialLogger';

public class F3_Authentication_LDAPAuthentication {

   protected $someLogger;

   public function authenticate($credentials) {
      $this->logger->log('tried to authenticate');
   }

   public function setSomeLogger(F3_Log_LoggerInterface $someLogger) {
      $this->someLogger = $someLogger;
   }
}

<?php

$c->F3_Authentication_LDAPAuthentication->properties->someLogger->reference = 'F3_Log_LoggerInterface';

?>

public class F3_Authentication_LDAPAuthentication {

   protected $someLogger;

   public function authenticate($credentials) {
      $this->logger->log('tried to authenticate');
   }

   public function injectSomeLogger(F3_Log_LoggerInterface $someLogger) {
      $this->someLogger = $someLogger;
   }
}

All dependencies defined in a constructor are, by its nature, required. If a dependency can't be solved by autowiring or by configuration, FLOW3's object builder will throw an exception.

However, autowired setter-injected dependencies are, by default, optional. If a dependency can't be solved, it just won't be injected and it is the developer's responsability to test for the availability of the desired object. There is a way though to declare a setter-injected dependency as required without the need to configure the dependency in a Components.php file. FLOW3 uses the @required annotation for this purpose:

public class F3_Authentication_LDAPAuthentication {

   protected $someLogger;

   public function authenticate($credentials) {
      $this->logger->log('tried to authenticate');
   }

   /**
    * Injects a logger
    *
    * @param    F3_Log_LoggerInterface $someLogger A logger which is used for logging LDAP authentication events
    * @return   void
    * @author   Robert Lemke <robert@typo3.org>
    * @required
    */
   public function injectSomeLogger(F3_Log_LoggerInterface $someLogger) {
      $this->someLogger = $someLogger;
   }
}

Due to the @required annotation, the injection of a logger is now required. If the object builder can't autowire a logger for this injection method, it will now throw an exception.

The dependencies between components are only resolved during the instantiation process. Whenever a new instance of a component class needs to be created, the component configuration is checked for possible dependencies. If there is any, the required components are built and only if all dependencies could be resolved, the component class is finally instantiated and the dependency injection takes place.

As already mentioned, the configuration for each component is compiled from different sources. The Components.php file is the recommended format and is therefore used in most of the examples. However, the names of the configuration options and their possible values are identical to all configuration sources.

<?php
declare(ENCODING = 'utf-8');

/*                                                                        *
 * Component Configuration for the Authentication package                 *
 * (this package doesn't really exist, and even if so, the configuration  *
 * would probably be different)                                           *
 *                                                                        */

/**
 * @package Authentication
 * @version $Id: Components.php 123 2008-01-01 12:00:00Z robert $
 */

$c->F3_Authentication_LDAPAuthentication->constructorArguments[1]->reference = 'F3_Log_LoggerInterface';
$c->F3_Authentication_LDAPAuthentication->constructorArguments[2]->reference = 'F3_LDAP_LDAPServerInterface';
$c->F3_Authentication_LDAPAuthentication->constructorArguments[3] = 'cn=John Smith,ou=TYPO3 Development,o=TYPO3 Association,c=CH';

?>

/**
 * This is my great class.
 *
 * @scope prototype
 */
class F3_MyPackage_SomeClass {

}

One advantage of componentry is the ability to replace components by others without any bad impact on those parts depending on them. A prerequisite for replaceable components is that their classes implement a common interface which defines the public API of the original component. Other components which implement the same interface can then act as a true replacement for the original component without the need to change code anywhere in the system. If this requirement is met, the only necessary step to replace the original implementation with a substitute is to alter the component configuration and set the class name to the new implementation.

To illustrate this circumstance, consider the following classes:

class F3_MyPackage_Greeter {
   public function sayHelloTo($name) {
      echo('Hello ' . $name);
   }
}

During initialization above class will automatically be registered as the component F3_MyPackage_Greeter and is available to other components. In the code of another component you might find these lines:

   // Explicitly fetch an instance of the F3_MyPackage_Greeter component:
$greeter = $componentManager->getComponent('F3_MyPackage_Greeter');

   // Say hello to Heike:
$greeter->sayHelloTo('Heike');

Great, that looks all fine and dandy but what if we want to use the much better component F3_OtherPackage_GreeterWithCompliments? Well, you just configure the component F3_MyPackage_Greeter to use a different class:

   # Change the name of the class which represents the component "F3_MyPackage_Greeter":
$c->F3_MyPackage_Greeter->className = 'F3_OtherPackage_GreeterWithCompliments';

Now all components who ask for a traditional greeter will get the more polite version. However, there comes a sour note with the above example: We can't be sure that the GreeterWithCompliments class really provides the necessary sayHello() method. The solution is to let both implementations implement the same interface:

interface F3_MyPackage_GreeterInterface {
   public function sayHelloTo($name);
}

class F3_MyPackage_Greeter implements F3_MyPackage_GreeterInterface {
   public function sayHelloTo($name) {
      echo('Hello ' . $name);
   }
}

class F3_OtherPackage_GreeterWithCompliments implements F3_MyPackage_GreeterInterface{
   public function sayHelloTo($name) {
      echo('Hello ' . $name . '! You look so great!');
   }
}

Instead of referring to the original implementation directly we can now refer to the interface. In this case we call the component name a component type because it contains the name of a PHP interface.

   // Explicitly fetch an instance of any implementation of the F3_MyPackage_GreeterInterface component type:
$greeter = $componentManager->getComponent('F3_MyPackage_GreeterInterface');

   // Say hello to Heike:
$greeter->sayHelloTo('Heike');

Finally we have to set which implementation of the F3_MyPackage_GreeterInterface should be active:

$c->F3_MyPackage_GreeterInterface->className = 'F3_OtherPackage_GreeterWithCompliments';

Any interface found in the Classes/ directory will equally be registered as a component if at least one class within the same package was found that implements this interface. The first class found in the package which implements the interface is considered to be the default implementation and the component's className option is set accordingly. Of course it is still possible that the class name is defined explicitly in the package's Components.php file or any other configuration source. This is especially important if more than one implementing class exists.

As mentioned earlier, the Component Manager allows for injection of straight values or references (ie. dependencies) either by passing them as constructor arguments during instantiation of the component class or by calling a setter method which sets the wished property accordingly. The following sections demonstrate how to pass values and define dependencies to other components.

public class F3_Authentication_LDAPAuthentication {

   protected $logger;
   protected $LDAPServer;
   protected $distinguishedName = '';

   public function __construct(F3_Log_LoggerInterface $logger, F3_LDAP_LDAPServerInterface $LDAPServer, $distinguishedName) {
      $this->logger = $logger;
      $this->LDAPServer = $LDAPServer;
      $this->distinguishedName = $distinguishedName;
   }

   public function authenticate(F3_Authentication_CredentialsInterface $credentials) {
      $this->LDAPServer->doSomeMagic($this->distinguishedName);
      $this->logger->log('tried to authenticate');
   }
}

  # Inject two component references as the first two arguments:
$c->F3_Authentication_LDAPAuthentication->constructorArguments[1]->reference = 'F3_Log_LoggerInterface';
$c->F3_Authentication_LDAPAuthentication->constructorArguments[2]->reference = 'F3_LDAP_LDAPServerInterface';

  # Inject a straight value as the third argument:
$c->F3_Authentication_LDAPAuthentication->constructorArguments[3] = 'cn=John Smith,ou=TYPO3 Development,o=TYPO3 Association,c=CH';

public class F3_Authentication_LDAPAuthentication {

   protected $logger;
   protected $LDAPServer;
   protected $distinguishedName = '';

   public function authenticate(F3_Authentication_CredentialsInterface $credentials) {
      $this->LDAPServer->doSomeMagic($this->distinguishedName);
      $this->logger->log('tried to authenticate');
   }

   /**
    * @required
    */
   public function injectLogger(F3_Log_LoggerInterface $logger) {
      $this->logger = $logger;
   }

   /**
    * @required
    */
   public function injectLDAPServer(F3_LDAP_LDAPServerInterface $LDAPServer) {
      $this->LDAPServer = $LDAPServer;
   }

   public function setDistinguishedName($distinguishedName) {
      $this->distinguishedName = $distinguishedName;
   }
}

  # Inject two component references:
$c->F3_Authentication_LDAPAuthentication->properties->logger->reference = 'F3_Log_LoggerInterface';
$c->F3_Authentication_LDAPAuthentication->properties->LDAPServer->reference = 'F3_LDAP_LDAPServerInterface';

  # Inject a straight value as the third argument:
$c->F3_Authentication_LDAPAuthentication->properties->distinguishedName = 'cn=John Smith,ou=TYPO3 Development,o=TYPO3 Association,c=CH';

The objects created by the Component Manager all exist in a certain scope. By default, an instance of a component class is unique which makes sure that the exact same object is returned whenever the Component Manager is asked for a specific component. This default scope is called Singleton. Of course other scopes are supported as well:

A great feature of the Component Manager is that components don't have to implement their own mechanism for administrating their scope - it only has to be configured. The following example contains configurations for three components, all living in a different scope:

$c->F3_MyPackage_ASingletonClass->scope = F3_FLOW3_Component_Configuration::SCOPE_SINGLETON;
$c->F3_MyPackage_APrototypeClass->scope = F3_FLOW3_Component_Configuration::SCOPE_PROTOTYPE;
$c->F3_MyPackage_ASessionClass->scope = F3_FLOW3_Component_Configuration::SCOPE_SESSION;

In most cases a component class will live in the Singleton scope and at most requires a few dependencies passed to its constructor. However, there are times when it becomes necessary to pass dynamic values as constructor arguments, especially when the component represents an entity and its instances are not unique (Prototype scope). Consider the following classes:

class F3_Address_Adressbook {

   protected $addresses = array();

   public __construct(F3_iCal_iCalConnectorInterface $iCalConnector) {
      ...
   }

   public addAddress(F3_Address_Address $address) {
      $this->addresses[] = $address;
   }

}

class F3_Address_Address {

   public __construct($street, $zip, $town, $country) {
      ...
   }
}

This is admittedly not the fanciest implementation of an address book, but it should demonstrate two things:

The following code demonstrates how this address book can be used and constructor arguments are passed to the Address entity:

   # Fetch a unique instance of the addressbook:
$myAddressbook = $componentManager->getComponent('F3_Address_Addressbook');

   # Create two new addresses and add them to the addressbook:
$newAddress = $componentManager->getComponent('F3_Address_Address', 'Tryggevældevej', '2720', 'København', 'DK');
$myAddresbook->addAddress($newAddress);

$newAddress = $componentManager->getComponent('F3_Address_Address', 'An den Brodbänken', '21335', 'Lüneburg', 'DE');
$myAddresbook->addAddress($newAddress);

Injecting dependencies to a constructor function is a common task. Because FLOW3 can detect the type of dependencies a constructor needs, it automatically configures the component to assert that the necessary components are injected. This automation is called autowiring and is enabled by default for every component. To repeat our favourite example, imagine that your component class needs some kind of logger. All you need to do in order to get one is writing the following constructor:

public function __construct(F3_Log_LoggerInterface $logger) {
   $logger->log("Hooray");
}

The constructor of the above example will get an instance of the component of type F3_Log_LoggerInterface injected and can use it for further operations.

If, for some reason, you need to disable autowiring support, you can do so by setting an option in your component configuration:

$c->F3_MyPackage_MyComponent->autoWiringMode = FALSE;

The lifecycle of a component object goes through different stages. It boils down to the following order:

Your component might want to take some action after certain of the above steps. Whenever one of the following methods exists in the component class, it will be invoked after the related lifecycle step:

As you can see from the above list, there is only one special method which is provided by PHP's own means and that is the initialization method. Here's a simple example:

class F3_MyPackage_MyClass {

   protected $logger;

   public function __construct(F3_Log_LoggerInterface $logger) {
      $this->logger = $logger;
   }

   public function intializeComponent() {
      $this->logger->log('MyClass has been initialized.');
   }
}

The above example will just work out of the box without any further configuration. However, if you don't have control over the name of your initialization method (maybe, because you are integrating legacy code), you can configure the name of the method in the component configuration:

$c->F3_MyPackage_MyClass->lifecycleInitializationMethod = 'myInitialize';