Fabien Potencier

Sourceforge Community Choice Awards: symfony is a Finalist!

2009-06-22T21:40:00+02:00

Thanks its dedicated community, symfony has been chosen as a finalist for the 2009 Sourceforge Community Choice Awards in no less than three categories!

Best Project
Best Tool or Utility for Developers
Best Project for the Enterprise

Some other PHP projets are also finalists: phpMyAdmin, FLOW3, Joomla, TYPO3, and vtiger CRM.

If you like symfony, or if you just like PHP, or if you just want to be kind with us, please, consider voting for symfony: http://sourceforge.net/community/cca09/vote/?f=392.

Pimple, the small dependency injection container for PHP 5.3

2009-06-16T07:50:00+02:00

Some people emailed me about a blog post I wrote some time ago about a dependency injection container done in PHP 5.3. I have published on Github the small version of it (Twittee), but not the "working" version.

Today, I took the time to publish it on Github. Pimple is a small dependency injection container, with all the features you need for a usage in real projects.

Feel free to use it, fork it, and enhance it for your next PHP 5.3 project.

And don't forget to give PHP 5.3 a try as the PHP core team has just published the third release candidate, and they hope to release the final version by the end of June.

Tweeting from PHP

2009-06-14T22:33:00+02:00

Twitter is everywhere nowadays. Odds are eventually you will want to tweet from PHP. No need to use one of the numerous PHP Twitter libraries, as tweeting is as simple as using the PHP built-in file_get_contents() function:

function tweet($message, $username, $password)
{
  $context = stream_context_create(array(
    'http' => array(
      'method'  => 'POST',
      'header'  => sprintf("Authorization: Basic %s\r\n", base64_encode($username.':'.$password)).
                   "Content-type: application/x-www-form-urlencoded\r\n",
      'content' => http_build_query(array('status' => $message)),
      'timeout' => 5,
    ),
  ));
  $ret = file_get_contents('http://twitter.com/statuses/update.xml', false, $context);
 
  return false !== $ret;
}

Pretty easy, no? Using the tweet() function is of course a piece of cake:

tweet('From PHP, yeah...', 'fabpot', 'Pa$$');

As an added bonus, the function returns true if everything went fine, or false otherwise.

As we talk about Twitter, you can follow me.

Quick SSH Tip

2009-06-09T19:40:00+02:00

If you need to regularly connect to a lot of different servers like I do, you probably use SSH to connect to them, and you also probably use your personal SSH identity file to ease the connection.

Some time ago, I re-discover a neat trick to simplify the connection by using the .ssh/config file. I don't know why I forgot about it, but as it seems that a lot of people around me do not know about this file either, here is a small post on how it can be used to your advantage.

Let's say you have a host at 1.2.3.4 you need to connect to and the username you need to use is fabien. Each time you want to connect to it, you need to type something like the following:

$ ssh fabien@1.2.3.4

Simple enough, even if you need to remember the remote user you need to use for each server. However, if you need to specify a specific key, it becomes more verbose:

$ ssh -i /Users/fabien/keys/myserver.key fabien@1.2.3.4

That's difficult to remember, quite tedious to write and error prone. Instead, I want to be able to just type:

$ ssh myserver

It's quite easy. Create a .ssh/config file under your home directory and put something like this inside:

Host myserver
  HostName 1.2.3.4
  User root
  IdentityFile /Users/fabien/keys/myserver.key

That's all there is to it. Now, connecting to the server is as easy as typing:

$ ssh myserver

And it works everywhere SSH is involved. For instance, when you use scp to copy a file:

$ scp localfile.txt myserver:/tmp/

It is also a great way to not give sensitive information in configuration files. For instance, in a symfony project, the properties.ini file can contain the information to connect to the production servers used for deployment. Instead of having to hardcode the real host name, the login and the password like this:

[production]
host=www.myserver.com
port=22
user=someusername
pass=somepassword
dir=/var/www/mysite/

You can simply reference the name you gave in the config file and keep the details secret on your local machine:

[production]
host=myserver
port=22
dir=/var/www/mysite/

Unix is really powerful thanks to little things like this one. By the way, if you want to know more about the Unix history, you can read the really interesting "Unix turns 40: The past, present and future of a revolutionary OS" article published on ComputerWorld.com earlier this month.

What for PHP6?

2009-06-07T21:10:00+02:00

PHP 5.3 is just around the corner with a lot of great new features. However, even if I'm really excited about this new release, I won't make yet another PHP 5.3 feature list; I will rather look at the future of PHP. PHP core developers met at php|tek and discussed the future of PHP. And it is really great to see that they plan lots of wonderful features; let's set aside the Unicode stuff.

They published some notes from the meeting, and here is my personal list for things I find really interesting:

Add __cast() magic method that will be called for all casts. If the __toString() method is there it will get used for string types first.
Consider making a "callable" type.
Make ArrayObject and ArrayAccess accepted everywhere regular arrays are.
Add traits support.
Add type hinted return values, scalar type hints.
Make function call chaining possible (f()() if f() returns a function), and array dereferencing (f()[0]).

