Moderniser une application PHP Zend Framework 1 avec le conteneur de dépendances de Symfony2

Composer est l'outil PHP moderne pour installer des bibliothèques PHP tierces. De manière standard, les dépendances se placent dans le répertoire /vendor du projet et Composer génère automatiquement un fichier d'autoload qui permet de charger les dépendances aisément dans votre projet PHP.

Outre les dépendances installables depuis la plateforme Packagist, Composer peut aussi gérer l'autoload de vos propres classes.

Composer se présente sous la forme d'une archive phar, à télécharger et placer où vous voulez, classiquement à la racine du projet. Ce fichier composer.phar ne devra bien sûr pas être versionné.

L'outil est utilisable en ligne de commande, installer un nouveau composant dans un projet PHP se résume donc bien souvent à cette simple commande :

php composer.phar require author/component

On suit la logique des namespaces PHP, où chaque composant doit avoir le nom de son auteur et le nom du composant dans son namespace.

Des options plus poussées sont bien entendu possibles, par exemple pour installer une version spécifique d'un composant. Pour cela, consultez la documentation de Composer sur le site officiel : https://getcomposer.org/doc/.

Composer va créer un fichier composer.lock contenant des informations internes à l'outil pour connaître la structure des paquets installés, et un fichier composer.json contenant la liste des dépendances installées. Ces deux fichiers doivent être commités. Lors de chaque instruction Composer, un fichier vendor/autoload.php sera aussi créé (la première fois) ou mis à jour avec les instructions d'autoload pour le nouveau composant.

La seule adaptation de notre application ZF1 sera donc d'intégrer l'autoload généré par Composer au démarrage. On commence par ajouter une constante ROOT_PATH représentant comme son nom l'indique le chemin absolu vers la racine de notre projet, en ajoutant ce bout de code au tout début du fichier public/index.php (c'est facultatif, mais je trouve cette constante pratique) :

if (!defined('ROOT_PATH')) {
    define('ROOT_PATH', realpath(__DIR__ . '/..'));
}

Ensuite dans le bootstrap de l'application, on ajoute la ligne suivante au tout début pour charger le fichier autoload généré par Composer :

require_once ROOT_PATH . '/vendor/autoload.php';

Et c'est tout ! Les dépendances Composer seront maintenant utilisables dans notre projet.

C'est le composant principal, si vous ne deviez en choisir qu'un, ce serait celui-ci ! C'est en effet la pierre angulaire de tout développement PHP moderne, le chargement des autres composants passera par lui.

L'installation est très simple avec Composer, et on va d'ailleurs installer en même temps le composant Symfony Config qui va nous permettre de charger la configuration des services dans différents formats (xml, yml, php) :

php composer.phar require symfony/dependency-injection
php composer.phar require symfony/config

L'utiliser dans notre projet ZF1 va demander un peu de travail. En fait, ZF1 possède déjà un conteneur de services, qui n'est autre que Zend_Application_Bootstrap, matérialisé par le fichier application/Bootstrap.php. Pour initialiser un service à la manière ZF1, appelé d'ailleurs « ressource », il faut créer une méthode _initMonService() qui doit retourner une instance de la classe de service. Cela présente l'inconvénient notoire de charger tous les services au démarrage, alors qu'ils ne seront pas nécessairement utilisés à chaque requête. De plus, la récupération des services est plutôt lourde puisqu'il faut chaque fois récupérer le singleton du contrôleur frontal pour récupérer le bootstrap, et enfin le service.

Nous allons néanmoins nous servir du Bootstrap ZF pour y stocker un seul service : le conteneur d'injection de dépendances de Symfony2 ! Et pour accéder à nos services facilement depuis les contrôleurs, nous réaliserons un petit plugin d'action.

IV-B-1. Autoload des services▲

