PHP // William Durand

[Video] Software testing: past, present, future

2014-11-09T00:00:00+00:00

Last month, I gave a talk on software testing at Forum PHP 2014 in Paris, organized by the french foundation of French speaking PHP users (AFUP). Then again, congratulations to the team, this event was a blast! (As usual, I would say :-))

In this talk, I gave an overview of what software testing was, describing three different periods: past, present, and future, hence the title of this talk.

You will find the video of my talk below (in French, sorry):

And, here are my slides:

If you attended my talk and did not rate it yet, please leave a comment on joind.in.

[Video] REST dans le monde Symfony

2014-07-16T00:00:00+00:00

Last month, I gave a talk about REST and Symfony at PHP Tour Lyon 2014, organized by the french foundation of French speaking PHP users (AFUP). Congratulations to the team, this event was a blast!

You will find the video of my talk below (in French, sorry):

And here are my slides:

I used the symfony-rest-edition and Propilex projects for the demos.

If you attended my talk and did not rate it yet, please leave a comment on joind.in.

RESTing with Symfony: SOS

2014-07-02T00:00:00+00:00

Two years ago, I wrote REST APIs with Symfony2: The Right Way, one of my most popular blog posts, but also one of the most well-known blog post about Symfony and REST. At first glance, I could enjoy this situation, but it actually makes me sad, and that is what I am going to explain here.

Lukas and I give talks to spread the word about RESTing with Symfony for the last year now. Sure thing is that we have a nice set of components (libraries and bundles) that work well together, and provide a lot of interesting features. For those who are not aware of this, checkout our slides! The Symfony developers behind all of this even contributed to the PHP ecosystem at large as most of the features are provided as standalone PHP libraries. Fantastic!

Not really. Last year, Lukas wrote a blog post explaining what was needed to REST in Symfony, and there was still a lot of work left. Did things change? Not really, again. That was in 2013, and remember that my blog post has been written in 2012.

Come on we are in 2014, and to me, nothing has changed! Sure we have a couple of “recent” blog posts such as the Symfony2 REST API: the best way series. It is a nice series, not only s/right/best, but it covers pretty much the same things I covered two years ago. I didn’t see any other interesting blog post about REST with Symfony recently unfortunately… Lately, Ryan, Leanna and I created a screencast named RESTful APIs in the Real World. I came across a few new bundles, mainly focused on authentication such as ApiKeyBundle and LexikJWTAuthenticationBundle. That is it!

I think that we, the Symfony folks interested in APIs and REST stuff, have two problems:

a clear lack of contributions (not only in term of code, documentation matters too);
too few new big features.

For instance, we could probably leverage the GeneratorBundle to scaffold an API. We probably need more integration with client-side applications (AngularJS, Backbone.js, whatever). People could write blog posts explaining how they built their API, because I am pretty sure there are people here who already built an API with Symfony. Existing bundles and libraries also need regular contributors, but this is obvious. Also, if you have other ideas or comments, you can leverage the new Developer eXperience (DX) system.

Please, help!

Enforcing Data Encapsulation with Symfony Forms

2013-12-16T00:00:00+00:00

Having classes (entities or whatever related to your model layer) that exposes attributes publicly, i.e. setters and getters for all attributes is just a non sense. Basically, a class with attributes/getters/setters is the same thing as a class with public properties or even as an array. Don’t do that!

You should rather write classes that own data, and keep them in a safe place. That is called encapsulation. Encapsulation is one of the four fundamentals in Object-Oriented Programming (OOP). It is used to hide the values or state of a structured object inside a class, preventing unauthorized parties direct access to them. That is why you should avoid getters and setters as much as you can, not to say all the time!

Working with the Symfony Form, it may be hard to decouple your code, and to not rely on getters and setters. Mathias Verraes describes a great approach in Decoupling (Symfony2) Forms from Entities, and I strongly agree with him. To sum up, the Form component should be used in your Presentation Layer, and it should not mess with your Model Layer. Use commands or DTOs with Forms, then create or act on your Model entities in the Application Layer (i.e. in your controllers).

However, the aim of this blog post is to show you how to keep decent model classes even with the Form component. In other words, don’t write poor model classes because of the framework you are using. You should design your model classes to fit your business, and according to OOP paradigms, not because framework X sucks at hydrating an object. I guess it is Hibernate’s fault at some point, at least in the Java world with their POJOs/JavaBeans, but I am digressing…

The solution to not rely on getters and setters is to control how objects are created into the Form component. In order to do that, you can rely on the empty_data option.

Let’s take an example. Among other things, your model layer defines a Customer entity that owns a name and an Email value object. You don’t want to break encapsulation and write SOLID code instead, so you end up writing the following Customer class definition:

<?php

namespace My\Model;

class Customer
{
    private $name;

    /**
     * @var Email
     */
    private $email;

    public function __construct($name, Email $email)
    {
        $this->name  = $name;
        $this->email = $email;
    }
}

The Email value object can be defined as follows. Thank you Mathias by the way.

<?php

namespace My\Model;

class Email
{
    private $email;

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

In your CustomerType, all you need to do is configure the empty_data option in the setDefaultOptions() method using a closure:

<?php

namespace My\Form\Type;

use My\Model\Customer;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\Form\FormInterface;
use Symfony\Component\OptionsResolver\OptionsResolverInterface;

class CustomerType extends AbstractType
{
    /**
     * {@inheritdoc}
     */
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('name', 'string')
            ->add('email', new EmailType())
        ;
    }

    /**
     * {@inheritdoc}
     */
    public function setDefaultOptions(OptionsResolverInterface $resolver)
    {
        $resolver->setDefaults(array(
            'data_class' => 'My\Model\Customer',
            'empty_data' => function (FormInterface $form) {
                return new Customer(
                    $form->get('name')->getData(),
                    $form->get('email')->getData()
                );
            }
        ));
    }

    // ...
}

It is worth mentioning that it works fine with custom types, collections, and so on. In the example above, it relies on a custom EmailType rather than directly using the built-in email type and creating the value object in the CustomerType. The creation is left to this EmailType. Calling getData() on $form->get('email') actually returns an Email object.

For the record, here is the EmailType definition:

<?php

namespace My\Form\Type;

use My\Model\Email;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\Form\FormInterface;
use Symfony\Component\OptionsResolver\OptionsResolverInterface;

class EmailType extends AbstractType
{
    /**
     * {@inheritdoc}
     */
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder->add('email', 'email');
    }

    /**
     * {@inheritdoc}
     */
    public function setDefaultOptions(OptionsResolverInterface $resolver)
    {
        $resolver->setDefaults(array(
            'data_class' => 'My\Model\Email',
            'empty_data' => function (FormInterface $form) {
                return new Email(
                    $form->get('email')->getData()
                );
            }
        ));
    }

    // ...
}

No more excuse to write crappy model classes now!

DDD with Symfony2: Basic Persistence & Testing

2013-11-13T00:00:00+00:00

After having described a decent folder structure and made things clear about DDD and this series, I will continue to bootstrap the sample application, focusing on a basic persistence layer and testing. It is not tied to DDD but it is worth writing about these two points.

A basic persistence layer is a layer that is simple. In other words, it does the job, period. It has poor performances, but it does not matter. What matters is that you can develop your application without having to decide whether you will use MySQL rather than a NoSQL database or an API for instance.

The `YamlUserRepository` Repository

Until now, the application used the InMemoryUserRepository described in the first blog post of this series. In order to introduce new concepts later in this series, you need a real persistence layer that is able to load and store data. That is why you need a YamlUserRepository.

For the record, YAML is a data serialization format that is both simple and human readable. You don’t need to focus on performance right now, so storing data in a file is ok.

Here is the implementation of the YamlUserRepository. That might not be the perfect/best implementation but it actually works:

<?php

namespace Acme\CoreDomainBundle\Repository;

use Acme\CoreDomain\User\User;
use Acme\CoreDomain\User\UserId;
use Acme\CoreDomain\User\UserRepository;
use Symfony\Component\Filesystem\Filesystem;
use Symfony\Component\Yaml\Yaml;

class YamlUserRepository implements UserRepository
{
    private $filename;

    public function __construct($filename)
    {
        $this->filename = $filename;

        (new Filesystem())->touch($this->filename);
    }