C#-style properties with getters/setters:

class Foo
{
   public $bar
       getter { return $this->bar; }
       setter { $this->bar = strtolower($value); }
   ;
}

On PHP 5.3, Lambda Functions, and Closures

2009-04-16T14:00:00+02:00

PHP 5.3 will have a lot of exciting new features. One of the most important one for me is the introduction of lambda functions and closures support. I won't talk too much about what lambda functions or closures are, as you can find many good blog posts describing them in great details. To sum up, a lambda function is an anonymous PHP function that can be stored in a variable and passed as an argument to other functions or methods. A closure is a lambda function that is aware of its surrounding context.

The first obvious use for lambda functions and closures is in conjunction with the array_map(), array_reduce(), and array_filter() native PHP functions:

$input = array(1, 2, 3, 4, 5);
$output = array_filter($input, function ($v) { return $v > 2; });

The above example filters the input array by removing all values greater than 2:

$output == array(2 => 3, 3 => 4, 4 => 5)

function ($v) { return $v > 2; } is the lambda function definition and it can be stored in a PHP variable to be reusable:

$max_comparator = function ($v) { return $v > 2; };
 
$input = array(1, 2, 3, 4, 5);
$output = array_filter($input, $max_comparator);

But what if I want to change the maximum number allowed in the filtered array? I can either create another lambda function or use a closure:

$max_comparator = function ($max)
{
  return function ($v) use ($max) { return $v > $max; };
};
 
$input = array(1, 2, 3, 4, 5);
$output = array_filter($input, $max_comparator(2));

Now, the $max_comparator function takes the maximum allowed number and returns a function that is different according to this maximum. Even for such a contrived example, I hope you see the great power it gives you!

Closures also opens up a lot of great possibilities, like the implementation of the cryptic Y-combinator, as demonstrated by Stanislav Malyshev in one of his recent blog post:

function Y($F)
{
  $func = function ($f) { return $f($f); };
 
  return $func(function ($f) use($F)
  {
    return $F(function ($x) use($f)
    {
      $ff = $f($f);
 
      return $ff($x);
    });
  });
}

Today, I want to talk about yet great another example on how to use lambda functions and closures. You will see that it can simplify your code a lot when used appropriately.

If you have read my blog recently, you know that I am quite obsessed with dependency injection these days. This post will show you how to implement a very simple but still full-featured dependency injection container, thanks to the new features of PHP 5.3.

A dependency injection container must be able to manage two different kind of data: objects and parameters. And objects must be created on-demand the first time they are accessed from the container.

Using a simple class that implements the magic __get() and __set() methods, we can easily manage both the objects and the parameters:

class DIContainer
{
  protected $values = array();
 
  function __set($id, $value)
  {
    $this->values[$id] = $value;
  }
 
  function __get($id)
  {
    return is_callable($this->values[$id]) ? $this->values[$id]($this) : $this->values[$id];
  }
}

Using the container is quite simple:

$container = new DIContainer();
 
// define the parameters
$container->cookie_name = 'SESSION_ID';
$container->storage_class = 'SessionStorage';
 
// defined the objects
$container->storage = function ($c)
{
  return new $c->storage_class($c->cookie_name);
};
$container->user = function ($c)
{
  return new User($c->storage);
};
 
// get the user object
$user = $container->user;
 
// the above call is roughly equivalent to the following code:
// $storage = new SessionStorage('SESSION_ID');
// $user = new User($storage);

The examples I use in this article are the same as the one I have used in my series on dependency injection.

The definition of an object is done by defining a lambda function that returns an instance of the object.

The __get() method checks if the value associated with a key is a PHP callable (and lambda functions are callables) to make the difference between an object definition and a parameter.

Also notice how we call the lambda:

$this->values[$id]($this)

The trick here is to pass the container as an argument of the lambda function so that it can use the container to access parameters and other objects managed by the container.

We can make the container a bit better by adding error support:

class DIContainer
{
  protected $values = array();
 
  function __set($id, $value)
  {
    $this->values[$id] = $value;
  }
 
  function __get($id)
  {
    if (!isset($this->values[$id]))
    {
      throw new InvalidArgumentException(sprintf('Value "%s" is not defined.', $id));
    }
 
    return is_callable($this->values[$id]) ? $this->values[$id]($this) : $this->values[$id];
  }
}

Defining objects with lambda functions is great because the developer can do whatever he wants to actually create and configure instances. But we still need to implement one important feature of any dependency injection container: shared instances. This can be done manually like this:

$container->user = function ($c)
{
  static $object;
 
  if (is_null($object))
  {
    $object = new User($c->storage);
  }
 
  return $object;
};

By declaring a static variable in the lambda function, the first time it is called, the object is created and returned. For all subsequent calls, the same instance will always be returned.

It works as expected, but this is quite repetitive, tedious, and error prone. For all instances that must be unique, we need to add this boilerplate code. Instead, I want to support shared instances as a native feature of the container itself. Thanks to closures, that's quite easy to accomplish:

class DIContainer
{
  // ...
 