- library
    - Zend (le framework lui-même, comme dans toute appli ZF1)
    - App (c'est ici que nous allons placer nos classes)
        - Application
        - Domain
            - Entity
                - Proxy
            - Repository
            - ValueObject
            - Service
        - Infra

"autoload": {
    "psr-0": {
        "App\\": "library/"
    }
}

php composer.phar dump-autoload

IV-B-2. Intégration du conteneur de services▲

pluginPaths.My_Resource = APPLICATION_PATH "/resources"
resources.dic.configfile = APPLICATION_PATH "/configs/services.yml"

<?php
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\Config\FileLocator;
use Symfony\Component\DependencyInjection\Loader\YamlFileLoader;
use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
use Symfony\Component\DependencyInjection\Loader\PhpFileLoader;

class My_Resource_Dic extends Zend_Application_Resource_ResourceAbstract
{
    /**
     * Initialise le conteneur d'injection de dépendances de Symfony
     * et le mémorise dans le container du bootstrap Zend
     * @return \Symfony\Component\DependencyInjection\ContainerBuilder
     */
    public function init()
    {
        $options = $this->getOptions();
        $container = new ContainerBuilder();
        // charge le fichier de définition des services suivant son format
        $configFile = basename($options['configfile']);
        $extension = substr($configFile, strrpos($configFile, "."));
        switch ($extension) {
            case '.yml':
                $loader = new YamlFileLoader($container, new FileLocator(dirname($options['configfile'])));
                break;
            case '.xml':
                $loader = new XmlFileLoader($container, new FileLocator(dirname($options['configfile'])));
                break;
            case '.php':
                $loader = new PhpFileLoader($container, new FileLocator(dirname($options['configfile'])));
                break;
            default: throw new Exception("DIC services config file format not supported");
        }
        $loader->load($configFile);
        
        // ajoute tous les paramètres définis dans resources.dic.params
        $this->_addContainerParameters($container, $options['params']);
        
        // indispensable pour l'héritage de services, merci stackoverflow !
        // http://stackoverflow.com/questions/11415998/symfony2-dependency-injection-with-parent-services-does-not-work
        $container->compile();
        return $container;
    }
    
    /**
     * Ajoute un ou plusieurs paramètres au container d'injection de dépendances. Si la valeur du paramètre
     * est un array on va le parcourir pour obtenir un nom de paramètre toto.titi.tata
     * @param ContainerBuilder $container
     * @param array|string $value
     * @param string $name
     */
    protected function _addContainerParameters(ContainerBuilder $container, $value, $name = null)
    {
        // si la valeur est un array, on parcourt tous ses éléments en construisant le nom du paramètre
        // en concaténant les clés avec un .
        if (is_array($value)) {
            foreach ($value as $key => $val) {
                $paramName = $key;
                if (!empty($name)) {
                    $paramName = $name . "." . $paramName;
                }
                $this->_addContainerParameters($container, $val, $paramName);
            }
        // la valeur n'est pas un array, donc on a fini de récurser, on peut ajouter le paramètre
        } else {
            $container->setParameter($name, $value);
        }
    }
}

    protected function _initMonService()
    {
        //$monService = new ...
        $this->bootstrap('dic');  // s'assure que le DIC est initialisé
        $this->getResource('dic')->set('mon.service', $monService);
    }

services:
    em:
        synthetic: true
        
    log:
        synthetic: true
        
    config:
        synthetic: true    
    
    domain.service.abstract:
        abstract: true
        arguments: ['@em']
        calls:
            - [setLog, ['@log']]
    
    domain.service.exemple:
        class: App\Domain\Service\Exemple
        parent: domain.service.abstract

    infra.ldap:
        class: App\Infra\Ldap\Ldap
        arguments: 
            - '%auth.ldap.host%'
            - '%auth.ldap.port%'
            - '%auth.ldap.username%'
            - '%auth.ldap.password%'
            - '%auth.ldap.dn%'

IV-B-3. Accéder aux services depuis le contrôleur avec un helper▲

resources.frontController.actionHelperPaths.Zend_Controller_Action_Helper = APPLICATION_PATH "/helpers/action"

<?php
/**
 * Helper d'action permettant d'accéder facilement au conteneur d'injection de dépendances
 * depuis les contrôleurs de l'application.
 *
 */
class Zend_Controller_Action_Helper_Dic extends Zend_Controller_Action_Helper_Abstract
{
    /**
     * Stocke l'instance du conteneur d'injection de dépendances
     * @var \Symfony\Component\DependencyInjection\ContainerBuilder
     */
    protected $_container;
    
    /**
     * Récupère le conteneur d'injection de dépendances depuis le boostrap et le mémorise dans l'objet
     */
    public function init()
    {
        $this->_container = $this->getFrontController()->getParam('bootstrap')->getResource('dic');
    }
    
    /**
     * Retourne le conteneur d'injection de dépendances pour pouvoir lui appliquer ses méthodes
     * @return \Symfony\Component\DependencyInjection\ContainerBuilder
     */
    public function direct()
    {
        return $this->_container;
    }
}

$serviceDoc = $this->_helper->dic()->get('domain.service.document');

Zend Framework dispose de classes pour s'interfacer avec les bases de données, utilisant le design pattern Table Data Gateway. En gros, on crée une classe par table qui décrit la structure de chaque table (colonnes, associations… ) et qui hérite d'une classe de base contenant les méthodes d'accès à la base de données.

Doctrine 2 quant à lui est un ORM plus puissant, c'est l'équivalent en PHP de Hibernate du monde Java, utilisant le design pattern Data Mapper. Les entités (classes table sous ZF) sont cette fois indépendantes (objets purs, ne devant hériter d'aucune classe de base), toutes les opérations de base de données s'effectuant depuis un objet « entity manager » (équivalent de la « session » Hibernate). Je n'entrerai pas dans les détails sur l'intérêt de cet ORM, encore une fois cela sort du cadre de cet article.

Son intégration dans un projet ZF1 nécessitera, outre l'installation par Composer, d'instancier l'objet « entity manager », qui est l'objet central permettant d'accéder à tous les objets de l'ORM. S'agissant d'un composant complexe, son initialisation va nécessiter un peu de code, raison pour laquelle nous l'ajouterons en tant que service synthétique au conteneur de services Symfony2.

Tout d'abord, installons la bibliothèque :

php composer.phar require doctrine/orm

Ensuite, créez la classe de ressource de boostrap suivante :

<?php
use Doctrine\ORM\Configuration;
use Doctrine\ORM\EntityManager;
use Doctrine\Common\Annotations\AnnotationRegistry;
use Doctrine\Common\Annotations\AnnotationReader;
use Doctrine\ORM\Mapping\Driver\AnnotationDriver;

class My_Resource_Doctrine extends Zend_Application_Resource_ResourceAbstract
{
    /**
     * Initialise l'ORM Doctrine en mémorisant l'entity manager dans le DIC
     */
    public function init()
    {
        $confDoctrine = $this->getOptions();

        if ('production' == APPLICATION_ENV) {
            $cache = new \Doctrine\Common\Cache\ApcCache;
        } else {
            $cache = new \Doctrine\Common\Cache\ArrayCache;
        }

        AnnotationRegistry::registerLoader('class_exists');
        $reader = new AnnotationReader();
        
        $config = new Configuration;
        $config->setMetadataCacheImpl($cache);
        $driverImpl = new AnnotationDriver($reader, ROOT_PATH . '/library/App/Domain/Entity');
        $config->setMetadataDriverImpl($driverImpl);
        $config->setQueryCacheImpl($cache);
        $config->setProxyDir(ROOT_PATH . '/library/App/Domain/Entity/Proxy');
        $config->setProxyNamespace('App\Domain\Entity\Proxy');
        
        if (true == $confDoctrine['proxies']['autogenerate']) {
            $config->setAutoGenerateProxyClasses(true);
        } else {
            $config->setAutoGenerateProxyClasses(false);
        }
        
        $em = EntityManager::create($confDoctrine['conn'], $config);
        $this->_bootstrap->bootstrap('dic');
        $this->_bootstrap->getResource('dic')->set('em', $em);
    }
}

Cette ressource utilise les paramètres suivants :

resources.doctrine.conn.driver           = 'pdo_mysql'
resources.doctrine.conn.host             = 'localhost'
resources.doctrine.conn.user             = 'root'
resources.doctrine.conn.password         = 'root'
resources.doctrine.conn.dbname           = 'mydatabase'
resources.doctrine.log.filename          = ROOT_PATH "/data/log/sql.log"
resources.doctrine.log.active            = false
resources.doctrine.proxies.autogenerate  = false

Au niveau du conteneur d'injection de dépendances de Symfony2, le service est donc défini comme suit :

services:
    em:
        synthetic: true

Vous pourrez maintenant créer vos entités dans le répertoire library/App/Domain/Entity et vos repositories dans library/App/Domain/Repository. La configuration a été faite de telle manière que vous puissiez utiliser un préfixe pour les annotations de l'ORM dans vos entités, ceci afin de pouvoir mélanger plusieurs types d'annotations (nous verrons l'intérêt avec le composant JMSSerializer plus bas). C'est la manière recommandée d'utiliser les annotations.

Voici un extrait d'une entité pour illustrer les annotations préfixées :

namespace App\Domain\Entity;

use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Entity
 * @ORM\Table(name="Societe")
 *
 */
class Societe
{
    /**
     * @ORM\Column(name="id", type="integer", nullable=false)
     * @ORM\Id @ORM\GeneratedValue(strategy="IDENTITY")
     * @var int
     */
    protected $id;

// etc.

JMSSerializer est un composant qui permet de sérialiser un objet en différents formats au moyen d'annotations. Un usage fréquent est la transformation de vos entités en JSON pour la réalisation d'API REST.

Commençons comme d'habitude par installer le composant avec Composer :

php composer.phar require jms/serializer

Pour sérialiser un objet, JMSSerializer parcourt toutes ses propriétés et les exporte au format désiré (souvent JSON, mais il est aussi possible de sortir du XML ou du YAML). Cela a l'air simple, mais toute la puissance de l'outil réside dans ses capacités d'adaptation : on peut ainsi lui dire de transformer le nom des propriétés (ce qu'il appelle une « naming strategy »), d'exclure certaines propriétés qu'on ne veut pas publier, de transformer les valeurs de sortie, de créer des propriétés virtuelles basées sur le résultat d'une méthode, etc.

Un détail va ici nous intéresser : pour le format JSON, par défaut, JMSSerializer applique une stratégie de nommage qui transforme le nom de toutes les propriétés en minuscules avec un underscore pour séparer les mots (convention « snake case »). Or classiquement dans une classe PHP nous utilisons plutôt la notation « camelCase ». Mais le sérialiseur nous le transformera en « camel_case » ! Cela se comprend, car cette convention est en général appliquée pour les formats JSON. Mais si nous voulons conserver les noms de propriétés originaux, il va falloir créer une classe de stratégie de nommage personnalisée. Rassurez-vous, ce n'est pas très compliqué.

Enfin, il est aussi possible de créer différentes catégories de sérialisation, en plaçant les propriétés dans des groupes. Dans certains cas en effet, vous voudrez sérialiser un même objet différemment suivant le contexte applicatif.

Pour simplifier l'utilisation du composant JMSSerializer, nous allons créer un service dédié « application.serializer » :

<?php
namespace App\Application\Serializer;

use JMS\Serializer\SerializerBuilder;
use JMS\Serializer\SerializationContext;

/**
 * Wrapper autour du serializer de JMS pour faciliter son usage
 */
class Serializer
{
    /**
     * Instance du sérialiseur JMS
     * @var JMS\Serializer\Serializer
     */
    protected $_jmsSerializer = null;
    
    /**
     * Doit-on sérialiser aussi les propriétés nulles ?
     * @var bool
     */
    protected $_serializeNull = true;
    
    /**
     * Construit l'instance du sérialiseur JMS
     */
    public function __construct()
    {
        $this->_jmsSerializer = SerializerBuilder::create()
            ->setPropertyNamingStrategy(new NamingStrategy())
            ->build();
    }
    
    /**
     * Spécifie si on doit sérialiser les propriétés nulles
     * @param bool $serializeNull
     * @return \App\Application\Serializer\Serializer
     */
    public function setSerializeNull($serializeNull)
    {
        if (is_null($serializeNull)) {
            throw new \InvalidArgumentException("Vous devez spécifier une valeur pour le paramètre serializenull");
        }
        $this->_serializeNull = $serializeNull;
        return $this;
    }
    
    /**
     * Sérialise un objet en spécifiant éventuellement des groupes pour obtenir une vue spécifique
     * @param array|object $object
     * @param string $format Format de sérialisation (défaut: json)
     * @param array $groups
     * @return string Objet sérialisé
     */
    public function serialize($object, $format = 'json', array $groups = null)
    {
        // si on ne précise pas de groupe, on prend le groupe par défaut
        if (empty($groups)) {
            $groups = array('Default');
        }
        return $this->_jmsSerializer->serialize(
            $object,
            $format,
            SerializationContext::create()
                ->setSerializeNull($this->_serializeNull)
                ->setGroups($groups)
        );
    }
}

Ce service se déclare donc comme suit, en précisant d'appeler la méthode setSerializeNull pour configurer cette option :

application.serializer:
    class: App\Application\Serializer\Serializer
    calls: 
        - [setSerializeNull, ['%serializer.serializenull%']]

Le service se base sur ce paramètre de configuration pour savoir s'il faut inclure ou pas les propriétés de valeur nulle dans la sérialisation (par défaut dans JMSSerializer cette valeur est à false) :

resources.dic.params.serializer.serializenull = true

Et voici la classe de stratégie de nommage :

<?php
namespace App\Application\Serializer;

use JMS\Serializer\Naming\PropertyNamingStrategyInterface;
use JMS\Serializer\Metadata\PropertyMetadata;

/**
 * Classe pour spécifier la stratégie de nommage des propriétés du JMSSerializer
 * Car la classe qu'on utilise d'habitude (IdenticalPropertyNamingStrategy) ignore l'annotation SerializedName
 */
class NamingStrategy implements PropertyNamingStrategyInterface
{
    public function translateName(PropertyMetadata $property)
    {
        if (!empty($property->serializedName)) {
            return $property->serializedName;
        }
        return $property->name;
    }
}

Bien évidemment, si la stratégie de nommage par défaut vous convient, il suffit de ne pas appeler la méthode setPropertyNamingStrategy lors de l'initialisation de JMSSerializer ;-)

Vous pourrez dès lors utiliser les annotations JMSSerializer dans vos entités, voici un exemple :

<?php
namespace App\Domain\Entity;

use Doctrine\ORM\Mapping as ORM;
use JMS\Serializer\Annotation as JMSSerializer;

/**
 * @ORM\Entity
 * @ORM\Table(name="Societe")
 *
 */
class Societe
{
    /**
     * @ORM\Column(name="id", type="integer", nullable=false)
     * @ORM\Id @ORM\GeneratedValue(strategy="IDENTITY")
     * @JMSSerializer\Exclude
     * @var int
     */
    protected $id;
    
    /**
     * @ORM\Column(name="raisonSociale", type="string", length=255, nullable=false)
     * @JMSSerializer\Groups({"Default", "modif"})
     * @var string
     */
    protected $raisonSociale;

// etc.

Et voici comment utiliser notre service de sérialisation depuis un contrôleur :

// récupération du service
$serializer = $this->_helper->dic()->get('application.serializer');

// exemple de sérialisation simple
$serializer->serialize($monEntite);

// exemple de sérialisation basée sur un contexte particulier (ici « modif »)
$json = $serializer->serialize($monEntite, 'json', array('modif'));

Réalisé par le créateur de Composer, Monolog est un service de log très évolué, bien plus puissant que Zend_Log. Il gère de multiples options de formatage, de multiples formats de sortie (fichier texte, mais aussi logs système, logs distants compatibles… ), bref c'est un composant très intéressant.

L'installation est triviale avec Composer :

php composer.phar require monolog/monolog

Ici aussi nous réaliserons une ressource de boostrap spécialisée pour l'initialiser :

<?php
use Monolog\Logger;
use Monolog\Handler\RotatingFileHandler;
use Monolog\Handler\StreamHandler;
use Monolog\Formatter\LineFormatter;
use Monolog\Processor\IntrospectionProcessor;
use Monolog\Processor\MemoryPeakUsageProcessor;
use Monolog\Processor\MemoryUsageProcessor;
use Monolog\Processor\WebProcessor;

class My_Resource_Log extends Zend_Application_Resource_ResourceAbstract
{
    /**
     * Initialise le logger Monolog et le mémorise dans le DIC
     */
    public function init()
    {
        $conf = $this->getOptions();
        $logger = new Logger('app');
        
        // n'utilise le split journalier que pour les environnements "live" (pas le dev)
        if (substr($this->_bootstrap->getEnvironment(), 0, 3) != 'dev') {
            $handler = new RotatingFileHandler($conf['file'], $conf['maxfiles']);
        } else {
            $handler = new StreamHandler($conf['file']);
        }
        
        $handler->setFormatter(new LineFormatter(null, null, true));
        $logger->pushHandler($handler);
        
        $logger->pushProcessor(new IntrospectionProcessor());
        $logger->pushProcessor(new MemoryPeakUsageProcessor());
        $logger->pushProcessor(new MemoryUsageProcessor());
        $logger->pushProcessor(new WebProcessor());

        $this->_bootstrap->bootstrap('dic');
        $this->_bootstrap->getResource('dic')->set('log', $logger);
    }
}

Comme d'habitude, je vous renvoie à la documentation officielle pour les détails de l'initialisation du composant.

Cette ressource utilise les paramètres suivants :

resources.log.file = ROOT_PATH "/data/log/app.log"
resources.log.maxfiles = 60   ; conserve un fichier de log par jour pendant 60 jours

Ensuite, dans l'application, écrire dans le log se fait en récupérant le service « log » et en utilisant les méthodes debug(), warning() ou error() exactement comme on le ferait avec Zend_Log.

Certains composants simples ne nécessitent même pas de configuration en tant que service. C'est le cas du composant php-markdown de Michel Fortin, qui permet donc de transformer une chaîne de caractères du format Markdown au format HTML. Son utilisation est toute simple, comme le montre cet extrait de la documentation :

use Michelf\Markdown;
$my_html = Markdown::defaultTransform($my_text);

Dans le cadre d'une application Zend Framework, le plus simple est d'embarquer ce code dans un helper de vue. Grâce à l'inclusion de l'autoloader de Composer dans le bootstrap de notre application, un simple use suffira à utiliser la classe.

Commençons d'abord par installer le composant avec Composer comme d'habitude :

php composer.phar require michelf/php-markdown

Déclarons le chemin où sont situés nos helpers de vue dans la configuration de l'application :

resources.view.helperPath = APPLICATION_PATH "/helpers/view"

Enfin, créons le helper de vue suivant :

<?php
use Michelf\Markdown;

class Zend_View_Helper_Markdown extends Zend_View_Helper_Abstract
{
    public function markdown($text)
    {
        return Markdown::defaultTransform($text);
    }
}

L'utilisation se fera par un simple $this->markdown($text) dans une vue phtml.