Composer : Votre propre annuaire de dépendances avec Satis

Composer est le nouveau gestionnaire de dépendances disponible dans le monde PHP. Pour rappel, un premier article sur cet outil est d’ores et déjà disponible sur le blog ainsi qu’une superbe cheatsheet avec les commandes et les paramètres les plus utiles.

Ce deuxième article va détailler une utilisation plus avancée de l’outil. En effet, nous allons nous concentrer sur la création d’un package, son référencement dans l’annuaire de bibliothèques alias Packagist, et également sur la création de son propre annuaire.

Section intitulée fork-et-utilisation-de-sa-propre-version-d-un-packageFork et utilisation de sa propre version d’un package

Avant même de créer votre propre bibliothèque, vous allez certainement vouloir au cours d’un projet, corriger un bug, ou ajouter une fonctionnalité dans un package existant. Dans le meilleur des cas, le code est sur Github, vous faites un fork et une pull request, et le mainteneur du package l’accepte rapidement.

Mais si la pull request n’est pas accepté rapidement, vous souhaitez tout de même les autres développeurs récupèrent votre version de la librairie. Pour cela, il suffit de rajouter à votre fichier composer.json un paramètre repositories et d’indiquer le type et l’url du dépôt où se trouve votre version :

"repositories": [
     {
       "type": "vcs",
       "url": "https://github.com/ternel/FPNTagBundle"
     }
],

Composer récupère les informations des packages sur Packagist si aucun dépôt n’a été spécifié dans cette section. FPNTagBundle est un Bundle Symfony2 que j’ai du forker pour ajouter une fonctionnalité, grâce au paramètre repositories avec les valeurs ci-dessus, Composer va tenter de récupérer les informations directement sur le dépôt spécifié, et il installera la version disponible sur ce dépôt. Pour un autre bundle, il aurait d’abord cherché sur ce dépôt et ne trouvant pas d’informations, il aurait continué sa recherche sur Packagist, l’annuaire centrale de librairies.

La prochaine étape va être de créer votre propre package.

Section intitulée creation-d-un-packageCréation d’un package

Pour l’exemple, nous allons prendre un SDK pour utiliser l’API proposée par un site.

Pour créer un package, c’est très simple. Il suffit d’avoir un fichier composer.json dans un dossier et ce dossier devient un package. Si ce composer.json contient une directive require, cela devient un package qui dépend d’un ou plusieurs autres packages. Le seul paramètre obligatoire pour que votre dossier devienne un package installable via composer, c’est de lui donner un nom :

{
    "name": "ternel/weekend-sdk",
    "description": "PHP-SDK to use EstCeQueCestBientotLeWeekEnd API"
}

Il est important de rappeler qu’un nom de package doit être composé de la façon suivante : vendor-name/package-name La description n’est pas obligatoire mais largement conseillée.

Vous avez maintenant un package installable par Composer, à condition d’ajouter à la main un dépôt dans le fichier de configuration comme on a pu le voir dans le premier point de cet article.

$ php composer.phar search weekend
ternel/weekend-sdk : PHP-SDK to use EstCeQueCestBientotLeWeekEnd API

C’est déjà pas mal, mais on peut faciliter encore plus l’installation de notre bibliothèque.

Section intitulée enregistrement-sur-packagistEnregistrement sur Packagist

Packagist est l’annuaire que Composer utilise par défaut afin de lister, rechercher et installer les bibliothèques. Pour référencer sa bibliothèque sur Packagist.org, il faut vous connecter et simplement donner l’url de votre dépôt, toutes les informations nécessaires sont dans votre composer.json. En quelques minutes, vous retrouvez votre code disponible à l’installation via composer. Il est important de mettre un maximum d’informations dans le fichier json de votre bibliothèque afin de la référencer correctement.

Si votre bibliothèque est hébergé sur github, sachez qu’il existe un hook Packagist à configurer avec les informations que le site vous donne. Dès que vous envoyez une nouvelle version, github va notifier Packagist et l’annuaire sera tout de suite mis à jour.

Section intitulée installation-et-utilisation-de-satisInstallation et utilisation de Satis

Satis vous permet de créer votre propre annuaire de package. Il est notamment utilisé par packagist.org. Encore une fois, une installation très simple grâce à composer et à sa fonctionnalité create-project :

php composer.phar create-project composer/satis

Satis se base ensuite sur un fichier de configuration au format JSON, voici les quelques paramètres à renseigner pour configurer correctement votre Satis :

{
    "name": "Ternel's Repo",
    "homepage": "http://composer-repo.ternel.net",
    "repositories": [{
        "type": "vcs",
        "url": "http://github.com/ternel/weekend-php-sdk"
    }],
    "require-all": true
}

Il faut donc un nom pour cet annuaire, et une url, ainsi que la liste des dépôts que Satis va devoir scanner pour trouver des packages. Le paramètre require-all permet d’indiquer que nous voulons mettre à disposition toutes les versions disponibles sur notre dépôt. Dans le cas contraire, nous devons le spécifier dans le paramètre require.

Une commande permet ensuite de scanner les différents dépôts et de créer la liste des packages disponibles via ce nouvel annuaire :

$ php bin/satis build config.json web

Deux fichiers sont alors générés dans le dossier web de notre application :

• un index.html qui ne fait que donner des informations pour cet annuaire : nom, url, liste des packages et versions
• un packages.json qui est le fichier important pour que Composer puisse récupérer toutes les informations concernant les packages disponibles.

Et voila, vous avez maintenant un annuaire privé de packages PHP. Plus rien ne vous empêche donc de packager vos propres projets internes, d’avoir vos propres miroirs pour vos dépendances (afin de rendre vos serveurs de production indépendant de Github par exemple), ou encore de publier en 2 min votre nouvelle librairie de génération de poney en ASCII !