  function asShared($callable)
  {
    return function ($c) use ($callable)
    {
      static $object;
 
      if (is_null($object))
      {
        $object = $callable($c);
      }
 
      return $object;
    };
  }
}

The asShared() method wraps the given lambda function to add the needed logic we have seen before. Declaring an object as unique for a given container is now dead simple:

$c->user = $c->asShared(function ($c)
{
  return new User($c->storage);
});

In less than 30 lines of PHP, we have coded a full-featured dependency injection container. Quite impressive!

If we remove the need for shared instance, and if we define parameters and objects as lambdas, we can even compact the code so that it fits in a tweet:

class Container {
 protected $s=array();
 function __set($k, $c) { $this->s[$k]=$c; }
 function __get($k) { return $this->s[$k]($this); }
}

I have called this tweet container twittee, and it has its own dedicated website and github repository.

PHP 5.3 is really a great step forward for the PHP language.

Symfony Service Container: The Need for Speed

2009-04-02T07:50:00+02:00

This article is part of a series on Dependency Injection in general and on a lightweight implementation of a Container in PHP in particular:

Part 1: What is Dependency Injection?

Part 2: Do you need a Dependency Injection Container?

Part 3: Introduction to the Symfony Service Container

Part 4: Symfony Service Container: Using a Builder to create Services

Part 5: Symfony Service Container: Using XML or YAML to describe Services

Part 6: The Need for Speed

During the first five articles of this series on Dependency Injection, we have progressively introduced the main concepts behind this simple and useful design pattern. We have also talked about the implementation of a lightweight PHP container that will be used for Symfony 2.

But with the introduction of the XML and YAML configuration files, you might have became a bit sceptic about the performance of the container itself. Even if services are lazy loading, reading a bunch of XML or YAML files on each request and creating objects by using introspection is probably not very efficient in PHP. And because the container is almost always the corner stone of any application using it, its speed does matter a lot.

On the one hand, using XML or YAML to describe services and their configuration is very powerful and flexible:

<container xmlns="http://symfony-project.org/2.0/container">
  <parameters>
    <parameter key="mailer.username">foo</parameter>
    <parameter key="mailer.password">bar</parameter>
    <parameter key="mailer.class">Zend_Mail</parameter>
  </parameters>
  <services>
    <service id="mail.transport" class="Zend_Mail_Transport_Smtp" shared="false">
      <argument>smtp.gmail.com</argument>
      <argument type="collection">
        <argument key="auth">login</argument>
        <argument key="username">%mailer.username%</argument>
        <argument key="password">%mailer.password%</argument>
        <argument key="ssl">ssl</argument>
        <argument key="port">true</argument>
      </argument>
    </service>
    <service id="mailer" class="%mailer.class%">
      <call method="setDefaultTransport">
        <argument type="service" id="mail.transport" />
      </call>
    </service>
  </services>
</container>

But, on the other hand, defining the service container as a plain PHP class gives you the full speed, as seen during the second article of this series:

class Container extends sfServiceContainer
{
  static protected $shared = array();
 
  protected function getMailTransportService()
  {
    return new Zend_Mail_Transport_Smtp('smtp.gmail.com', array(
      'auth'     => 'login',
      'username' => $this['mailer.username'],
      'password' => $this['mailer.password'],
      'ssl'      => 'ssl',
      'port'     => 465,
    ));
  }
 
  protected function getMailerService()
  {
    if (isset(self::$shared['mailer']))
    {
      return self::$shared['mailer'];
    }
 
    $class = $this['mailer.class'];
 
    $mailer = new $class();
    $mailer->setDefaultTransport($this->getMailTransportService());
 
    return self::$shared['mailer'] = $mailer;
  }
}

The above code does the bare minimum to provide flexibility thanks to the configuration variables, and still be very fast.

How can you have the best of both world? That's quite simply. The Symfony Dependency Injection component provides yet another built-in dumper: a PHP dumper. This dumper can convert any service container to plain PHP code. That's right, it is able to generate the code you could have written by hand in the first place.

Let's use again our Zend_Mail example and for brevity's sake, let's use the XML definition file created in the previous article:

$sc = new sfServiceContainerBuilder();
 
$loader = new sfServiceContainerLoaderFileXml($sc);
$loader->load('/somewhere/container.xml');
 
$dumper = new sfServiceContainerDumperPhp($sc);
 
$code = $dumper->dump(array('class' => 'Container'));
 
file_put_contents('/somewhere/container.php', $code);

As for any other dumper, the sfServiceContainerDumperPhp class takes a container as its constructor first argument. The dump() method takes an array of options, and one of them is the name of the class to generate.

Here is the generated code:

class Container extends sfServiceContainer
{
  protected $shared = array();
 
  public function __construct()
  {
    parent::__construct($this->getDefaultParameters());
  }
 
  protected function getMailTransportService()
  {
    $instance = new Zend_Mail_Transport_Smtp('smtp.gmail.com', array(
      'auth' => 'login',
      'username' => $this->getParameter('mailer.username'),
      'password' => $this->getParameter('mailer.password'),
      'ssl' => 'ssl',
      'port' => 465
    ));
 
    return $instance;
  }
 