    /**
     * {@inheritDoc}
     */
    public function find(UserId $userId)
    {
        foreach ($this->findAll() as $user) {
            if ($user->getId()->isEqualTo($userId)) {
                return $user;
            }
        }

        return null;
    }

    /**
     * {@inheritDoc}
     */
    public function findAll()
    {
        $users = array();
        foreach ($this->getRows() as $row) {
            $users[] = new User(
                new UserId($row['id']),
                $row['first_name'],
                $row['last_name']
            );
        }

        return $users;
    }

    /**
     * {@inheritDoc}
     */
    public function add(User $user)
    {
        $rows = array();
        foreach ($this->getRows() as $row) {
            if ($user->getId()->isEqualTo(new UserId($row['id']))) {
                continue;
            }

            $rows[] = $row;
        }

        $rows[] = array(
            'id'         => $user->getId()->getValue(),
            'first_name' => $user->getFirstName(),
            'last_name'  => $user->getLastName(),
        );

        file_put_contents($this->filename, Yaml::dump($rows));
    }

    /**
     * {@inheritDoc}
     */
    public function remove(User $user)
    {
        $rows = array();
        foreach ($this->getRows() as $row) {
            if ($user->getId()->isEqualTo(new UserId($row['id']))) {
                continue;
            }

            $rows[] = $row;
        }

        file_put_contents($this->filename, Yaml::dump($rows));
    }

    private function getRows()
    {
        return Yaml::parse($this->filename) ?: array();
    }
}

This new repository relies on two Symfony2 components: Filesystem and Yaml.

As you might notice, the identity between two users is checked by the isEqualTo() method, part of the UserId value object. The body of this method is pretty straightforward:

public function isEqualTo(UserId $userId)
{
    return $this->getValue() === $userId->getValue();
}

Register the new repository into the Dependency Injection Container (DIC). The YamlUserRepository class takes a filename as first argument, that is why the service definition contains a <argument> tag.

The file will be created into the cache directory (%kernel.cache_dir%) meaning that if you clear the cache, your data will be lost.

<!-- src/Acme/CoreDomainBundle/Resources/config/repositories.xml -->
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <parameters>
        <!-- ... -->
        <parameter key="user_repository.yaml.class">Acme\CoreDomainBundle\Repository\YamlUserRepository</parameter>
    </parameters>

    <services>
        <!-- ... -->

        <!-- Concrete Implementations -->
        <service id="user_repository.yaml" class="%user_repository.yaml.class%" public="false">
            <argument>%kernel.cache_dir%/users.yml</argument>
        </service>
    </services>
</container>

Using the YamlUserRepository rather than the InMemoryUserRepository is just a matter of configuration. Change the alias for the user_repository service and you are done:

<service id="user_repository" alias="user_repository.yaml"></service>

Looks good? No! I told you that the implementation worked fine, did you trust me? You should not, and you should write tests instead.

Unit Testing

Testing the YamlUserRepository implementation looks pretty easy, except that it relies on the filesystem to load and store data. Most of the developers I know would touch a temporary file at the beginning of each test method and delete it at the end. That is not the right way to test such a thing.

vfsStream to the rescue! It is a stream wrapper for a virtual filesystem, which can be used to mock the real filesystem. That is exactly what you need.

Install it as a dev package:

$ composer require mikey179/vfsStream:"1.3.*@dev" --dev

First, you need to setup the virtual filesystem using the vfsStream::setup() method. Then, you can create a virtual filename that will be injected into your YamlUserRepository just like the DIC would do it:

<?php

namespace Acme\CoreDomainBundle\Tests\Repository;

use org\bovigo\vfs\vfsStream;
use Acme\CoreDomainBundle\Repository\YamlUserRepository;
use Acme\CoreDomainBundle\Tests\TestCase;
use Acme\CoreDomain\User\User;
use Acme\CoreDomain\User\UserId;

class YamlUserRepositoryTest extends TestCase
{
    private $cacheDir;

    private $repository;

    protected function setUp()
    {
        $this->cacheDir   = vfsStream::setup('cache');
        $this->repository = new YamlUserRepository(vfsStream::url('cache/users.yml'));
    }
}

The following method creates fixtures that will be useful in your test methods:

<?php

class YamlUserRepositoryTest extends TestCase
{

    // ...

    protected function addUsers()
    {
        $this->repository->add(
            new User(new UserId('62A0CEB4-0403-4AA6-A6CD-1EE808AD4D23'), 'Jean', 'Bon')
        );
        $this->repository->add(
            new User(new UserId('62A0CEB4-0403-4AA6-A6CD-1EE808AD4D44'), 'John', 'Doe')
        );
    }
}

And here are your first tests:

<?php

class YamlUserRepositoryTest extends TestCase
{

    // ...

    public function testFind()
    {
        $this->addUsers();

        $user = $this->repository->find(
            new UserId('62A0CEB4-0403-4AA6-A6CD-1EE808AD4D23')
        );

        $this->assertNotNull($user);
        $this->assertInstanceOf('Sportbook\CoreDomain\User\User', $user);
        $this->assertEquals('Jean', $user->getName()->getFirstName());
    }

    public function testFindReturnsNullIfNotFound()
    {
        $user = $this->repository->find(
            new UserId('62A0CEB4-0403-4AA6-A6CD-1EE808AD4D23')
        );

        $this->assertNull($user);
    }

    public function testAdd()
    {
        $this->addUsers();
        $expected = <<<YAML
-
    id: 62A0CEB4-0403-4AA6-A6CD-1EE808AD4D23
    first_name: Jean
    last_name: Bon
-
    id: 62A0CEB4-0403-4AA6-A6CD-1EE808AD4D44
    first_name: John
    last_name: Doe

YAML;
        $this->assertEquals(
            $expected,
            $this->cacheDir->getChild('users.yml')->getContent()
        );
    }
}

Note that the testAdd() method is just an example on how to use vfsStream. Also, I won’t cover all tests that should be written for this repository, however you must test all its public methods.

Now, let’s setup the functional tests.

Functional Testing

A while ago, I created a bundle named BazingaRestExtraBundle, which contains various tools that are not part of the FOSRestBundle (yet). One of the most useful class is the WebTestCase which extends the Symfony one, and provides methods that I use all the time while testing REST APIs, especially the assertJsonResponse() I already covered.

Require it as dev package:

$ composer require willdurand/rest-extra-bundle:"0.0.*" --dev

Then, create your first functional test class:

<?php

namespace Acme\ApiBundle\Tests\Controller;

use Bazinga\Bundle\RestExtraBundle\Test\WebTestCase;

class UserControllerTest extends WebTestCase
{
    public function testAll()
    {
        $client   = static::createClient();
        $crawler  = $client->request('GET', '/users.json');
        $response = $client->getResponse();

        $this->assertJsonResponse($response);
    }
}

This test should fail because you didn’t provide any fixtures. Use the setUp() method to copy a fixtures file to the cache directory so that you keep control over the data in your tests:

<?php

class UserControllerTest extends WebTestCase
{
    // ...

    protected function setUp()
    {
        $this->client = static::createClient();

        (new Filesystem())->copy(
            __DIR__ . '/../Fixtures/users.yml',
            $this->client->getContainer()->get('kernel')->getCacheDir() . '/users.yml',
            true
        );
    }
}

The Fixtures/users.yml file contains the following data:

- id: 50AAF29D-DB0B-43FE-9DD8-2F1C058416C5
  first_name: Jean
  last_name: Bon
- id: 53E2F088-E0B0-4A21-86A8-67B2FD6A2749
  first_name: John
  last_name: Doe

That’s it! You are able to test your application in a functional way like a boss!

Conclusion

As of now, the sample application looks good. It does not do much things right now, but everything is bootstrapped. You should keep in mind that testing is really important, and that you should use the right tools even in your tests. vfsStream is awesome!

Hopefully you now understand why combining programming to the interface with dependency injection is powerful. Replacing an implementation to another one is just a matter of alias here.

In the next blog post, I will mainly cover factories, stay tuned!

Taking Geocoder to the next level

2013-08-29T00:00:00+00:00

Almost two years ago, I pushed the first commits of a project that was anything but useful. I started this project to ease a friend’s life – @themouette – who was playing with the Google Maps API in a PHP app back then. I named this project Geocoder because I could not come up with a better name…

A few weeks later, this project got a lot more attention, I received very positive feedback and people started to contribute. That was amazing! At the time of writing, more than 630 commits have been made by 43 contributors. According to Packagist, it has been installed more than 40K times. Awesome for such a library!

