Il y a différentes façons d'installer/déployer Kirby CMS mais aussi ses plugins. Vous pouvez le faire à la main par des copier/coller de dossiers et fichiers, vous pouvez utiliser Git et un système de Webhook, vous pouvez utiliser Kirby CLI ou vous pouvez utiliser l'outil Composer. Dans cet article nous allons nous concentrer sur l'utilisation de Composer.

Composer est un outil en ligne de commande permettant de faciliter la gestion des dépendances d'un projet PHP. On entend par "dépendances" des packages ou librairies externes dont dépend votre projet. Chaque dépendance pouvant avoir ses propres dépendances qui elles-mêmes peuvent avoir des dépendances, les mises à jour à la main peuvent vite devenir périlleuses et délicates. Grâce à Composer, toute la gestion des ces dépendances va être prise en charge avec quelques lignes de commandes.

Pour pouvoir utiliser les commandes Composer sur votre serveur web en local ou sur votre serveur de production, il faudra commencer par l'installer. Une fois installé, Composer aura accès à tous les packages publiques de la communauté PHP mis à disposition par leurs développeurs et développeuses sur le site https://packagist.org.

La méthode d'installation dépend de votre système d'exploitation (Linux, Mac, Windows ...) et de la façon dont vous souhaitez l'installer, en local dans un projet ou globalement sur votre système d'exploitation. Généralement, par simplicité et pour ne le faire qu'une fois, nous choisissons l'installation globale mais si vous souhaitez tester différentes versions de Composer dans des projets distincts (par choix ou obligation) alors l'installation en local sera nécessaire.

Je ne vais pas détailler les différentes façons d'installer Composer ici, je vous renvoie donc sur le site officiel et plus particulièrement sur la page consacrée à l'installation de Composer.

Tout ce qui est répertorié sur le site https://packagist.org est installable dans un projet via des commandes Composer. Kirby CMS mais aussi le Starterkit et le Plainkit par exemple sont disponibles sur ce site et donc installables via Composer. Vous trouverez également de nombreux plugins Kirby et bien d'autres choses en lien avec Kirby.

Passons à la pratique !

Nous allons créer un simple dossier vide, par exemple /mon_projet, et y installer un package PHP pour observer ce qui se passe et commencer à utiliser des commandes Composer.

Dans votre terminal, placez-vous quelque part dans votre système de fichiers et créez un nouveau dossier /mon_projet

# Je suis sur Linux ...

# Je me place dans mon dossier /Documents
cd Documents

# Je créer un dossier /mon_projet
mkdir mon_projet

# Je me place dans le dossier /mon_projet
cd mon_projet

Maintenant que je suis dans mon dossier /mon_projet, je vais installer une librairie PHP qui me permet de générer des données factices, il s'agit de fakerphp/faker. (j'ai choisi cette librairie complètement au hasard, son utilité n'a pas d'importance ici).

# J'installe la librairie fakerphp/faker 
composer require fakerphp/faker

# Regardons ce qui a été généré dans mon dossier /mon_projet
ls
composer.json  composer.lock  vendor

La commande require utilisée ici permet d’installer et d’intégrer une librairie externe à son projet.

En executant cette commande, on observe que Composer à créé deux fichiers à la racine du dossier /mon_projet : composer.json et composer.lock et un dossier /vendor qui contient les fichiers et dossiers nécessaires pour pouvoir utiliser notre librairie "faker".