  protected function getMailerService()
  {
    if (isset($this->shared['mailer'])) return $this->shared['mailer'];
 
    $class = $this->getParameter('mailer.class');
    $instance = new $class();
    $instance->setDefaultTransport($this->getMailTransportService());
 
    return $this->shared['mailer'] = $instance;
  }
 
  protected function getDefaultParameters()
  {
    return array (
      'mailer.username' => 'foo',
      'mailer.password' => 'bar',
      'mailer.class' => 'Zend_Mail',
    );
  }
}

If you have a closer look at the code generated by the dumper, you will notice that the code is very similar to the one we wrote by hand.

The generated code does not use the shortcut notation to access parameters and services to be as fast as possible.

By using the sfServiceContainerDumperPhp dumper, you can have the best of both world: the flexibility of the XML or YAML format to describe and configure your services, and the speed of an optimized and auto-generated PHP file.

Of course, as projects have almost always different settings for different environments, you can of course generate different container classes, based on the environment or on a debugging setting. Here is a small snippet of PHP code that illustrates how to build the container dynamically for the very first request, and use a cached one for all other requests when not in debugging mode:

$name = 'Project'.md5($appDir.$isDebug.$environment).'ServiceContainer';
$file = sys_get_temp_dir().'/'.$name.'.php';
 
