Installer un bundle grâce à Composer Symfony2

Comment Composer sait où trouver les bibliothèques ?

Très bonne question. En effet, il est évident que ce système de gestion ne peut marcher que si on peut centraliser les informations de chaque bibliothèque. Il s'agit du site www.packagist.org.

Par exemple, voici la page pour la bibliothèque Symfony2 (eh oui, c'est une bibliothèque comme une autre !) : https://packagist.org/packages/symfony/symfony. Vous pouvez voir les informations comme le mainteneur principal, le site de la bibliothèque, etc. Mais ce qui nous importe le plus, ce sont les sources ainsi que les dépendances (dans Requires).

Composer va donc lire ces informations, et a alors toutes les cartes en main pour télécharger Symfony2 ainsi que ses dépendances.

Concrètement, comment ça marche ?

Concrètement, voici comment s'utilise Composer :

• On définit dans un fichier la liste des bibliothèques dont le projet dépend, ainsi que leur version ;
• On exécute une commande pour installer ou mettre à jour ces bibliothèques (et leurs propres dépendances donc) ;
• On inclut alors le fichier d'autoload généré par Composer dans notre projet.

Mais avant de manipuler Composer, commençons par l'installer !

Installer Composer et Git

nstaller Composer

Installer Composer est très facile, il suffit d'une seule commande… PHP ! Exécutez cette commande dans la console :

C:\wamp\www> php -r "eval('?>'.file_get_contents('http://getcomposer.org/installer'));"

Si nous avons des problèmes de OPENSSL 

extension=php_openssl.dll ( wamp <-> bin <-> php <-> php5.4.16 <-> php.ini )

on active extension dans php extension

ce n'est pas Composer en lui-même mais son installateur. Il fait quelques vérifications (version de PHP, etc.), puis télécharge effectivement Composer dans le fichier composer.phar.

Composer en lui-même, c'est le fichier PHARcomposer.phar, c'est lui que nous devrons exécuter par la suite. Vous pouvez déjà l'exécuter pour vérifier que tout est OK :

C:\wamp\www>php composer.phar --version
Composer version a5eaba8

N'hésitez pas à mettre à jour Composer lui-même de temps en temps. Il faut pour cela utiliser la commande self-update de Composer, comme suit :

C:\wamp\www>php composer.phar self-update
Updating to version ded485d.
    Downloading: 100%

Et voilà, je viens de mettre à jour Composer très simplement !

Cependant, l'installation n'est pas finie. En effet, pour récupérer certaines bibliothèques, Composer utilise Git.

Installer Git

Sous Windows, il faut utiliser msysgit. Cela installe msys (un système d'émulation des commandes Unix sous Windows) et Git lui-même.

Téléchargez le fichier et exécutez-le, cela va tout installer. Laissez les paramètres par défaut, ils conviennent très bien. Cela va prendre un peu de temps, car il y a pas mal à télécharger (une centaine de Mo) et à exécuter, ne vous inquiétez pas. Une fois que vous avez une ligne de commande (/dev), vous pouvez fermer la fenêtre.

Une fois cela installé, il faut ajouter les exécutables Git au PATH de Windows. Ajoutez donc ceci : « ;C:\msysgit\bin;C:\msysgit\mingw\bin » à la suite de votre variable d'environnement système PATH

Redémarrez votre ordinateur, et ensuite vérifiez l'installation en exécutant la commande suivante :

C:\wamp\www>git version
git version 1.7.9.msysgit.0

Si vous n'avez pas d'erreur, c'est tout bon !

Installer Git sous Linux

Sous Linux, c'est encore plus simple avec votre gestionnaire de paquets. Voici comment l'installer depuis la distribution Debian et ses dérivées (Ubuntu, etc.) :

sudo apt-get install git-core

Installer un bundle grâce à Composer

Manipulons Composer

Avant d'utiliser Composer dans notre projet Symfony2, on va d'abord s'amuser avec lui sur un projet test afin de bien comprendre son fonctionnement. Créez donc un répertoire test là où vous avez téléchargé Composer.

Déclarer ses dépendances

La première chose à faire dans un projet, c'est de déclarer ses dépendances. Cela se fait via un fichier composer.json, qui contient les informations sur les bibliothèques dont dépend votre projet ainsi que leur version. La syntaxe est assez simple, en JSON, créez le fichier composer.json  suivant dans le répertoire test  :

{
  "require": {
    "twig/extensions": "~1.0"
  }
}

Ce tableau JSON est le minimum syndical : il ne précise que les dépendances via la clé require. Il n'y a ici qu'une seule dépendance : "twig/extensions". La version requise pour cette dépendance est "~1.0", cela signifie qu'on veut la version la plus récente dans la branche 1.* .

Un point sur les versions, voici ce que vous pouvez mettre :

Valeur	Exemple	Description
Un numéro de version exact	"2.0.17"	Ainsi, Composer téléchargera cette version exacte.
Une plage de versions	">=2.0,<2.6"	Ainsi, Composer téléchargera la version la plus à jour, à partir de la version 2.0 et en s'arrêtant avant la version 2.6. Par exemple, si les dernières versions sont 2.4, 2.5 et 2.6, Composer téléchargera la version 2.5.
Une plage de versions sémantique	"~2.1"	Ainsi, Composer téléchargera la version la plus à jour, à partir de la version 2.1 et en s'arrêtant avant la version 3.0. C'est une façon plus simple d'écrire ">=2.1,<3.0"  avec la syntaxe précédente. C'est la façon la plus utilisée pour définir la version des dépéndances.
Un numéro de version avec joker « * »	"2.0.*"	Ainsi, Composer téléchargera la version la plus à jour qui commence par 2.0. Par exemple, il téléchargerait la version 2.0.17, mais pas la version 2.1.1.
Un nom de branche "dev-XXX"		C'est un cas un peu particulier, où Composer ira chercher la dernière modification d'une branche Git en particulier. N'utilisez cette syntaxe que pour les bibliothèques dont il n'existe pas de vraie version. Vous verrez assez souvent "dev-master", où "master" correspond à la branche principale d'un dépôt Git.

Dans notre cas, "~1.0" correspond à la branche 1.* .

Pour information, vous pouvez aller regarder les informations de cette bibliothèque sur Packagist. Vous pouvez voir que les seules versions stables existantes (à l'heure où j'écris ces lignes) sont : 1.0.0, 1.0.1 et 1.1.0 . Notre contrainte de version "~1.0"  les accepte toutes, Composer ira donc chercher dans notre cas la version la plus récente, ici 1.1.0 .

Vous pouvez voir également qu'elle dépend d'une autre bibliothèque, "twig/twig", qui correspond au moteur de templates Twig à proprement parler. Elle en a besoin dans sa version "~1.12", Composer ira donc chercher la dernière version dans la branche 1.* . A l'heure où j'écris ces lignes, il s'agit de la version 1.16.0.

Mettre à jour les dépendances

Pour mettre à jour toutes les dépendances, "twig/extensions" dans notre cas, il faut exécuter la commande update de Composer, comme ceci :

C:\wamp\www\test>php ../composer.phar update
Loading composer repositories with package information
Updating dependencies (including require-dev)
 - Installing twig/twig (v1.16.0)
 Downloading: 100%

 - Installing twig/extensions (v1.1.0)
 Downloading: 100%

Writing lock file
Generating autoload files

C:\wamp\www\test>

Chez moi, j'ai placé Composer (le fichier composer.phar) dans le répertoire www. Or ici on travaille dans le répertoire de test www\test. J'ai donc dit à PHP d'exécuter le fichier ../composer.phar, mais bien sûr si le vôtre est dans le répertoire courant ou ailleurs, adaptez la commande.

Et voilà !

Vous pouvez aller vérifier dans le répertoire test/vendor :

• Composer a téléchargé la dépendance "twig/extensions" que l'on a défini, dans vendor/twig/extensions ;
• Composer a téléchargé la dépendance "twig/twig" de notre dépendance à nous, dans vendor/twig/twig ;
• Composer a généré les fichiers nécessaires pour l'autoload, allez vérifier le fichier vendor/composer/autoload_namespaces.php.

Tout est maintenant OK pour se servir de "twig/extensions" dans votre projet ! C'était donc la démarche et le fonctionnement pour la gestion des dépendances avec Composer. Mais revenons maintenant à notre projet sous Symfony2.

Mettons à jour Symfony2

Si vous avez téléchargé la version de Symfony2 qui comprend déjà les dépendances, vous avez en fait téléchargé tout le contenu du dossier vendor que Composer pourrait gérer tout seul. L'objectif de ce paragraphe est de déléguer cette gestion à Composer.

Vous pouvez voir qu'en fait il existe déjà un fichier de définition des dépendances à la racine de votre projet : le fichier composer.json. N'hésitez pas à l'ouvrir : vous pourrez y voir toutes les dépendances déjà définies.

Pour l'instant, ce fichier existe, mais on n'a jamais utilisé Composer pour les gérer. Il ne reste donc plus qu'à dire à Composer de les mettre toutes à jour. Rien de spécial à faire par rapport à tout à l'heure, exécutez simplement la commande suivante :

php ../composer.phar update

Cela va prendre un peu de temps, car Composer a beaucoup à télécharger, les dépendances d'un projet Symfony2 sont nombreuses. Il y a en effet Symfony2 en lui-même, mais également Doctrine, Twig, certains bundles, etc.

Maintenant, Composer a pris la main sur toutes vos dépendances, on va pouvoir en ajouter une nouvelle : un bundle Symfony2 !

Installer un bundle avec Composer

Dans ce paragraphe, nous allons installer le bundle DoctrineFixtureBundle, qui permet de préremplir la base de données avec des données, afin de bien tester votre application. Cependant, les explications sont valables pour l'installation de n'importe quel bundle, retenez donc bien la méthode.

1. Trouver le nom du bundle

Vous l'avez compris, on définit une dépendance dans Composer via son nom. Il faut donc logiquement connaître ce nom pour pouvoir l'installer. Pour cela, rien de plus simple, on se rend sur http://packagist.org/ et on fait une petite recherche. Dans notre cas, recherchez « fixture », et cliquez sur le bundle de Doctrine, « doctrine/doctrine-fixtures-bundle ».

2. Déterminer la version du bundle

Une fois que vous avez trouvé votre bundle, il faut en sélectionner une version. Il se peut que celui-ci n'ait pas vraiment de version fixe, et que seul "dev-master" soit disponible. Dans ce cas, assurez vous (auprès du développeur, ou en regardant le code) qu'il est compatible avec votre projet.

Mais la plupart du temps, les bundles sont versionnés et c'est à vous de choisir la version qui vous convient. Restons sur notre cas du bundle fixture : https://packagist.org/packages/doctrin [...] xtures-bundle . Les deux dernières versions stables sont "2.2.0" et "2.0.1" :

• Regardez les prérequis de la version 2.0.1 : il est indiqué que cette version a besoin de "symfony/symfony" dans sa version 2.0 (car "<2.1" exclut la version 2.1). Cette version est trop vieille, on ne peut donc pas l'utiliser, car on tourne sur un Symfony 2.5 ;
• Regardez alors les prérequis de la version 2.2.0 : a priori pas de soucis car il n'y a pas de version maximale (pas de "<2.4" par exemple).

On choisit alors la version "2.2.0" du bundle, ou plus précisément toute la branche 2.* à partir de la version 2.2 grâce à la contrainte "~2.2" .

3. Déclarer le bundle à Composer

Une fois qu'on a le nom du bundle et sa version, il faut le déclarer à Composer, dans le fichier composer.json. On sait déjà le faire, il faut modifier la section "require", voici ce que cela donne :

// composer.json

// …

"require": {
  "php": ">=5.3.3",
  // …
  "incenteev/composer-parameter-handler": "~2.0",
  "doctrine/doctrine-fixtures-bundle": "~2.2"
},

// …

N'oubliez pas d'ajouter une virgule à la fin de l'avant-dernière dépendance, dans mon cas "incenteev/composer-parameter-handler", sinon ce n'est plus du Json valide !

4. Mettre à jour les dépendances

Une fois la dépendance déclarée à Composer, il ne reste qu'à mettre à jour les dépendances, avec la commande update :

C:\wamp\www\Symfony>php ../composer.phar update
Updating dependencies (including require-dev)
 - Installing doctrine/data-fixtures (v1.0.0)
 Loading from cache

 - Installing doctrine/doctrine-fixtures-bundle (v2.2.0)
 Loading from cache

[…]

5. Enregistrer le bundle dans le Kernel

Dernier point, totalement indépendant de Composer : il faut déclarer le bundle dans le Kernel de Symfony2. Allez dans app/AppKernel.php et ajoutez le bundle à la liste :

<?php
// app/AppKernel.php

// …

  if (in_array($this->getEnvironment(), array('dev', 'test'))) {
      // ...
      $bundles[] = new Doctrine\Bundle\FixturesBundle\DoctrineFixturesBundle();
    }

// …

Ici, j'ai déclaré le bundle uniquement pour les modes « dev » et « test » (regardez la condition du if), car c'est l'utilité du bundle fixture, on en reparlera. Bien entendu, si votre bundle doit être accessible en mode « prod », placez-le hors de ce if.  

Voilà, votre bundle est opérationnel !

Mais comment Composer donne à Symfony les informations pour l'autoload ?

Bonne question. Composer s'occupe vraiment de tout, et notamment de déclarer les namespaces pour l'autoload : allez le vérifier dans le fichier vendor/composer/autoload_namespaces.php. Ce fichier contient tous les namespaces nécessaires pour votre projet. C'est lui que Symfony2 inclut déjà, vérifiez-le en regardant le fichier app/autoload.php, on y voit cette ligne :

<?php
$loader = require __DIR__.'/../vendor/autoload.php';
// …

Voilà comment Symfony2 utilise Composer pour gérer son autoload.

Gérer l'autoload d'une bibliothèque manuellement

Il se peut que vous ayez une bibliothèque existante en stock, mais qui n'est pas référencée sur Packagist. Composer ne peut pas gérer entièrement cette bibliothèque, car il n'a pas ses informations : comment la mettre à jour, quelles sont ses dépendances, etc.

Par contre, vous avez tout de même envie de l'intégrer dans votre projet. Notamment, vous souhaitez la charger automatiquement grâce à l'autoload PHP. Il existe un moyen rapide pour y arriver : il faut ajouter les informations à la section "autoload" de votre composer.json. Composer ne mettra pas son nez dans cette section pour tout ce qui est installation et mises à jour. Par contre, il l'inclura dans son fichier d'autoload que Symfony2 charge. Voici ce que vous devez rajouter (ligne 8 dans le code suivant) :

// composer.json

{
  // …

  "autoload": {
    "psr-0": { "": "src/", "SymfonyStandard": "app/",
      "VotreNamespace": "chemin/vers/la/bibliotheque"
    }
  },

  // …
}

Attention, il faut toujours utiliser cette méthode et ne jamais aller modifier le fichier vendor/composer/autoload_namespaces.php ! Comme tout fichier qui se trouve dans le répertoire vendor, vous ne devez pas le toucher, car il peut être écrasé à tout moment : dès que vous faites un update avec Composer, ce dernier va télécharger les nouvelles versions et écraser les anciennes…

L'idée est donc de dire manuellement à Composer que votre bibliothèque "VotreNamespace"  se trouve dans le répertoire "chemin/vers/la/bibliothèque". Enfin, pour que Composer regénère les fichiers d'autoload avec cette nouvelle information, il faut exécuter sa commande dump-autoload :

C:\wamp\www\Symfony>php ../composer.phar dump-autoload
Generating autoload files

Bien sûr, pour que cela fonctionne il faut que votre bibliothèque respecte la convention PSR-0, c'est-à-dire une convention de nommage et d'autoloading. Je vous invite à lire le lien pour en savoir plus à ce propos. Symfony2 suit bien entendu cette convention.

Pour conclure

Ce chapitre-parenthèse sur Composer touche à sa fin. S'il vous semble un peu décalé aujourd'hui, vous me remercierez un peu plus tard de vous en avoir parlé, lorsque vous voudrez installer des bundles trouvés à droite ou à gauche. D'ailleurs, on a déjà installé DoctrineFixtureBundle, un bundle bien pratique dont nous nous resservirons dès la prochaine partie sur Doctrine !

Sachez également que je n'ai absolument pas tout dit sur Composer, car cela ferait trop long et ce n'est pas tellement l'objet de ce tutoriel. Cependant, Composer a sa propre documentation et je vous invite à vous y référer. Par curiosité, par intérêt, en cas de problème, n'hésitez pas : http://getcomposer.org !

En résumé

• Composer est un outil pour gérer les dépendances d'un projet en PHP, qu'il soit sous Symfony2 ou non.
• Le fichier composer.json permet de lister les dépendances que doit inclure Composer dans votre projet.
• Composer détermine la meilleure version possible pour vos dépendances, les télécharge, et configure leur autoload tout seul.
• Composer trouve toutes les bibliothèques sur le site http://www.packagist.org, sur lequel vous pouvez envoyer votre propre bibliothèque si vous le souhaitez.
• La très grande majorité des bundles Symfony2 sont installables avec Composer, ce qui simplifie énormément leur utilisation dans un projet.