Geocoder is an abstraction layer for most of the existing third-party geocoding APIs. It is rather specific and that is why these numbers look even more awesome to me! This project became my most starred library on GitHub, and the project has been featured by Smashing Magazine on Twitter ❤️

I believe it became relatively successful because Geocoder has been created to answer only one need, and the scope was small enough. The library was focused on (reverse) geocoding addresses, nothing more and certainly nothing fancy.

Earlier this week, I decided to move forward with this project. First of all, I am glad to unveil a new website available at geocoder-php.org. The homepage introduces Geocoder as well as its related projects. More projects will join the family soon! Each project has its own documentation page and a cookbook will be published soon..

In addition to that, a new GitHub organization called geocoder-php has been created to gather all the folks interested in the project. It is critical for such a project to be maintained, and that is why I asked key people to join the new Geocoder family. Our goal is to make Geocoder even better and future-proof!

Last but not least, Geocoder now has its own shiny logo:

We, the Geocoder core team, intend to ship new features and release often. Your feedback is important. Please get in touch with us about missing features and so on. Also, if you are using Geocoder, I would personally be glad to hear from you!

Special thanks to Antoine, Markus, and all contributors.

DDD with Symfony2: Making Things Clear

2013-08-20T00:00:00+00:00

Domain Driven Design also known as DDD is an approach to develop software for complex needs by connecting the implementation to an evolving model. It is a way of thinking and a set of priorities, aimed at accelerating software projects that have to deal with complicated domains.

It is possible to use this approach in a Symfony2 project, and that is what I am going to introduce in a series of blog posts. You will learn how to build an application that manages users through a REST API using Domain Driven Design.

This is the second article of this series! You should read Folder Structure And Code First before digging into that one. This blog post is an attempt to fix a few misunderstandings coming from the first post. I recommend you to quickly jump to all links, they are valuable!

DDD Is Not RAD

Domain Driven Design is not a fast way to build a software. It is not RAD at all! It implies a lot of boilerplate code, tons of classes, and so on. No, really. It is not the fastest way to write an application. No one ever said that DDD was simple or easy.

However, it is able to ease your life when you have to deal with complex business expectations. How? By considering your domain (also known as your business) as the heart of your application. Honestly, DDD should be used in a rather large application, with complex business rules and scenarios. Don’t use it if you are building a blog, it does not make much sense (even if it is probably the best way to learn the hard way). So question is when to use DDD? I would say when your domain is very complex, or when the business requirements change fast.

There Is No Database

In DDD, we don’t consider any databases. DDD is all about the domain, not about the database, and Persistence Ignorance (PI) is a very important aspect of DDD.

With Persistence Ignorance, we try and eliminate all knowledge from our business objects of how, where, why or even if they will be stored somewhere. Persistence Ignorance means that the business logic itself doesn’t know about persistence. In other words, your Entities should not be tied to any persistence layer or framework.

So, don’t expect me to make choices because it works better with Doctrine, Propel or whatever. This is not how we should use DDD. We, as developers, need to become part of our business users domains, we need to stop thinking in technical terms and constructs, and need to immerse ourselves in the world our business users inhabit.

DDD And REST

By now, I use a REST API as Presentation Layer. It is perfectly doable and, even if both concepts seem opposites, they play nice together. Remember that one of the strengths of DDD is the separation of concerns thanks to distinct layers. I am afraid that people think that it is not possible to play with both at the same time because nobody understands REST or HTTP.

Basically, you should not expose your Domain Model as-is over a public interface such as a REST API. That is why you should use Data Transfer Objects (DTOs). DTOs are simple objects that should not contain any business logic that would require testing by the way. A DTO could be seen as a PHP array actually.

What you should do here is to write a REST API that exposes resources that make sense for the clients (the clients that consume your API), and that are not always 1-1 with your Domain Model. See these resources as DTOs. For instance, if you deal with Orders and Payments, you could create a transaction resource to perform the business operation payOrder(Order $order, Payment $payment) as proposed by Jonathan Bensaid in the (now deleted) comments of the previous article:

POST /transactions
orderId=123&paymentId=456&...

The Application Layer will receive the data from the Presentation Layer and call the Domain Layer. This transaction is a DTO. It is not part of the domain but it is useful to exchange information between the Presentation and the Application layers.

However, in the previous article I was able to directly map my User Entity to resources of type users. But if you look at the whole thing, I used a Serializer component to only expose some properties. That is actually another sort of DTO. The Entity is transformed to only expose data that are relevant for the clients (the clients that consume your API). So it is ok(-ish)!

Also, note that HTTP methods explicitly delineate commands and queries. That means Command Query Responsibility Separation CQRS maps directly to HTTP. Hurray!

So, What’s Next?

In this series, I will introduce a more complex business, don’t worry! Hopefully I was clear enough to explain my choices regarding this series, and I fixed some misconceptions about DDD, RAD, and REST.

In the next blog post, I will introduce the Presentation Layer, new Value Objects such as the Name one, and more on DDD! At the end of the next post, you will basically get a CRUD-ish application. Yes, I know… CRUD is an anti-pattern, but it does not mean you should avoid it all the time. Creating new users make sense afterall.

The third post will allow you to create almost everything you need in the different DDD layers to build a strong and powerful domain, with complex logic, and so on. You may not get why DDD is great until that, so don’t panic and stay tuned!

DDD with Symfony2: Folder Structure And Code First

2013-08-07T00:00:00+00:00

Bootstrap

Start by creating a fresh project using the symfony-standard edition:

composer create-project symfony/framework-standard-edition path/to/install