Ce fichier est très important et ne doit pas être supprimé car il indique à Composer la liste des dépendances installées dans votre projet ainsi que les versions actuelles de ces dépendances. C'est grâce à ce fichier que Composer sera en mesure de mettre à jour vos dépendances si besoin. C'est aussi grâce à ce fichier que Composer sera capable de tout ré-installer (nous verrons plus loin dans quel cas c'est utile).

Voici ce que contient notre fichier composer.json, on y retrouve la librairie fakerphp/faker ainsi que la version actuellement installée, ici la version v1.21.

# composer.json

{
    "require": {
        "fakerphp/faker": "^1.21"
    }
}

Si vous installez d'autres librairies dans votre projet, elles seront listées dans ce fichier composer.json

Lorsque Composer a fini d'installer les dépendances, il écrit tous les paquets et leurs versions exactes qu'il a téléchargés depuis https://packagist.org dans le fichier composer.lock.

Voici ce que contient notre fichier composer.lock, on y retrouve la librairie fakerphp/faker ainsi que la version actuellement installée, ici la version v1.21.0.

Comme vous pouvez l'observer, il y a beaucoup plus de précisions dans ce fichier et la version installée est également plus précise et explicite.

# composer.lock

"_readme": [
        "This file locks the dependencies of your project to a known state",
        "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#in>
        "This file is @generated automatically"
    ],
    "content-hash": "04a00e492ebc09eb702e633b8b16980b",
    "packages": [
        {
            "name": "fakerphp/faker",
            "version": "v1.21.0",
            "source": {
                "type": "git",
                "url": "https://github.com/FakerPHP/Faker.git",
                "reference": "92efad6a967f0b79c499705c69b662f738cc9e4d"
            },
            "dist": {
                "type": "zip",
                "url": "https://api.github.com/repos/FakerPHP/Faker/zipball/92e>
                "reference": "92efad6a967f0b79c499705c69b662f738cc9e4d",
                "shasum": ""
            },
            "require": {
                "php": "^7.4 || ^8.0",
                "psr/container": "^1.0 || ^2.0",
                "symfony/deprecation-contracts": "^2.2 || ^3.0"
            },
            "conflict": {
                "fzaninotto/faker": "*"
            },

... 
# Je ne met que le début de mon fichier ici mais il contient bien plus d'informations.

Alors à quoi sert ce fichier ?

Il permet à Composer de ré-installer les dépendances de votre projet avec exactement les mêmes packages et les mêmes versions que celles indiquées dans ce fichier. Si plusieurs personnes récupèrent votre projet et veulent ré-installer les dépendances avec Composer, le résultat sera constant entre ces différentes personnes. Tout le monde aura le même état du projet tel qu'il est décrit dans ce fichier composer.lock. Composer ne tiendra pas compte des packages mis à jour si ils sont disponibles sur https://packagist.org mais se tiendra aux versions indiquées dans sont fichier composer.lock

Si nous décidons ultérieurement de mettre à jour nos dépendances, le fichier composer.json et composer.lock seront mis à jour en conséquence.

Une fois la dépendance installée via Composer, vous pouvez utiliser ses "Classes" dans votre fichier PHP en faisant appel au fichier autoloader.php généré par Composer et présent à la racine du dossier /vendor

Ensuite, lisez la documentation de la dépendance sur https://packagist.org pour savoir comment l'utiliser dans votre projet.

# Un fichier PHP de mon projet

<?php

// require the autoload.php file
require_once 'vendor/autoload.php';


use Faker\Factory;

// use the factory to create a Faker\Generator instance
$faker = Factory::create();

// generate data by calling methods
echo $faker->name();

// 'Vince Sporer'
echo $faker->email();

// 'walter.sophia@hotmail.com'
echo $faker->text();

// 'Numquam ut mollitia at consequuntur inventore dolorem.'

Nous avons la possibilité de mettre à jour toutes les dépendances de notre projet en une seule fois ou de mettre à jour les dépendances individuellement.

# Mettre à jour toutes les dépendances d'un coup
composer update

# Mettre à jour une dépendance individuellement
coposer update fakerphp/faker

Pour supprimer une dépendance, c'est simple, nous utiliserons la commande remove suivi du nom du package :

# Supprimer une dépendance
composer remove fakerphp/faker

Les fichiers composer.json et composer.lock seront mis à jour en conséquence pour tenir compte de cette suppression.

Il est possible, grâce à Composer, d'initier l'installation d'un projet Kirby quelque part dans votre système de fichier. Pour cela, nous allons utiliser la commande Composer create-project

Cette commande va dans l'ordre :

1- Créer un dossier avec le nom que vous aurez choisi
2- Télécharger dans ce dossier tous les fichiers et dossiers du Starterkit ou du Plainkit
... qui sont, je le rappelle, des mini-projets de démarrage Kirby.

Exemple avec l'installation du Starterkit :

# Quelque part dans votre système de fichier
composer create-project getkirby/starterkit le_nom_de_mon_project

La commande Composer create-project va s'occuper de créer le dossier racine de votre projet. Ici un dossier le_nom_de_mon_project a été créé par Composer avec à l'intérieur tous les fichiers et dossiers du Starterkit ainsi qu'un dossier /vendor contenant les librairies que Kirby utilise. Les fichiers composer.json et composer.lock ont également été créés à la racine du dossier que vous avez indiqué dans la commande.

La commande Composer update permet de mettre à jour des dépendences. Pour mettre à jour Kirby CMS il faut remplacer le dossier /kirby de votre projet par la dernière version. Si vous avez utilisé Composer pour installer Kirby CMS dans votre projet, vous pouvez effectuer sa mise à jour de la façon suivante :

# Je m'assure, avant d'executer cette commande, d'être dans le dossier racine de mon projet
composer update getkirby/cms

Seul le dossier /kirby, qui contient les fichiers du "Core" de Kirby CMS, sera mis à jour. Composer ira chercher la dernière version disponible sur le site https://packagist.org.

Vous n'êtes pas obligé d'utiliser l'outil Composer pour installer/déployer un projet Kirby. Cependant si vous souhaitez introduire Composer dans votre process de mise à jour sur un projet Kirby existant, c'est possible.

Pour cela, suivez les étapes suivantes :

- Installez Composer sur votre serveur de développement et de production.
- Créez un fichier composer.json dans le dossier racine de votre projet Kirby (voir le contenu de ce fichier ci-dessous).
- Dans un terminal, placez-vous dans le dossier racine du projet Kirby puis executez la commande composer install

# composer.json minimum pour installer/mettre à jour Kirby version 3.x (ne prend pas en compte la mise à jour des plugins)

{
  "require": {
    "getkirby/cms": "^3.0"
  },
  "config": {
    "optimize-autoloader": true
  }
}

Composer se basera sur votre fichier composer.json pour générer le fichier composer.lock et créer le dossier /vendor

Par la suite, vous pourrez utiliser la commande composer update pour mettre à jour Kirby dans votre projet.

De nombreux plugins Kirby supportent l'installation et la mise à jour via Composer. Pour vous en assurer, regardez les instructions d'installation dans le fichier readme.md du dépot Git du plugin.

Si c'est le cas, l'installation du plugin se fait de la façon suivante (Composer est installé sur votre serveur) :

- Placez-vous dans le dossier racine de votre projet.
- Dans votre terminal, au niveau du dossier racine, executez la commande composer require <référence_du_plugin>

Exemple pour installer le plugin displaypages :

composer require rasteiner/k3-pagesdisplay-section

Les fichiers du plugin seront installés dans votre projet au niveau du dossier /plugins de kirby et les fichiers composer.json et composer.lock seront mis à jour pour tenir compte de cette installation.

Pour mettre à jour vos plugins soit vous le faite globalement avec la mise à jour de kirby grâce à la commande générique composer update, soit vous mettez à jour les plugins individuellement avec la commande composer update <référence_de_mon_plugin>

# Mise à jour globale des plugins (mettra aussi à jour Kirby)
composer update

# Mise à jour individuelle d'un plugin
composer update rasteiner/k3-pagesdisplay-section

Lorsque vous développez sur votre serveur locale ou votre serveur de développement, vous utiliserez un terminal pour executer les commandes Composer. C'est sur ces serveurs que vous effectuerez les mises à jours des dépendances composer update.

En revanche, sur votre serveur de production, il sera préférable d'automatiser l'execution de ces commandes lors de la phase de déploiement. Si vous décidez d'utiliser Composer, assurez-vous que votre hébergeur met à votre disposition Composer et la possibilité d'éxecuter des scripts de déploiement.

Généralement, ces systèmes de déploiement intègrent le gestionnaire de contrôle de version Git. Vous pushez votre code sur un dépôt Git distant, via un webhook, votre serveur de production reçoit l'information et récupère le code fraichement mis à jour depuis votre dépôt Git.

Lorsque vous utilisez Composer et l'outil de versionning Git, il est recommandé de mettre dans votre fichier .gitignore le dossier /vendor, le dossier /kirby et les dossiers contenant vos plugins Kirby pour alléger vos dépôts.

# Fichier .gitignore

...

# Ignorer le dossier /vendor de Composer
# ---------------------------------------

/vendor

# Ignorer le dossier /kirby
# --------------------------------------

/kirby

# Ignorer les dossiers des plugins Kirby
# ---------------------------------------

/plugins/pagesdisplay
...

Ces éléments pourront être réinstallés sur votre serveur de production lors des déploiements en automatisant l'éxecution de commandes Composer : composer install --optimize -autoloader . Cette commande va se baser sur le fichier composer.lock pour réinstaller votre projet dans le même état de mise à jour qu'il était sur votre serveur de développement.

Composer est un formidable outil pour gérer ses dépendances, installer et mettre à jour Kirby CMS et ses plugins. Cependant il est important de maîtriser un minimum son mode de fonctionnement pour résoudre les eventuels problèmes qui pourraient se présenter.

Nous avons ici effleuré les possibilités de Composer et vue des commandes fréquement utilisées. Pour en savoir plus sur Composer, je vous encourrage à consulter la documentation officielle et les nombreux tutoriels présents sur le web.

Il faut aussi avoir quelques notions CI/CD (distribution et déploiement continus) qui est une approche qui automatise le développement des applications en instaurant des éléments de surveillance tout au long de la phase d'intégration, de test et de déploiement. Cela sera utile pour automatiser l'execution des commandes Composer sur votre serveur de production lors des phases de déploiement et de mise à jour. Sachez que vous n'êtes pas toujours obligé de mettre les mains dans le cambouis. Certains hébergeurs ou outil comme RunCloud (gestionaire graphique de serveurs virtuels) peuvent vous faciliter la vie via des interfaces graphiques.