Si votre entreprise développe beaucoup sous Symfony 2, vous avez généralement besoin d’industrialiser la production. Cela passe forcément par un gestionnaire capable de gérer le déploiement et les dépendances entre vos paquets. La méthode n’est pas restreinte à Symfony; elle s’appliquera tout aussi bien à d’autres technologies utilisant Composer telles que Zend Framework 2, WordPress, PHP Unit, etc.
Satis est un indexeur de packages Composer. Il permet de remplacer Packagist (très utile dans le domaine publique) dans le domaine privé. Il est issu du projet Composer.
Je vais tenter de vous expliquer comment mettre en place votre propre dépôt de bundles. L’exemple sera fait d’éléments externes souvent utilisés que sont les bibliothèques JavaScript et CSS, et il sera déclinable à l’infini sur des bibliothèques PHP ou des bundles maison.
Installation de Satis
Satis est un projet en ligne de commande. De conception, il pourra sans problème être exécuté par un ordonnanceur (comme Cron), via un hook Subversion, ou conclure un processus de build. Il ne nécessite pas de virtualhost pour lui même, mais produira des fichiers statiques qui devront être accessibles par le web.
Son installation est extrêmement simple, elle utilise Composer :
|
1 |
$ composer.phar create-project composer/satis --stability=dev [cible] |
La cible étant le nom du dossier dans lequel vous souhaitez l’installer.
Une seule instance de Satis pourra gérer plusieurs dépôts si besoin (ici je n’en déclarerais qu’un). Chaque dépôt est déclaré dans un fichier JSON. Par défaut, Il recherchera le fichier « satis.json » :
|
1 2 3 4 5 6 7 8 9 10 |
{ "name": "MonServeurDeBundle", "homepage": "http://mon-serveur-de-bundle.local", "repositories": [ { "type": "svn", "url": "http://mon-serveur-svn.local/sf2-bundles/bootstrap" }, { "type": "svn", "url": "http://mon-serveur-svn.local/sf2-bundles/font-awesome" }, { "type": "svn", "url": "http://mon-serveur-svn.local/sf2-bundles/jquery" } ], "require-all": true } |
- « name »: Sera le nom du dépôt. Il apparaîtra en titre de la page web statique générée par Satis.
- « homepage »: L’url du dépôt, pointant vers la même page web statique
- « repositories »: Liste des dépôts de fichiers devant être indexés par cette instance
- « require-all »: Indique à Satis que vous indexerez toutes les versions de tous les dépôts
Vous pouvez mixer à volonté les types de serveur (Subversion, GIT, etc). Portez toutefois attention au mode d’authentification lorsque vous aurez prévu d’automatiser son lancement. Utilisez soit des comptes à usage local en lecture seule, dont vous pourrez indiquer le mot de passe; soit une authentification par clé privée. Pour l’exemple, nous lanceront Satis manuellement, et il nous demandera les accès Subversion de chacun des trois dépôt référencés ci dessus.
Vous pouvez explorer plus loin la configuration de Satis depuis sa documentation (en anglais).
Après avoir mis des packages à disposition, on exécutera Satis par cette ligne de commande :
|
1 |
$ php [chemin-vers-satis]/bin/satis build satis.json [chemin-vers-racine-web] |
Satis va alors se connecter à chaque dépôt référencé dans le fichier JSON (ici « satis.json »), vous demandant éventuellement d’en saisir les accès. Il indexera sur chacun le fichier « composer.json », et produira le dépôt sous forme de fichiers statiques, qu’il placera dans « [chemin-vers-racine-web] ».
Format d’un package
Je vais prendre comme exemple le premier bundle référencé dans le fichier JSON : Bootstrap. Voici son arborescence sous subversion:
- branches
- tags
- 3.3.4
- composer.json
- MonEntrepriseBootstrapBundle.php
- Resources
- public
- css
- bootstrap.css
- bootstrap.css.map
- bootstrap.min.css
- bootstrap-theme.css
- bootstrap-theme.css.map
- bootstrap-theme.min.css
- fonts
- glyphicons-halflings-regular.eot
- glyphicons-halflings-regular.svg
- glyphicons-halflings-regular.ttf
- glyphicons-halflings-regular.woff
- glyphicons-halflings-regular.woff2
- js
- bootstrap.js
- bootstrap.min.js
- css
- public
- 3.3.4
- trunk
Je l’ai choisi parce que c’est un élément externe que j’utilise beaucoup. Comme il n’est pas de moi, il ne contiendra que des tags (ici le tag 3.3.4). Comme c’est un framework CSS et JS, il sera très simple, du point de vue de Symfony 2. Enfin il va me permettre de vous montrer la faculté qu’a Satis de gérer les dépendances.
Voici son fichier composer.json, qui sera indexé par Satis :
|
1 2 3 4 5 6 7 8 9 10 11 12 |
{ "name": "mon-entreprise/bootstrap", "type": "symfony-bundle", "description": "Bootstrap 3.3.4", "keywords": [ "bootstrap" ], "homepage": "http://getbootstrap.com", "licence": "MIT", "version": "3.3.4", "autoload": { "psr-4": { "MonEntreprise\BootstrapBundle\": "" } } } |
Pour que Composer ait connaissance de votre nouveau dépôt géré par Satis, vous devrez le référencer dans le « composer.json » du projet cible, en ajoutant :
|
1 2 3 4 5 6 7 8 |
{ "repositories": [ { "type": "composer", "url": "http://mon-serveur-de-bundle.local" } ] } |
Satis est prévu pour utiliser l’indispensable trio branches / tags / trunk. Lorsque vous ajouterez l’un de vos bundles à un projet, vous pourrez utiliser la syntaxe suivante :
|
1 |
$ composer.phar require mon-entreprise/bootstrap ~3.3 |
Pour aller chercher votre bundle dans les tags; ou bien :
|
1 |
$ composer.phar require mon-entreprise/bootstrap dev-trunk |
Pour aller le chercher dans le trunk.
Après chaque mise à jour de l’un de vos bundles, vous devrez regénérer le dépôt de Satis depuis le serveur à l’aide de la commande :
|
1 |
$ php [chemin-vers-satis]/bin/satis build satis.json [chemin-vers-racine-web] |
Le temps de vous faire la main, vous serez certainement amené à installer et désinstaller vos bundles régulièrement du projet qui les utilise. La désinstallation doit se faire manuellement en supprimant le sous-dossier du bundle dans le dossier « vendor » du projet, puis en retirant l’objet qui référence le bundle dans les fichiers « composer.json » et « composer.lock » du projet.
Comme pour tous les bundles, une fois installé dans le projet cible, vous devrez l’ajouter au kernel en ajoutant à la méthode « registerBundles() » la ligne :
|
1 |
new MonEntrepriseBootstrapBundleMonEntrepriseBootstrapBundle(), |
Comme il s’agit d’un bundle contenant des assets (même que des assets), il faudra aussi les installer avec la commande :
|
1 |
$ php app/console assets:install |
Enfin, vous pourrez utiliser Bootstrap depuis votre application en appelant ses assets :
|
1 2 |
<link href="{{ asset('bundles/monentreprisebootstrap/css/bootstrap.min.css') }}" rel="stylesheet" type="text/css"> <script src="{{ asset('bundles/monentreprisebootstrap/js/bootstrap.min.js') }}"></script> |
Je vous laisse créer le bundle jQuery sur le même modèle. Revenez ensuite dans le »composer.json » de votre bundle Bootstrap pour le référencer comme dépendance, en ajoutant :
|
1 2 3 |
"require": { "mon-entreprise/jquery": "~1.11" }, |
Une fois jQuery déclaré comme dépendance de Bootstrap, il sera installé automatiquement avec ce dernier.
Pour aller plus loin
Vous pouvez aussi demander à Satis de packager localement les bundles.
Ajoutons les directives suivantes au fichier « satis.json » vu précédemment :
|
1 2 3 4 5 6 7 |
{ "archive": { "directory": "dist", "format": "tar", "prefix-url": "http://mon-serveur-de-bundle.local" } } |
- « directory »: Dossier de stockage des archives
- « format »: Format des archives
- « prefix-url »: URL d’accès au dépôt d’archives
Dans ce cas, Satis vous demandera doublement les identifiants d’accès aux gestionnaires de version (SVN, GIT, etc).
Les avantages de cette solution :
- Économies de bande passante. Satis va aller chercher les sources, puis les développeurs téléchargeront les archives depuis Satis.
- Centralisation des identifiants. C’est Satis qui va s’identifier auprès des différents dépôts de fichiers. Les développeurs pourront potentiellement accéder aux archives de façon libre.
- Particulièrement utile dans le cas où les développeurs n’ont pas directement accès aux dépôts de fichiers source.
Liens
- Handling private packages with Satis: Documentation officielle de Satis en anglais, sur le site de Composer.
- Créer un repository de Bundles privés avec Satis: Article qui m’a fait découvrir Satis, et dont je me suis inspiré pour rédiger le mien.