I use to remove unecessary files such as src/*, as well as useless bundles. My composer.json file requires the following packages (for now):

"require": {
    "php": ">=5.3.3",
    "symfony/symfony": "2.3.*",
    "sensio/distribution-bundle": "2.3.*",
    "twig/extensions": "1.0.*",
    "symfony/monolog-bundle": "2.3.*",
    "incenteev/composer-parameter-handler": "~2.0",
    "sensio/framework-extra-bundle": "~2.3"
}

Don’t forget to update the AppKernel class accordingly. You are now ready!

Folder Structure

As Mathias Verraes stated in his blog post about Code Folder Structures, most of the usual Symfony2 project folder structures are not efficient. That is why it is important to spend some time designing a decent folder structure.

In your case, the domain expert said users are centrepieces. The word User is part of the Ubiquitous Language, the term Eric Evans uses in DDD for the practice of building up a common, rigorous language between developers and users.

At first glance, it sounds like a good idea to create a CoreDomainBundle or even a UserBundle bundle that will own users related things. Nein Nein Nein Nein Nein Nein! I too often say that bundles should integrate libraries, and I am not the only one.

This also applies to your bundles, so users related stuff will better live in a CoreDomain package:

src
└── Acme
    └── CoreDomain
        └── User

However, you still need a CoreDomainBundle bundle in order to integrate your CoreDomain package into your Symfony2 project:

src
└── Acme
    ├── CoreDomain
    │   └── User
    └── CoreDomainBundle
        └── AcmeCoreDomainBundle.php

This package is part of the Domain Layer. This layer is the heart of your application. Business rules and logic live inside this layer. Business entity state and behavior are defined and used here. Next section is about designing this Domain Layer using a Code First approach.

Code First

The Code First approach provides an alternative to the well-known Database First approach. As far as I know, it comes from the Microsoft world, but it does not really matter.

Using a Database First approach, you design your database schema, and then generate your classes. That is how Propel works for instance. It is RAD compliant, but it does not fit the DDD mindset.

Let’s try the Code First approach then. Basically, start by writing your classes, think in term of objects, not tables. You don’t have to take care of the database yet. The domain expert said a User has an identifier, a first name, and a last name.

The User class is called an Entity in DDD as it has an identity. It is unique within the system. Identity can be represented in many ways on an entity, it could be a numeric identifier, a GUID, or a natural key. Note that these Entities are not the same as the Doctrine ones. They might be Doctrine classes, but they don’t have to be.

<?php

namespace Acme\CoreDomain\User;

class User
{
    private $id;

    private $firstName;

    private $lastName;

    public function __construct(UserId $id, $firstName, $lastName)
    {
        $this->id        = $id;
        $this->firstName = $firstName;
        $this->lastName  = $lastName;
    }

    public function getId()
    {
        return $this->id;
    }

    public function getFirstName()
    {
        return $this->firstName;
    }

    public function getLastName()
    {
        return $this->lastName;
    }
}

Generally speaking, try to avoid setters in order to make your code solid. You could use a Value Object to represent the name of the user but it is not mandatory.

By the way, a Value Object is a simple object whose equality is not based on identity, instead two Value Objects are equal if all their fields are equal. Value Objects can be a Money or date range object. Their key property is that they follow value semantics rather than reference semantics. They don’t however have any value other than by virtue of their attributes. Also, Value Objects should be immutable. If you want to change a Value Object you should replace the object with a new one.

As you might noticed, the User identifier is represented by a UserId instance, not a scalar type because you don’t know which type to use. Will it be a numeric identifier or a GUID? You don’t know yet. Also, instead of passing IDs everywhere, having a class for them makes this very explicit. This UserId class is your very first Value Object:

<?php

namespace Acme\CoreDomain\User;

class UserId
{
    private $value;

    public function __construct($value)
    {
        $this->value = (string) $value;
    }

    public function getValue()
    {
        return $this->value;
    }
}

The domain expert said the application will manage users, so your application will deal with a collection of users. In DDD, a collection can be implemented by using the Repository design pattern.

A Repository mediates between the domain and data mapping using a collection-like interface for accessing domain objects. It is not a Data Access Layer though, as it deals with Entities and Value Objects. Note that there are various Repository implementation patterns but, in your case, here is how your UserRepository interface should look like:

<?php

namespace Acme\CoreDomain\User;

interface UserRepository
{
    public function find(UserId $userId);

    public function findAll();

    public function add(User $user);

    public function remove(User $user);
}

You should end up with the following folder structure:

src
└── Acme
    ├── CoreDomain
    │   └── User
    │       ├── User.php
    │       ├── UserId.php
    │       └── UserRepository.php
    └── CoreDomainBundle
        └── AcmeCoreDomainBundle.php

Now that you have a decent Domain Layer with Entities, Value Objects, and Repositories, let’s wire it to your Symfony2 application. Note that your Domain Layer is reusable, and loosely coupled. That is really important!

The Infrastructure Layer

In a Code First approach, you can delay the decision to choose a persistence layer. The main advantage is to be able to write some other parts of the application without having to wait.

You can create a InMemoryUserRepository class that implements the UserRepository interface which contains hardcoded objects:

<?php

namespace Acme\CoreDomainBundle\Repository;

use Acme\CoreDomain\User\User;
use Acme\CoreDomain\User\UserId;
use Acme\CoreDomain\User\UserRepository;

class InMemoryUserRepository implements UserRepository
{
    private $users;

    public function __construct()
    {
        $this->users[] = new User(
            new UserId('8CE05088-ED1F-43E9-A415-3B3792655A9B'), 'John', 'Doe'
        );
        $this->users[] = new User(
            new UserId('62A0CEB4-0403-4AA6-A6CD-1EE808AD4D23'), 'Jean', 'Bon'
        );
    }

    public function find(UserId $userId)
    {
    }

    public function findAll()
    {
        return $this->users;
    }

    public function add(User $user)
    {
    }

    public function remove(User $user)
    {
    }
}

Here is what you should get by running tree src/:

src
└── Acme
    ├── CoreDomain
    │   └── User
    │       ├── User.php
    │       ├── UserId.php
    │       └── UserRepository.php
    └── CoreDomainBundle
        ├── Repository
        │   └── InMemoryUserRepository.php
        └── AcmeCoreDomainBundle.php

The InMemoryUserRepository class is part of what people call the Infrastructure Layer in DDD, and is located into the CoreDomainBundle bundle because it is specific to the application. The Infrastructure Layer contains technical services, persistence, and more generally, concrete implementations of the Domain Layer.

Register a new service named user_repository so that the Application Layer is able to access the UserRepository repository. The Application Layer can be seen as the Controller Layer in a Model-View-Controller architecture. The Application Layer is in charge of coordinating the actions to be performed on the domain, and delegates all domain actions to the domain itself. This layer is kept thin. It does not contain business rules or knowledge. It does not have state reflecting the business situation, but it can have state that reflects the progress of a task for the user or the program.

By the way, you will need to write an Extension class in order to load bundle’s service configuration but I won’t cover that part.

The user_repository service acts as an interface. It is an alias that points to a concrete implementation which is a non-public service:

<!-- src/Acme/CoreDomainBundle/Resources/config/repositories.xml -->
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <parameters>
        <parameter key="user_repository.in_memory.class">Acme\CoreDomainBundle\Repository\InMemoryUserRepository</parameter>
    </parameters>

    <services>
        <!-- Exposed Services -->
        <service id="user_repository" alias="user_repository.in_memory"></service>

        <!-- Concrete Implementations -->
        <service id="user_repository.in_memory" public="false" class="%user_repository.in_memory.class%"></service>
    </services>
</container>

Later when you will choose your persistence layer, you will just have to change the alias to another concrete implementation like user_repository.doctrine for instance, but you won’t have to change your Application Layer code.

The Application Layer

What you have to build is a REST API. The code will live in a bundle named ApiBundle:

src
└── Acme
    ├── ApiBundle
    │   ├── Controller
    │   │   └── UserController.php
    │   ├── Resources
    │   │   └── config
    │   │       └── routing.yml
    │   └── AcmeApiBundle.php
    ├── CoreDomain
    │   └── User
    │       ├── User.php
    │       ├── UserId.php
    │       └── UserRepository.php
    └── CoreDomainBundle
        ├── DependencyInjection
        │   └── AcmeCoreDomainExtension.php
        ├── Repository
        │   └── InMemoryUserRepository.php
        └── AcmeCoreDomainBundle.php

You will need the following dependencies in your composer.json file:

"require": {
    ...

    "friendsofsymfony/rest-bundle": "0.13.*@dev",
    "jms/serializer-bundle": "0.12.*@dev"
}

Don’t forget to register the bundles in the AppKernel class.

For now, you will implement only one action to retrieve all users into your UserController class:

<?php

namespace Acme\ApiBundle\Controller;

use FOS\RestBundle\Controller\Annotations as Rest;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;

class UserController extends Controller
{
    /**
     * @Rest\View
     */
    public function allAction()
    {
        $users = $this->get('user_repository')->findAll();

        return array('users' => $users);
    }
}

There is no black magic here, things won’t work out of the box. Let’s take a look at the configuration. First, you need to add a new route to your routing definition:

# src/Acme/ApiBundle/Resources/config/routing.yml
acme_api.user_all:
  pattern: /users.{_format}
  defaults: { _controller: AcmeApiBundle:User:all, _format: ~ }
  requirements:
    _method: GET

You also need to configure both FOSRestBundle and SensioFrameworkExtraBundle:

# app/config/config.yml
fos_rest:
  view:
    view_response_listener: force
  format_listener:
    default_priorities: ["json", "html", "*/*"]
    fallback_format: json
    prefer_extension: true

sensio_framework_extra:
  view: { annotations: false }

At this time, you should be able to access http://yourproject.local/users, but it should throw an exception saying the Twig template named AcmeApiBundle:User:all.html.twig does not exist. However, if you browse http://yourproject.local/users.json, you should get JSON content containing your users.

Thing is, it is not well serialized. That is because you didn’t configure JMSSerializerBundle yet. First of all, you need to tell the Serializer where to find configuration files:

# app/config/config.yml
jms_serializer:
  metadata:
    directories:
      CoreDomain:
        namespace_prefix: "Acme\\CoreDomain"
        path: "@AcmeApiBundle/Resources/config/serializer/"

The ApiBundle owns the serializer configuration, it is one of its responsibilities. As you can see, I use a YAML configuration file, not annotations, because I don’t want to pollute the agnostic Domain Layer.

Here is the configuration file for the User entity:

# src/Acme/ApiBundle/Resources/config/serializer/User.User.yml
Acme\CoreDomain\User\User:
  exclusion_policy: ALL
  properties:
    id:
      expose: true
      inline: true
    firstName:
      expose: true
      serialized_name: first_name
    lastName:
      expose: true
      serialized_name: last_name

And here is the configuration file for the UserId value object:

# src/Acme/ApiBundle/Resources/config/serializer/User.UserId.yml
Acme\CoreDomain\User\UserId:
  exclusion_policy: ALL
  properties:
    value:
      expose: true
      serialized_name: id