if (!$isDebug && file_exists($file))
{
  require_once $file;
  $sc = new $name();
}
else
{
  // build the service container dynamically
  $sc = new sfServiceContainerBuilder();
  $loader = new sfServiceContainerLoaderFileXml($sc);
  $loader->load('/somewhere/container.xml');
 
  if (!$isDebug)
  {
    $dumper = new sfServiceContainerDumperPhp($sc);
 
    file_put_contents($file, $dumper->dump(array('class' => $name));
  }
}

That wraps up our tour of the Symfony 2 Dependency Injection Container.

Before closing this series, I want to show you yet another great feature of the dumpers. Dumpers can do a lot of different things, and to demonstrate the decoupling of the implementation of the component, I have implemented a Graphviz dumper. What for? To help you visualize your services and their dependencies.

First, let's see how to use it on our example container:

$dumper = new sfServiceContainerDumperGraphviz($sc);
file_put_contents('/somewhere/container.dot', $dumper->dump());

The Graphviz dumper generates a dot representation of your container:

digraph sc {
  ratio="compress"
  node [fontsize="11" fontname="Myriad" shape="record"];
  edge [fontsize="9" fontname="Myriad" color="grey" arrowhead="open" arrowsize="0.5"];
 
  node_service_container [label="service_container\nsfServiceContainerBuilder\n", shape=record, fillcolor="#9999ff", style="filled"];
  node_mail_transport [label="mail.transport\nZend_Mail_Transport_Smtp\n", shape=record, fillcolor="#eeeeee", style="dotted"];
  node_mailer [label="mailer\nZend_Mail\n", shape=record, fillcolor="#eeeeee", style="filled"];
  node_mailer -> node_mail_transport [label="setDefaultTransport()" style="dashed"];
}

This representation can be converted to an image by using the dot program:

$ dot -Tpng /somewhere/container.dot > /somewhere/container.png

For this simple example, the visualization has no real added value, but as soon as you start having more than a few services, it can be quite useful... and beautiful.

The Graphviz dumper dump() method takes a lot of different options to tweak the output of the graph. Have a look at the source code to discover the default values for each of them:

graph: The default options for the whole graph

node: The default options for nodes

edge: The default options for edges

node.instance: The default options for services that are defined directly by object instances

node.definition: The default options for services that are defined via service definition instances

node.missing: The default options for missing services

As a teaser for the next Symfony component that will be released later this month, here is the graph for an hypothetic CMS using the Symfony 2 new Templating Framework:

That's all for this series on Dependency Injection. I hope you have learned something reading these articles. I also hope you will try the Symfony 2 Service Container component soon and give me feedback about your usage. Also, if you create "recipes" for some existing Open-Source libraries, consider sharing them with the community. You can also send them to me and I will host them along side the container component to ease reusing.

Symfony Service Container: Using XML or YAML to describe Services

2009-04-01T09:00:00+02:00

This article is part of a series on Dependency Injection in general and on a lightweight implementation of a Container in PHP in particular:

Part 1: What is Dependency Injection?

Part 2: Do you need a Dependency Injection Container?

Part 3: Introduction to the Symfony Service Container

Part 4: Symfony Service Container: Using a Builder to create Services

Part 5: Symfony Service Container: Using XML or YAML to describe Services

Part 6: The Need for Speed

With the last article on Dependency Injection, you learned how to describe services with PHP code by using the sfServiceContainerBuilder class. Today, with the help of service loaders and dumpers, you will learn how to use XML or YAML to describe your services.

The Subversion repository has been updated with the code needed for today's tutorial. If you got the code from yesterday's repository, ou can just update it (svn up). If not, the repository is available at http://svn.symfony-project.com/components/dependency_injection/trunk/.

The Symfony Dependency Injection component provides helper classes that load services using "loader objects". By default, the component comes with two of them: sfServiceContainerLoaderFileXml to load XML files, and sfServiceContainerLoaderFileYaml to load YAML files.

But before diving into the XML and YAML notations, let's first have a look at another part of the Symfony Dependency Injection component: the "dumper objects". A service dumper takes a container object and convert it to another format. And of course, the component comes bundled with dumpers for the XML and YAML formats.

To introduce the XML format, let's convert yesterday's container service definitions to a container.xml file by using the sfServiceContainerDumperXml dumper class.

Remember the code we used to define the Zend_Mail service?

require_once '/PATH/TO/sfServiceContainerAutoloader.php';
sfServiceContainerAutoloader::register();
 
$sc = new sfServiceContainerBuilder();
 
$sc->
  register('mail.transport', 'Zend_Mail_Transport_Smtp')->
  addArgument('smtp.gmail.com')->
  addArgument(array(
    'auth'     => 'login',
    'username' => '%mailer.username%',
    'password' => '%mailer.password%',
    'ssl'      => 'ssl',
    'port'     => 465,
  ))->
  setShared(false)
;
 
$sc->
  register('mailer', '%mailer.class%')->
  addMethodCall('setDefaultTransport', array(new sfServiceReference('mail.transport')))
;

To convert this container to an XML representation, use the following code:

$dumper = new sfServiceContainerDumperXml($sc);
 
file_put_contents('/somewhere/container.xml', $dumper->dump());

A dumper class constructor takes a service container builder object as its first argument and the dump() method introspects the container services and converts them to another representation. If everything went fine, the container.xml file should look like the following XML snippet:

<?xml version="1.0" ?>
 
<container xmlns="http://symfony-project.org/2.0/container">
  <parameters>
    <parameter key="mailer.username">foo</parameter>
    <parameter key="mailer.password">bar</parameter>
    <parameter key="mailer.class">Zend_Mail</parameter>
  </parameters>
  <services>
    <service id="mail.transport" class="Zend_Mail_Transport_Smtp" shared="false">
      <argument>smtp.gmail.com</argument>
      <argument type="collection">
        <argument key="auth">login</argument>
        <argument key="username">%mailer.username%</argument>
        <argument key="password">%mailer.password%</argument>
        <argument key="ssl">ssl</argument>
        <argument key="port">465</argument>
      </argument>
    </service>
    <service id="mailer" class="%mailer.class%">
      <call method="setDefaultTransport">
        <argument type="service" id="mail.transport" />
      </call>
    </service>
  </services>
</container>

The XML format supports anonymous services. An anonymous service is a service that does not need a name and is defined directly in its use context. It can be very convenient when you need a service that won't be used outside of another one scope:

<service id="mailer" class="%mailer.class%">
  <call method="setDefaultTransport">
    <argument type="service">
      <service class="Zend_Mail_Transport_Smtp">
        <argument>smtp.gmail.com</argument>
        <argument type="collection">
          <argument key="auth">login</argument>
          <argument key="username">%mailer.username%</argument>
          <argument key="password">%mailer.password%</argument>
          <argument key="ssl">ssl</argument>
          <argument key="port">465</argument>
        </argument>
      </service>
    </argument>
  </call>
</service>

Loading back the container is dead simple thanks to the XML service loader class:

require_once '/PATH/TO/sfServiceContainerAutoloader.php';
sfServiceContainerAutoloader::register();
 
$sc = new sfServiceContainerBuilder();
 
$loader = new sfServiceContainerLoaderFileXml($sc);
$loader->load('/somewhere/container.xml');

As for dumpers, a loader takes a service container builder as its constructor first argument, and the load() method reads the file and registers the services into the container. The container is then useable as usual.

If you change the dumper code to use the sfServiceContainerDumperYaml class instead, you will have a YAML representation of your services:

require_once '/PATH/TO/sfYaml.php';
 
$dumper = new sfServiceContainerDumperYaml($sc);
 
file_put_contents('/somewhere/container.yml', $dumper->dump());

This will only work if you first load the sfYAML component (http://svn.symfony-project.com/components/yaml/trunk/) as it is required for the service container loader and dumper.

The previous container is represented like follows in YAML:

parameters:
  mailer.username: foo
  mailer.password: bar
  mailer.class:    Zend_Mail
 
services:
  mail.transport:
    class:     Zend_Mail_Transport_Smtp
    arguments: [smtp.gmail.com, { auth: login, username: %mailer.username%, password: %mailer.password%, ssl: ssl, port: 465 }]
    shared:    false
  mailer:
    class: %mailer.class%
    calls:
      - [setDefaultTransport, [@mail.transport]]

You can of course mix and match the loaders and the dumpers to convert any format to any other one:

// Convert an XML container service definitions file to a YAML one
$sc = new sfServiceContainerBuilder();
 
$loader = new sfServiceContainerLoaderFileXml($sc);
$loader->load('/somewhere/container.xml');
 
$dumper = new sfServiceContainerDumperYaml($sc);
file_put_contents('/somewhere/container.yml', $dumper->dump());

To keep this article short, I won't list all possibilities of the YAML or XML format. But you can easily learn them by converting an existing container and look at the output.

Using YAML or XML files for configuring your services allows you to create your services with a GUI (yet to be done...). But it also opens a lot more interesting possibilities.

One of the most important one is the ability to import other "resources". A resource can be any other configuration file:

<container xmlns="http://symfony-project.org/2.0/container">
  <imports>
    <import resource="default.xml" />
  </imports>
  <parameters>
    <!-- These parameters override the one defined in default.xml -->
  </parameters>
  <services>
    <!-- These service definitions override the one defined in default.xml -->
  </services>
</container>

The imports section lists resources that need to be included before the other sections are evaluated. By default, it looks for files with a path relative to the current file, but you can also pass an array of paths to look in as the second argument of the loader:

$loader = new sfServiceContainerLoaderFileXml($sc, array('/another/path'));
$loader->load('/somewhere/container.xml');

You can even embed a YAML definition file in an XML one by defining the class that is able to load the resource:

<container xmlns="http://symfony-project.org/2.0/container">
  <imports>
    <import resource="default.yml" class="sfServiceContainerLoaderFileYaml" />
  </imports>
</container>

And of course, the same goes for the YAML format:

imports:
  - { resource: default.xml, class: sfServiceContainerLoaderFileXml }

The import facility gives you a flexible way to organize your service definition files. It is also a great way to share and reuse definition files. Let's talk about the web session example we introduced in the first article. When you use web sessions in a test environment, the session storage object probably need to be mocked; on the contrary, and if you have several load-balanced web servers, the production environment need to store its sessions in a database like MySQL. One way to have a different configuration based on the environment is to create several different configuration files and import them as needed:

<!-- in /framework/config/default/session.xml -->
<container xmlns="http://symfony-project.org/2.0/container">
  <parameters>
    <parameter key="session.class">sfSessionStorage</parameter>
  </parameters>
 
  <!-- service definitions go here -->
</container>
 
<!-- in /project/config/session_test.xml -->
<container xmlns="http://symfony-project.org/2.0/container">
  <imports>
    <import resource="session.xml" />
  </imports>
 
  <parameters>
    <parameter key="session.class">sfSessionTestStorage</parameter>
  </parameters>
</container>
 
<!-- in /project/config/session_prod.xml -->
<container xmlns="http://symfony-project.org/2.0/container">
  <imports>
    <import resource="session.xml" />
  </imports>
 
  <parameters>
    <parameter key="session.class">sfMySQLSessionStorage</parameter>
  </parameters>
</container>

Using the right configuration is trivial:

$loader = new sfServiceContainerLoaderFileXml($sc, array(
  '/framework/config/default/',
  '/project/config/',
));
$loader->load('/somewhere/session_'.$environment.'.xml');

I can hear people crying about using XML to define the configuration, as XML is probably not the most readable configuration format on earth. Coming from a Symfony background, you could have written all the files in the YAML format. But you can also decouple the service definitions from their configuration. As you can import files form other ones, you can define services in a services.xml file, and store the related configuration in a parameters.xml one. You can also define parameters in a YAML file (parameters.yml). Eventually, there is a last built-in INI loader that is able to read parameters from a standard INI file:

<!-- in /project/config/session_test.xml -->
<container xmlns="http://symfony-project.org/2.0/container">
  <imports>
    <import resource="config.ini" class="sfServiceContainerLoaderFileIni" />
  </imports>
</container>
 
<!-- /project/config/config.ini -->
[parameters]
session.class = sfSessionTestStorage

It is not possible to define services in an INI file; only parameters can be defined and parsed.

These examples barely scratches the surface of the container loaders and dumpers features, but I hope this article has been a good overview of the power of the XML and YAML formats over the PHP one. And for those who are sceptic about the performance of a container that needs to load several files to be configured, I think you will be blown away by the next article. As this will be the last installment of this series on Dependency Injection, I will also talk about a nice way to visualize your service dependencies.

Symfony Service Container: Using a Builder to create Services

2009-03-31T08:20:00+02:00

This article is part of a series on Dependency Injection in general and on a lightweight implementation of a Container in PHP in particular:

Part 1: What is Dependency Injection?

Part 2: Do you need a Dependency Injection Container?

Part 3: Introduction to the Symfony Service Container

Part 4: Symfony Service Container: Using a Builder to create Services

Part 5: Symfony Service Container: Using XML or YAML to describe Services

Part 6: The Need for Speed

In the previous article on Dependency Injection, you learned how to use the sfServiceContainer class to provide a more appealing interface to your service containers. In this article, we will go one step further and learn how to leverage the sfServiceContainerBuilder class to describe services and their configuration in pure PHP code.

The Subversion repository has been updated with the code needed for this tutorial. If you have checkout the code yesterday, you can simple update it. If not, the repository is available at http://svn.symfony-project.com/components/dependency_injection/trunk/.

The sfServiceContainerBuilder class extends the basic sfServiceContainer class and allows the developer to describe services with a simple PHP interface.

The Service Container Interface

All service container classes share the same interface, defined in sfServiceContainerInterface:

interface sfServiceContainerInterface
{
  public function setParameters(array $parameters);
  public function addParameters(array $parameters);
  public function getParameters();
  public function getParameter($name);
  public function setParameter($name, $value);
  public function hasParameter($name);
  public function setService($id, $service);
  public function getService($id);
  public function hasService($name);
}

The description of the services are done by registering service definitions. Each service definition describes a service: from the class to use to the arguments to pass to the constructor, and a bunch of other configuration properties (see the sfServiceDefinition sidebar below).

The Zend_Mail example can easily be rewritten by removing all the hardcoded code and building it dynamically with the builder class instead:

require_once 'PATH/TO/sf/lib/sfServiceContainerAutoloader.php';
sfServiceContainerAutoloader::register();
 
$sc = new sfServiceContainerBuilder();
 
$sc->
  register('mail.transport', 'Zend_Mail_Transport_Smtp')->
  addArgument('smtp.gmail.com')->
  addArgument(array(
    'auth'     => 'login',
    'username' => '%mailer.username%',
    'password' => '%mailer.password%',
    'ssl'      => 'ssl',
    'port'     => 465,
  ))->
  setShared(false)
;
 
$sc->
  register('mailer', '%mailer.class%')->
  addMethodCall('setDefaultTransport', array(new sfServiceReference('mail.transport')))
;

The creation of a service is done by calling the register() method, which takes the service name and the class name, and returns a sfServiceDefinition instance.

A service definition is internally represented by an object of class sfServiceDefinition. It is also possible to create one by hand and registering it directly by using the service container setServiceDefinition() method.

The definition object implements a fluid interface and provides methods that configure the service. In the above example, we have used the following ones:

addArgument(): Adds an argument to pass to the service constructor.
setShared(): Whether the service must be unique for a container or not (true by default).
addMethodCall(): A method to call after the service has been created. The second argument is an array of arguments to pass to the method.

Referencing a service is now done with a sfServiceReference instance. This special object is dynamically replaced with the actual service when the referencing service is created.

During the registration phase, no service is actually created, it is just about the description of the services. The services are only created when you actually want to work with them. It means you can register the services in any order without taking care of the dependencies between them. It also means you can override an existing service definition by re-registering a service with the same name. That's yet another simple way to override a service for testing purpose.

The sfServiceDefinition Class

A service has several properties that changes the way it is created and configured:

setConstructor(): Sets the static method to use when the service is created, instead of the standard new construct (useful for factories).

setClass(): Sets the service class.

setArguments(): Sets the arguments to pass to the constructor (the order is of course significant).

addArgument(): Adds an argument for the constructor.

setMethodCalls(): Sets the service methods to call after service creation. These methods are called in the same order as the registration.

addMethodCall(): Adds a service method call to call after service creation. You can add a call to the same method several times if needed.

setFile(): Sets a file to include before creating a service (useful if the service class if not autoloaded).

setShared(): Whether the service must be unique for a container or not (true by default).

setConfigurator(): Sets a PHP callable to call after the service has been configured.

As the sfServiceContainerBuilder class implements the standard sfServiceContainerInterface interface, using the service container does not need to be changed:

$sc->addParameters(array(
  'mailer.username' => 'foo',
  'mailer.password' => 'bar',
  'mailer.class'    => 'Zend_Mail',
));
 
$mailer = $sc->mailer;

The sfServiceContainerBuilder is able to describe any object instantiation and configuration. We have demonstrated it with the Zend_Mail class, and here is another example using the sfUser class from Symfony:

$sc = new sfServiceContainerBuilder(array(
  'storage.class'        => 'sfMySQLSessionStorage',
  'storage.options'      => array('database' => 'session', 'db_table' => 'session'),
  'user.class'           => 'sfUser',
  'user.default_culture' => 'en',
));
 
$sc->register('dispatcher', 'sfEventDispatcher');
 
$sc->
  register('storage', '%storage.class%')->
  addArgument('%storage.options%')
;
 
$sc->
  register('user', '%user.class%')->
  addArgument(new sfServiceReference('dispatcher'))->
  addArgument(new sfServiceReference('storage'))->
  addArgument(array('default_culture' => '%user.default_culture%'))->
;
 
$user = $sc->user;

In the Symfony example, even if the storage object takes an array of options as an argument, we passed a string placeholder (addArgument('%storage.options%')). The container is smarter enough to actually pass an array, the value of the placeholder.

That's all for today. Using PHP code to describe the services is quite simple and powerful. It gives you a tool to create your container without duplicating too much code and to abstract objects instantiation and configuration. In the next article, we will see how services can also be described with XML or YAML files. Stay tuned!

Introduction to the Symfony Service Container

2009-03-30T12:30:00+02:00

This article is part of a series on Dependency Injection in general and on a lightweight implementation of a Container in PHP in particular:

Part 1: What is Dependency Injection?

Part 2: Do you need a Dependency Injection Container?

Part 3: Introduction to the Symfony Service Container

Part 4: Symfony Service Container: Using a Builder to create Services

Part 5: Symfony Service Container: Using XML or YAML to describe Services

Part 6: The Need for Speed

Until now in this series on Dependency Injection, we have talked about general concepts. The first two introductory articles were important to better understand the implementation we will talk about in this article and in the following ones. It is now time to dive into the Symfony 2 service container implementation.

The Dependency Injection Container in Symfony is managed by a class named sfServiceContainer. It is a very lightweight class that implements the basic features we talked about in the last article.

The Symfony Service Container is available as a standalone component in the symfony official Subversion repository: http://svn.symfony-project.com/components/dependency_injection/trunk/. Keep in mind that this component is still under heavy development, which means that things can change.

In Symfony speak, a service is any object managed by the container. In the Zend_Mail example from the last article, we had two of them: the mailer service and the mail_transport service:

class Container
{
  static protected $shared = array();
 
  protected $parameters = array();
 
  public function __construct(array $parameters = array())
  {
    $this->parameters = $parameters;
  }
 
  public function getMailTransport()
  {
    return new Zend_Mail_Transport_Smtp('smtp.gmail.com', array(
      'auth'     => 'login',
      'username' => $this->parameters['mailer.username'],
      'password' => $this->parameters['mailer.password'],
      'ssl'      => 'ssl',
      'port'     => 465,
    ));
  }
 
  public function getMailer()
  {
    if (isset(self::$shared['mailer']))
    {
      return self::$shared['mailer'];
    }
 
    $class = $this->parameters['mailer.class'];
 
    $mailer = new $class();
    $mailer->setDefaultTransport($this->getMailTransport());
 
    return self::$shared['mailer'] = $mailer;
  }
}

If we make the Container class extend the sfServiceContainer Symfony class, we can simplify the code a bit:

class Container extends sfServiceContainer
{
  static protected $shared = array();
 
  protected function getMailTransportService()
  {
    return new Zend_Mail_Transport_Smtp('smtp.gmail.com', array(
      'auth'     => 'login',
      'username' => $this['mailer.username'],
      'password' => $this['mailer.password'],
      'ssl'      => 'ssl',
      'port'     => 465,
    ));
  }
 
  protected function getMailerService()
  {
    if (isset(self::$shared['mailer']))
    {
      return self::$shared['mailer'];
    }
 
    $class = $this['mailer.class'];
 
    $mailer = new $class();
    $mailer->setDefaultTransport($this->getMailTransportService());
 
    return self::$shared['mailer'] = $mailer;
  }
}

That's not much, but it will give us a more powerful and clean interface. Here is the main changes we made:

The method names have been suffixed with Service. By convention, a service is to be defined by a method prefixed by get and suffixed by Service. Each service has a unique identifier, which is the underscored version of the method name without the prefix and suffix. By defining a getMailTransportService() method, we have defined a service named mail_transport.
The methods are now protected. We will see in a minute how to retrieve services from the container.
The container can be used as an array to get parameter values ($this['mailer.class']).

A service identifier must be unique and must be made of letters, numbers, underscores, and dots. Dots are useful to define "namespaces" within your container (for instance mail.mailer and mail.transport).

Let's see how to use the new container class:

require_once 'PATH/TO/sf/lib/sfServiceContainerAutoloader.php';
sfServiceContainerAutoloader::register();
 
$sc = new Container(array(
  'mailer.username' => 'foo',
  'mailer.password' => 'bar',
  'mailer.class'    => 'Zend_Mail',
));
 
$mailer = $sc->mailer;

Now, because the Container class extends the sfServiceContainer class, we can enjoy a cleaner interface:

Services are accessible via a uniform interface:

if ($sc->hasService('mailer'))
{
  $mailer = $sc->getService('mailer');
}
 
$sc->setService('mailer', $mailer);

As a shortcut, services are also accessible by using the class property notation:

if (isset($sc->mailer))
{
  $mailer = $sc->mailer;
}
 
$sc->mailer = $mailer;

Parameters are accessible via a uniform interface:

if (!$sc->hasParameter('mailer_class'))
{
  $sc->setParameter('mailer_class', 'Zend_Mail');
}
 
echo $sc->getParameter('mailer_class');
 
// Override all parameters of the container
$sc->setParameters($parameters);
 
// Adds parameters
$sc->addParameters($parameters);

As a shortcut, parameters are also accessible by using the container like an array:

if (!isset($sc['mailer.class']))
{
  $sc['mailer.class'] = 'Zend_Mail';
}
 
$mailerClass = $sc['mailer.class'];

You can also iterate over all services of a container:

foreach ($sc as $id => $service)
{
  echo sprintf("Service %s is an instance of %s.\n", $id, get_class($service));
}

Using the sfServiceContainer class is very useful when you have a very small number of services to manage; even if you still need to do a lot of groundwork yourself, and duplicate a lot of code. But, if the number of services to be managed starts to grow beyond a few of them, we need a better way to describe the services.

That's why, most of the time, you don't use the sfServiceContainer class directly. It was nonetheless important to take some time to describe it as it is the corner stone of the Symfony dependency injection container implementation.

In the next article, we will have a look at the sfServiceContainerBuilder class, which eases the service definition process.