That should give you the following JSON content:

{
  "users": [
    {
      "id": "8CE05088-ED1F-43E9-A415-3B3792655A9B",
      "first_name": "John",
      "last_name": "Doe"
    },
    {
      "id": "62A0CEB4-0403-4AA6-A6CD-1EE808AD4D23",
      "first_name": "Jean",
      "last_name": "Bon"
    }
  ]
}

Running tree src/ on the command line should give you the following output:

src
└── Acme
    ├── ApiBundle
    │   ├── Controller
    │   │   └── UserController.php
    │   ├── Resources
    │   │   ├── config
    │   │   │   ├── routing.yml
    │   │   │   └── serializer
    │   │   │       ├── User.User.yml
    │   │   │       └── User.UserId.yml
    │   │   └── views
    │   │       └── User
    │   │           └── all.html.twig
    │   └── AcmeApiBundle.php
    ├── CoreDomain
    │   └── User
    │       ├── User.php
    │       ├── UserId.php
    │       └── UserRepository.php
    └── CoreDomainBundle
        ├── DependencyInjection
        │   └── AcmeCoreDomainExtension.php
        ├── Repository
        │   └── InMemoryUserRepository.php
        ├── Resources
        │   └── config
        │       └── repositories.xml
        └── AcmeCoreDomainBundle.php

Conclusion

Adopting the right folder structure in your code is important. You should always decouple your code as much as possible. By remembering that a bundle integrates a third-party library or just a set of agnostic classes, you end up with a clean separation between Symfony2 related things, and your business logic.

Bundles that integrate your Domain Layer packages are part of the Infrastructure Layer. Your controllers are part of the Application Layer. The missing layer is the Presentation Layer (UI) which talk to the Application Layer. This layer is responsible for displaying information to the user, and accept new data, but I will cover it in another article.

Source: http://guptavikas.wordpress.com/2009/12/01/domain-driven-design-an-introduction/

By using the Code First approach, you have been able to write a first action that just works. You won’t have to change it. However, you will be able to rely on a database or whatever you want later on. It will be up to you.

In the next blog post, I will ~~introduce the **Presentation Layer**, new Value Objects such as the `Name` one, and more on **DDD**!~~ cover a few points that have been misunderstood.

REST APIs with Symfony2: The Right Way

2012-08-02T00:00:00+00:00

Designing a REST API is not easy. No, really! If you want to design an API the right way, you have to think a lot about everything, and either to be pragmatic or to be an API terrorist. It’s not just about GET, POST, PUT, and DELETE. In real life, you have relations between resources, the need to move a resource somewhere else (think about a tree), or you may want to set a specific value to a resource.

This article will sum up everything I learnt by building different APIs, and how I used Symfony2, the FOSRestBundle, the NelmioApiDocBundle, and Propel. Let’s say we will build a User API.

Do you speak…?

An API is used by clients. They need to know how to talk to your API, and a decent documentation is a good start, and will be described at the end of this article.

Actually, you also need to know how to talk to them too, and in the HTTP protocol, there is something named the Accept header. Basically, your clients will send a header with the format they want to get.

Thanks to the FOSRestBundle, everything is done for you. No need to handle this part yourself, but you have to configure which formats you want to support. Most of the time, you will use JSON, and if you take care of semantic problematics, you will send XML. This part will be described later too.

GET what?

The GET HTTP verb is idempotent. That means whatever you can do, when you get a resource, you get the same response, and nothing should be altered. You will use GET to return resources: either a collection, or a single resource. In Symfony2, the routing definition would be:

# src/Acme/DemoBundle/Resources/config/routing.yml

acme_demo_user_all:
    pattern:  /users
    defaults: { _controller: AcmeDemoBundle:User:all, _format: ~ }
    requirements:
        _method: GET

acme_demo_user_get:
    pattern:  /users/{id}
    defaults: { _controller: AcmeDemoBundle:User:get, _format: ~ }
    requirements:
        _method: GET
        id: "\d+"

The UserController class would contain the following code:

<?php

namespace Acme\DemoBundle\Controller;

use Acme\DemoBundle\Model\User;
use Acme\DemoBundle\Model\UserQuery;
use FOS\RestBundle\Controller\Annotations as Rest;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

class UserController
{
    /**
     * @Rest\View
     */
    public function allAction()
    {
        $users = UserQuery::create()->find();

        return array('users' => $users);
    }

    /**
     * @Rest\View
     */
    public function getAction($id)
    {
        $user = UserQuery::create()->findPk($id);

        if (!$user instanceof User) {
            throw new NotFoundHttpException('User not found');
        }

        return array('user' => $user);
    }
}

Instead of using a ParamConverter, I always use to fetch the object myself in get*() methods. You will know later why, just trust me for the moment, it’s better.

Status code matter for your clients, so if the user doesn’t exist, use a NotFoundHttpException exception which returns a response with a 404 status code.

By using the View annotation, you will render the user object using the right format according to the user Accept header. Using an alias (Rest) for this annotation is a trick to avoid confusion with the View object we will discover later. Basically, the annotation relies on this class. It’s just a matter of taste whether you like annotations or not.

Last thing, the allAction() method has the same behavior, you fetch all your users, and then you return them.

A user has four properties: an id, an email, a username and a password. You probably don’t want to expose the password for some good reasons. The easiest way to achieve that is to configure the serializer. I use to configure it in YAML:

# In Propel, the most part of the code is located in base classes
# src/Acme/DemoBundle/Resources/config/serializer/Model.om.BaseUser.yml
Acme\DemoBundle\Model\om\BaseUser:
  exclusion_policy: ALL
  properties:
    id:
      expose: true
    username:
      expose: true
    email:
      expose: true

I exclude all properties by default, it allows me more control on what I really want to expose. It doesn’t matter with four attributes, but it’s always better to adopt this strategy, it’s like configuring a firewall after all.

Basically, you will get the following JSON response:

{
  "user": {
    "id": 999,
    "username": "xxxx",
    "email": "xxxx@example.org"
  }
}

Easy right? But, you will probably need to create, update, or delete your users, and that’s what we will discover in the next sections.

POST ‘it

Creating a resource implies the use of the POST HTTP verb. But how do you get data? How do you validate data? And how do you create your new resource? These three questions have more than one answer or strategy.

You could use the deserialization mechanism to create an object from the input serialized data. There is an interesting work in progress by @beberlei about Form deserialization. It’s a bit different than just using the Serializer component but it seems easier.

I use to use the awesome Symfony Forms to do everything at once. So let’s write a Form type to create our users. Using the PropelBundle, you could use the propel:form:generate command:

php app/console propel:form:generate @AcmeDemoBundle User

It will create the following form type:

<?php

namespace Acme\DemoBundle\Form\Type;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolverInterface;

class UserType extends AbstractType
{
    /**
     * {@inheritdoc}
     */
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder->add('username');
        $builder->add('email', 'email');
        $builder->add('password', 'password');
    }

    /**
     * {@inheritdoc}
     */
    public function setDefaultOptions(OptionsResolverInterface $resolver)
    {
        $resolver->setDefaults(array(
            'data_class'        => 'Acme\DemoBundle\Model\User',
            'csrf_protection'   => false,
        ));
    }

    /**
     * {@inheritdoc}
     */
    public function getName()
    {
        return 'user';
    }
}

The only things I tweaked are the email and password types, and I disabled the CSRF protection. In a REST API, you probably use an security layer like OAuth for example. Having a CSRF protection in a REST context doesn’t make sense.

Now, you want to add validation rules, and thanks to the Validator component, it’s really powerful. I definitely love this component because it becomes simple to validate all data you want in a safe way.

Back to our use case, I use to define my validation rules in YAML, but feel free to use your preferred way. Here is an example:

# src/Acme/DemoBundle/Resources/config/validation.yml
Acme\DemoBundle\Model\User:
  getters:
    username:
      - NotBlank:
    email:
      - NotBlank:
      - Email:
    password:
      - NotBlank:

Let’s write the controller method now:

<?php

// ...

    public function newAction()
    {
        return $this->processForm(new User());
    }

New tip, always use a method to process your form. You will thank yourself. The processForm() method looks like:

<?php

// ...

    private function processForm(User $user)
    {
        $statusCode = $user->isNew() ? 201 : 204;

        $form = $this->createForm(new UserType(), $user);
        $form->handleRequest($this->getRequest());

        if ($form->isValid()) {
            $user->save();

            $response = new Response();
            $response->setStatusCode($statusCode);

            // set the `Location` header only when creating new resources
            if (201 === $statusCode) {
                $response->headers->set('Location',
                    $this->generateUrl(
                        'acme_demo_user_get', array('id' => $user->getId()),
                        true // absolute
                    )
                );
            }

            return $response;
        }

        return View::create($form, 400);
    }

Basically, you create a form, you bind input data, if everything is valid, you save your user, and you return a response. If something went wrong, you return a 400 status code with the form. The $form instance will be serialized to highlight invalid input data. For example, you could get the following error response:

{
  "code": 400,
  "message": "Validation Failed";
  "errors": {
    "children": {
      "username": {
        "errors": [
          "This value should not be blank."
        ]
      }
    }
  }
}

Note that the View class here is not the same as the annotation one, that’s why I used an alias earlier. Read more about this class in The View Layer chapter in the FOSRestBundle documentation.

Also, passing the form name is important here. Basically, your clients will send the following content:

{
  "user": {
    "username": "foo",
    "email": "foo@example.org",
    "password": "hahaha"
  }
}

You can try this API method with curl:

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X
POST -d '{"user":{"username":"foo", "email": "foo@example.org", "password":
"hahaha"}}' http://example.com/users

Make sure to set the body_listener parameter to true in the FOSRestBundle configuration. It allows you to receive data in JSON, XML, etc. Then again, everything works out of the box.

As I said previously, when everything is ok, you persist the user ($user->save() in Propel), and then you return a response.

You will return a 201 status code which means resource created. Note that I don’t use the View annotation here.

But if you read the code, you may think that I did weird stuff. Actually, once a resource is created, you have to return only one information: how to access this resource, in other words, its URI. The HTTP specification says you should use the Location header, and that’s what I do here. But, most of the time you don’t want to perform a new request to get information like the id of the user (you already have other information anyway). Here is the beginning of my main concern: pragmatic vs terrorist?

Guess what? I use to be terrorist here, and I follow the specification by returning just the Location header:

Location: http://example.com/users/999

When I have a JavaScript framework like Backbone.js as client, and because I don’t want to rewrite it entirely because it doesn’t support right APIs, I return the id in addition. Being pragmatic is not a bad idea anyway.

Don’t forget to add the routing definition for this action. Creating a resource is a POST request to the collection, so let’s add a new route:

acme_demo_user_new:
  pattern: /users
  defaults: { _controller: AcmeDemoBundle:User:new, _format: ~ }
  requirements:
    _method: POST

Once you know how to create a new resource, it’s quite easy to update it.

PUT vs PATCH, fight!

Updating a resource in REST means replacing it actually, especially if you use the PUT HTTP verb. There is also the PATCH method which takes a diff as input and applies a patch to your resource, in other words, it’s a partial update.

Thanks to our previous work, updating a resource will be quickly implemented. You have to write a new method in your controller, and to add a new route. Here, I rely on a ParamConverter to fetch the User object. If it doesn’t exist, the converter will throw an exception and this exception will be converted in a response with a 404 status code.

<?php

// ...

    public function editAction(User $user)
    {
        return $this->processForm($user);
    }

Editing a resource means you know it, so you will perform a PUT request on this resource:

acme_demo_user_edit:
  pattern: /users/{id}
  defaults: { _controller: AcmeDemoBundle:User:edit, _format: ~ }
  requirements:
    _method: PUT

Both PUT and PATCH methods have to return a 204 status code standing for No Content, and meaning everything is ok, go ahead. In the context of this blog post, PUT is exclusively used to update existing resources, not to create new ones. That is why you have to return a 204 status code.

If you want to create new resources at a given URI, then you will have to update the code above by removing the use of a ParamConverter, and create a new user in case it does not exist:

<?php

// ...

    public function editAction($id)
    {
        if (null === $user = UserQuery::create()->findPk($id)) {
            $user = new User();
            $user->setId($id);
        }

        return $this->processForm($user);
    }

In this case, your method can return either 204 if the resource exists or 201 with a Location header if a new resource has been created.

That’s it! What about deleting resources now?

DELETE

Deleting a resource is super easy. Add a new route:

acme_demo_user_delete:
  pattern: /users/{id}
  defaults: { _controller: AcmeDemoBundle:User:remove, _format: ~ }
  requirements:
    _method: DELETE

And, write a short method:

<?php

// ...

    /**
     * @Rest\View(statusCode=204)
     */
    public function removeAction(User $user)
    {
        $user->delete();
    }

In a few lines of code, you have a fully working API that exposes CRUD operations in a safe way. But now, what about adding relationship between users, like friendship?

How to retrieve the friends for a given user in REST? We just have to consider friends as a collection of users owned by the user. Let’s implement that.

The Friendship Algorithm

First, we have to create a new route. As we consider the friends as a collection owned by a user, we will fetch this collection directly on a resource:

acme_demo_user_get_friends:
  pattern: /users/{id}/friends
  defaults: { _controller: AcmeDemoBundle:User:getFriends, _format: ~ }
  requirements:
    _method: GET

The action in the controller looks like:

<?php

// ...

    public function getFriendsAction(User $user)
    {
        return array('friends' => $user->getFriends());
    }

That’s it. Now, think about how to represent the process of becoming friend with another user. How would you manage that in a REST approach? You can’t use POST to the collection of friends as you won’t create anything Both users already exist. You can’t use PUT as you don’t really want to replace the whole collection, and it seems a bit harsh.

Well, the HTTP procotol describes a LINK HTTP verb that solves this problem. It says:

The LINK method establishes one or more Link relationships between the existing resource identified by the Request-URI and other existing resources.

That’s exactly what we need. We want to link two resources, we should never forget resources while we build APIs. So, how to do that in Symfony2?

My approach is to rely on a request listener here. The client will perform a LINK request on a resource, and will send at least one Link header:

LINK /users/1
Link: <http://example.com/users/2>; rel="friend"
Link: <http://example.com/users/3>; rel="friend"

Using a request listener is a nice option because it allows you to have clean inputs in your action. The aim of this action is to link objects after all, we don’t want to play with URIs in the controller. The transformation has to be done before.

The request listener gets those Link headers, and uses the RouterMatcher part of Symfony2 to retrieve the controller and the method names. It also gets the parameters.

In other words, it has all information to create a controller, and to call the right method on it with the right parameters. In our example, for each Link header, it calls the getUser() action on the UserController controller. That’s why I didn’t use ParamConverters, it allows me to pass the id value, and to get my resource. I make two assumptions:

if the user doesn’t exist, I will get an exception;
I will get an array as returned value because I use the View annotation.

Once I get my resource objects, I put them in the request’s attributes, and that’s all for the listener. Here is the code:

<?php

namespace Acme\DemoBundle\EventListener;

use Symfony\Component\HttpKernel\Event\GetResponseEvent;
use Symfony\Component\HttpKernel\Controller\ControllerResolverInterface;
use Symfony\Component\Routing\Matcher\UrlMatcherInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpKernel\HttpKernelInterface;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\HttpKernel\Event\FilterControllerEvent;

class LinkRequestListener
{
    /**
     * @var ControllerResolverInterface
     */
    private $resolver;
    private $urlMatcher;

    /**
     * @param ControllerResolverInterface $controllerResolver The 'controller_resolver' service
     * @param UrlMatcherInterface         $urlMatcher         The 'router' service
     */
    public function __construct(ControllerResolverInterface $controllerResolver, UrlMatcherInterface $urlMatcher)
    {
        $this->resolver = $controllerResolver;
        $this->urlMatcher = $urlMatcher;
    }

    public function onKernelRequest(GetResponseEvent $event)
    {
        if (!$event->getRequest()->headers->has('link')) {
            return;
        }

        $links  = array();
        $header = $event->getRequest()->headers->get('link');

        /*
         * Due to limitations, multiple same-name headers are sent as comma
         * separated values.
         *
         * This breaks those headers into Link headers following the format
         * http://tools.ietf.org/html/rfc2068#section-19.6.2.4
         */
        while (preg_match('/^((?:[^"]|"[^"]*")*?),/', $header, $matches)) {
            $header  = trim(substr($header, strlen($matches[0])));
            $links[] = $matches[1];
        }

        if ($header) {
            $links[] = $header;
        }

        $requestMethod = $this->urlMatcher->getContext()->getMethod();
        // Force the GET method to avoid the use of the
        // previous method (LINK/UNLINK)
        $this->urlMatcher->getContext()->setMethod('GET');

        // The controller resolver needs a request to resolve the controller.
        $stubRequest = new Request();

        foreach ($links as $idx => $link) {
            $linkParams = explode(';', trim($link));
            $resource   = array_shift($linkParams);
            $resource   = preg_replace('/<|>/', '', $resource);

            try {
                $route = $this->urlMatcher->match($resource);
            } catch (\Exception $e) {
                // If we don't have a matching route we return
                // the original Link header
                continue;
            }

            $stubRequest->attributes->replace($route);

            if (false === $controller = $this->resolver->getController($stubRequest)) {
                continue;
            }

            // Make sure @ParamConverter and friends are handled
            $subEvent = new FilterControllerEvent($event->getKernel(), $controller, $stubRequest, HttpKernelInterface::MASTER_REQUEST);
            $event->getDispatcher()->dispatch(KernelEvents::CONTROLLER, $subEvent);
            $controller = $subEvent->getController();

            $arguments = $this->resolver->getArguments($stubRequest, $controller);

            try {
                $result = call_user_func_array($controller, $arguments);

                // By convention the controller action must return an array
                if (!is_array($result)) {
                    continue;
                }

                // The key of first item is discarded
                $links[$idx] = current($result);
            } catch (\Exception $e) {
                continue;
            }
        }

        $event->getRequest()->attributes->set('links', $links);
        $this->urlMatcher->getContext()->setMethod($requestMethod);
    }
}

Now, you can create a new route:

acme_demo_user_link:
  pattern: /users/{id}
  defaults: { _controller: AcmeDemoBundle:User:link, _format: ~ }
  requirements:
    _method: LINK

And the code of the action looks like:

<?php

// ...

    /**
     * @Rest\View(statusCode=204)
     */
    public function linkAction(User $user, Request $request)
    {
        if (!$request->attributes->has('links')) {
            throw new HttpException(400);
        }

        foreach ($request->attributes->get('links') as $u) {
            if (!$u instanceof User) {
                throw new NotFoundHttpException('Invalid resource');
            }

            if ($user->hasFriend($u)) {
                throw new HttpException(409, 'Users are already friends');
            }

            $user->addFriend($u);
        }

        $user->save();
    }

If users are already friends, you will get a response with a 409 status code which means Conflict. If there is no link header, it’s a bad request (400).

And it would be the same thing to remove friends. There is a UNLINK HTTP verb too.

Last thing I didn’t explain is the PATCH verb, I mean what would be a use case for such a verb? The answer is partial update or every other methods that are either not safe, unsure or not idempotent. If you have a custom API method, and you don’t know which verb to use, PATCH is probably the answer.

Assuming you allow your users to change their email thanks to a third party client, then again it’s for some good business reasons. This client uses a two steps process. The user asks for changing his email, he gets an email with a link and this link allows him to change his email. Let’s skip the first part and focus on the second one. The user sends a new password to the client, and the client has to call your API. Either this client will fetch the resource, and replace it or you are smart and you provide a PATCH method.

Let’s PATCH the world

This section has been removed as it described a wrong way to use the PATCH method. You can read this: Please. Don’t Patch Like An Idiot.. It covers how to update user’s email, using the PATCH method the right way, but not in PHP unfortunately.

So now, what’s the plan? We use GET, POST, PUT, DELETE, LINK, and UNLINK verbs. We are able to create, read, update, delete a user. We can get all users, and add relationships between them.

Actually, regarding the Richardson Maturity Model, we just covered the level 2. Let’s take a look at HATEOAS and unlock the level 3!

Hate who?

HATEOAS is not about hating people, but you could hate this movement if you are a true pragmatic programmer. It basically means Hypermedia As The Engine Of Application State. To me, it looks like a semantic dimension you bring into your APIs.

Earlier in this article I talked about the format used to exchange information between a client and your API. JSON is not the best choice when you want to follow HATEOAS principles even if some people tried to provide solutions.

Let’s convert our User representation in XML:

<user>
    <id>999</id>
    <username>xxxx</username>
    <email>xxxx@example.org</email>
</user>

This is the output you could get by requesting the XML format as a client. There is nothing HATEOAS here. The first step is the addition of links:

<user>
    <id>999</id>
    <username>xxxx</username>
    <email>xxxx@example.org</email>

    <link href="http://example.com/users/999" rel="self" />
</user>

This was easy, we just added the link that references the user you fetched. But if you get a paginate collection of users, you could get:

<users>
    <user>
        <id>999</id>
        <username>xxxx</username>
        <email>xxxx@example.org</email>

        <link href="http://example.com/users/999" rel="self" />
        <link href="http://example.com/users/999/friends" rel="friends" />
    </user>
    <user>
        <id>123</id>
        <username>foobar</username>
        <email>foobar@example.org</email>

        <link href="http://example.com/users/123" rel="self" />
        <link href="http://example.com/users/123/friends" rel="friends" />
    </user>

    <link href="http://example.com/users?page=1" rel="prev" />
    <link href="http://example.com/users?page=2" rel="self" />
    <link href="http://example.com/users?page=3" rel="next" />
</users>

Now the client knows how to browse the collection, how to use the pager, and how to fetch a user and/or its friends.

The second part is about adding media types to answer the question: What?. What is this resource? What does it contain or what do I need to create such a resource?

This part introduces your own content type:

Content-Type: application/vnd.yourname.something+xml

Our users will now have the following content type: application/vnd.acme.user+xml.

<user>
    <id>999</id>
    <username>xxxx</username>
    <email>xxxx@example.org</email>

    <link href="http://example.com/users/999" rel="self" />

    <link rel="friends"
          type="application/vnd.acme.user+xml"
          href="http://example.com/users/999/friends" />
</user>

Last, but not the least, you can add versioning to your API in three different ways. First, you can add the version number in your URIs, this is the easy way:

/api/v1/users

You can use your new content type:

application/vnd.acme.user-v1+xml

Or you can also use a qualifier in your Accept header, that way you don’t touch your content type:

application/vnd.acme.user+xml;v=1

It’s really up to you. The first solution is easy but less RESTful than the two other solutions. But those solutions require more smart clients.

Testing

To be honest, if you decide to expose your API to your customers, this section is the most important. You can decide to follow the REST approach or not, but your API has to work perfectly, and that means well tested.

I use to test APIs I build with functional tests, that means I consider the system as a black box. Symfony2 embeds a nice Client which allows you to call your API methods directly in your test classes:

<?php

$client   = static::createClient();
$crawler  = $client->request('GET', '/users');

$response = $crawler->getResponse();

$this->assertJsonResponse($response, 200);

I use to use my own WebTestCase class with a assertJsonResponse() method:

<?php

// ...

    protected function assertJsonResponse($response, $statusCode = 200)
    {
        $this->assertEquals(
            $statusCode, $response->getStatusCode(),
            $response->getContent()
        );
        $this->assertTrue(
            $response->headers->contains('Content-Type', 'application/json'),
            $response->headers
        );
    }

This is the first check I do after a call to the API. If it’s ok, then I can make more assertions related to the content I fetched.

When you write tests for your APIs, test everything you can think about. Don’t forget to test bad requests, and to have at least one test method for each status code you can return. It’s important because, even if there is a problem, you have to return the right status code, and the right message to the clients. A 500 status code doesn’t have the same meaning than a 400.

Documentation

Having a well documented API is really important, because it’s the only thing your clients will have access to. You don’t provide the entire code to them, there is just an endpoint and documentation.

In a HATEOAS approach, your API is auto documented, so you don’t need to write the documentation yourself, because your clients will discover features themselves.

But then again, having a HATEOAS API is quite complex, and it’s not so widespread nowadays. If your API follows the level 2 of the Richardson’s model, it’s already good, but you will have to write the documentation yourself!

NelmioApiDocBundle to the rescue! I wrote this bundle at Nelmio in order to automatically generate documentation for our APIs. Based on code introspection, the bundle extracts a lot of information, and displays a nice page with all information found.

You now have all keys to build wonderful APIs!

Useful Links

I will probably update this post with more information, links, etc. So stay tuned!

Introduction to Propel2 at Symfony Live 2012

2012-06-08T00:00:00+00:00

Here are my slides for the talk I gave this morning at Symfony Live 2012 in Paris.

If you attended this conference, please leave a feedback on joind.in. Cheers!

Geocoder: the missing PHP library

2012-05-31T00:00:00+00:00

Seven months ago, I released Geocoder, a PHP 5.3+ library to ease geocoding manipulations. More and more applications have to deal with geolocation and, even if HTML5 provides a Geolocation API, a server-side library is always useful. Today, this library has more than 230 watchers on GitHub and it’s time to introduce it here.

The library is standalone and split in two parts: HttpAdapters, which are responsible for getting data from remote APIs, and Providers, which own the logic to extract information.

Adapters

There are many adapters to use Geocoder with, like Buzz, cURL, Guzzle and the Zend Http Client. If you want to use another HTTP layer, you can easily write your own provider by implementing the HttpAdapterInterface interface.

Providers

The most important part of Geocoder is probably all its providers: FreeGeoIp, HostIp, IpInfoDB, Yahoo! PlaceFinder, Google Maps, Bing Maps, OpenStreetMaps, CloudMade, and even Geoip, the PHP extension. Same thing here, you can easily write your own provider by implementing the ProviderInterface interface.

Geocoder supports both geocoding and reverse geocoding. It depends on the provider you choose and also what you want to do. The API is really simple:

<?php

$geocoder = new \Geocoder\Geocoder();
$adapter  = new \Geocoder\HttpAdapter\BuzzHttpAdapter();

$geocoder->registerProviders(array(
    new \Geocoder\Provider\YahooProvider($adapter, 'API_KEY'),
));

// IP based
$result = $geocoder->geocode('88.188.221.14');

// Street address based
$result = $geocoder->geocode('10 rue Gambetta, Paris, France');

// reverse geocoding
$result = $geocoder->reverse($latitude, $longitude);

The $result variable is an instance of ResultInterface. Again, the API is simple.

Dumpers

Another feature provided by Geocoder is the ability to dump a ResultInterface object in standard formats like GPS eXchange (GPX), GeoJSON, Keyhole Markup Language (KML), Well-Known Binary (WKB) or Well-Known Text (WKT). This is too small to become a separated library and it can be helpful if you need to share geolocated data.

Conclusion

Geocoder is quite stable now. It is well integrated with Propel thanks to the GeocodableBehavior and with Doctrine thanks to the DoctrineBehaviors. Both behaviors are really powerful. Install them and your model objects (entities) become geo-aware! For Drupal folks, the geocoder module should use Geocoder sooner or later.

Geocoder has more than ten contributors (thank you so much!!!). It is actively maintained and already used in production! Oh and it’s well unit tested, with more than a hundred tests and almost a thousand assertions!

If you plan to deal with geocoding stuff in your PHP project, you should give Geocoder a try ;)

Propel and Symfony: a year ago

2012-04-25T00:00:00+00:00

Did you know that the PropelBundle was part of the Symfony core? Yes, at the very beginning. It was moved out some time after. Basically, I didn’t create the PropelBundle but I started to learn Symfony by using it.

Hi,

You seem to work on the PropelBundle actively, and that’s great news. This bundle is under my account right now because it is orphan. But if you want to take care of the maintenance of it, then I think it’s time for your fork to become the official repository for the bundle. What do you think?

Fabien

To be honest, this bundle didn’t really work and I spent a fair amount of time to learn Symfony internals, learn Propel 1.6 internals and find ways to make this bundle work 😅 It was fun! After a few weeks, the bundle became useful and, at the same time, I joined e-TF1 where I had the opportunity to work with both Symfony and Propel. I could use this bundle in production!

A few months later, I accepted to take the lead of the Propel project and I added the PropelBundle as an official Propel project. It was the best choice because people helped me a lot to improve this bundle, and now it is fully compatible with Symfony (kudos to Toni who is the PropelBundle manager). To spread the word, I also wrote exhaustive documentation about Propel and Symfony.

Making this bundle reliable and trustful was the hardest part of the work. Even if the bundle worked great and even if we were there to answer questions or to fix issues, it was tricky to get more users. That’s why I asked Fabien to create a Propel Bridge in Symfony. It was the first step to avoid comments like “it’s not the default ORM, lalala”. At the same time, Symfony took the decision to be a View Controller framework without any Model layer bundled by default.

Today, I’m proud to announce that the last step has been unlocked thanks to Joseph. Propel has its own chapter in the official Symfony book, which means you have to think about which Model layer to use now. There is no more excuse to not try Propel in Symfony or to use Doctrine by default and not by choice.

Try Propel, seriously! It could fit your needs depending on what you expect. Some great bundles already support Propel (like the FOSUserBundle). Also please avoid comments like “Doctrine is much nicer”, which make little sense. Why is it much nicer? I never got any good arguments in favor of Doctrine I didn’t already know. I can hear everything that is constructive. I used Doctrine for more than six months, both ORM and ODM (MongoDB). I have strong arguments against it but I also like some parts of it. Who can say the same thing about Propel?

Now, you have the choice. It’s up to you. Thanks!

Component Driven Development: it's like Lego!

2012-02-01T00:00:00+00:00

Did you ever hear about Component-Based Development? Maybe about Component Driven Development? Both concepts are the same, and if you’ve worked with Symfony, Spring or similar frameworks, then chances are you’ve already done Component Driven Development (CDD).

It’s all about separation of concerns. You design components with their own logic. Each component does one thing well and only one thing (that is also the Unix philosophy). Separating business logic in self-contained components requires to focus on interactions between components. In other words, you have to think in terms of interfaces and boundaries.

UML provides a component diagram that allows you to easily identify the components, interfaces and their relations. This could be a useful tool. In a UML component diagram, a provided interface is modeled using the lollipop notation and a required interface is modeled using the socket notation.

Simplified example of a UML component diagram

As I wrote previously, you are most likely already familiar with Component Driven Development if you know Symfony or Spring. Why? Because these two frameworks use the Inversion of Control (IoC) architectural pattern via the Dependency Injection design pattern (I consider IoC an architectural pattern because it’s not a design pattern you can implement).

There are two known issues with IoC, though. First, you need a way to manage dependencies between components. Second, how do you instantiate all these components (in which order for instance)? Dependency Injection Container (DIC) to the rescue! A (service) container requires some configuration that essentially describes the dependencies between components. Checkout the Symfony docs about Dependency Injection for more technical information.

With that, the two issues I just mentioned are solved and you can now write highly decoupled code. The main drawback is the time you’ll have to spend thinking about your architecture and component interactions. This is where the UML component diagram can be helpful ;-)

Thanks to a framework that provides abstractions such as a DIC, you can start “assembling” an app by reusing existing components (i.e. libraries) to avoid writing everything from scratch. See why it is like Lego now?

In the PHP world, we have magic tools like:

The Symfony components: a reusable set of standalone PHP components
Composer: the awesome package manager for PHP
Packagist: the official registry to discover great PHP libraries

Less time wasted writing “framework code”, more time spent writing business-oriented code and “glue code” for the existing components you use directly “as-is”, yay!

PHP // William Durand

[Video] Software testing: past, present, future

[Video] REST dans le monde Symfony

RESTing with Symfony: SOS

Enforcing Data Encapsulation with Symfony Forms

DDD with Symfony2: Basic Persistence & Testing

The YamlUserRepository Repository

Unit Testing

Functional Testing

Conclusion

Taking Geocoder to the next level

DDD with Symfony2: Making Things Clear

DDD Is Not RAD

There Is No Database

DDD And REST

So, What’s Next?

DDD with Symfony2: Folder Structure And Code First

Bootstrap

Folder Structure

Code First

The Infrastructure Layer

The Application Layer

Conclusion

REST APIs with Symfony2: The Right Way

Do you speak…?

GET what?

POST ‘it

PUT vs PATCH, fight!

DELETE

The Friendship Algorithm

Let’s PATCH the world

Hate who?

Testing

Documentation

Useful Links

Introduction to Propel2 at Symfony Live 2012

Geocoder: the missing PHP library

Adapters

Providers

Dumpers

Conclusion

Links

Propel and Symfony: a year ago

Component Driven Development: it's like Lego!

The `YamlUserRepository` Repository