====== Utiliser Composer avec une instance Simple Hosting PHP ======

Ce tutoriel décrit comment utiliser [[https://getcomposer.org/|Composer]], le très populaire gestionnaire de dépendances de PHP,
sur une instance [[https://wiki.gandi.net/en/simple/instance/php|Simple Hosting PHP]].

Ce tutoriel couvre l'ensemble d'un projet avec Composer, depuis la création de l'instance à l'ouverture de la page web dans votre navigateur,
en passant par l'écriture du code, l'installation et l'utilisation de Composer.

Vous travaillerez à partir de l'interface en ligne de commande de votre ordinateur, d'où vous exécuterez l'ensemble des opérations. Certaines commandes utilisent Gandi CLI, notre outil maison qui facilite l'utilisation des produits Gandi à partir d'un Terminal. Tous les exemples proposent aussi des commandes alternatives, qui ne demandent pas l'utilisation de Gandi CLI.

==== Qu'est qu'un Gestionnaire de dépendances =====

Un gestionnaire de dépendances est un outil facilitant l'inclusion de code externe (dépendances) à un projet. C'est particulièrement pratique lorsque ces dépendances incluent elles-mêmes des dépendances.

Afin d'éviter la copie de plusieurs fichiers à la main (avec possibilité de doublon), un gestionnaire de dépendances tel que Composer fourni un outil simple permettant de lister les dépendances dans un fichier, pour lancer une commande qui les télécharge et installe pour vous.

En complément, les gestionnaires de dépendances populaires attirent un nombre croissant de développeurs qui choisissent de publier des librairies compatibles, facilitant leur l'adoption par les utilisateurs. En résulte, pour les développeurs modernes, une grande quantité de librairies de bonne qualité, prêtes à l'usage.

===== Pré-requis ======

Pour ce tutoriel, vous aurez besoin de : 

  * Un [[https://www.gandi.net/contact/create|compte Gandi]]
  * Un code promo, un moyen de paiement accepté ou suffisamment de fonds sur votre compte Prépayé pour acheter une [[https://www.gandi.net/hebergement/simple|instance Simple Hosting]]
   * [[http://cli.gandi.net|Gandi CLI]] version 0.17 ou supérieure (usage de Gandi CLI optionnel mais recommandé)

===== Débutons =======

Commencez par créer le dossier du projet sur votre ordinateur.

    ~ $ mkdir gstatus
    ~ $ cd gstatus
    ~/gstatus $ git init .
    ~/gstatus $ mkdir htdocs

====== Installation de Composer ======

Composer fourni un script d'installation automatisé que vous pouvez exécuter directement à partir de la ligne de commande.

Copiez-Collez la commande suivante dans votre Terminal pour créer le fichier "composer.phar" à la racine du site/vhost.

  ~/gstatus $ php -r "readfile('https://getcomposer.org/installer');" | php

Vous pouvez désormais exécuter ce fichier avec 'php' pour obtenir les instructions d'utilisation et vérifier l'installation.

  ~/gstatus $ php composer.phar

======== Ecriture de l'application ===========

L'application utilisée dans cet exemple tient en un seul fichier de 30 lignes, contenant du code PHP et HTML. Lorsque la page est chargée, le script PHP effectue une requête HTTP vers l'API de Statut de Gandi et récupère l'état actuel des services. La page affiche alors un text détaillant le statut, ainsi qu'un lien pour obtenir plus d'informations.

====== Déclarer et installer les dépendances ======

Au lieu d'écrire la requête HTTP à la main, vous utiliserez Guzzle, une librairie facilitant l'écriture et la manipulation de requêtes. Guzzle est disponible à travers Composer, donc vous pouvez déclare cette dépendance dans un fichier "composer.json", que vous allez créer à la racine du site/vhost.

**NB**: Avec PHP 5.4, vous aurez besoin de la version 5 de Guzzle plutôt que de la version 6.

  ~/gstatus $ vim composer.json

  {
    "require": {
      "guzzlehttp/guzzle": "~6"
    }
  }

Maintenant, lancez la commande Composer pour l'installation :

  ~/gstatus $ php composer.phar install

Les dépendances de l'application, en l'occurrence Guzzle et ses propres dépendances, sont désormais installées dans le dossier "vendor" de votre projet.

Vous noterez également que Composer à créé un fichier "composer.lock" dans ce dossier. Ce fichier contient les versions exactes des librairies qui ont été téléchargées par Composer, et qui seront les mêmes qui seront utilisées par l'instance Simple Hosting.

======== Création du fichier index.php =====

Votre code consistera en un simple fichier, ''index.php''. Il contient une fonction "getGandiStatus()" qui récupère le statut actuel des services Gandi à partir de l'API Satut, appelée par une fonction "currentStatus()" qui retourne les résultats en une phrase lisible par un humain.

Ensuite, un peu HTML produira une page web minimaliste pour, avec un peu PHP imbriqué, afficher la phrase résultant de la fonction "currentStatus()".

Pour inclure la librairie Guzzle, vous utiliserez l'instruction 'require' standard de Composer, qui sert à inclure toutes les dépendances gérées par l'outil.

  ~/gstatus $ cd htdocs/

  ~/gstatus/htdocs $ vim index.php

  <?php
    require '../vendor/autoload.php';
  
    function getGandiStatus() {
      $client = new GuzzleHttp\Client();
      $res = $client->get('https://status.gandi.net/api/status');
      $gandi_status = json_decode($res->getBody(), true);
      return $gandi_status["status"];
    };
  
    function currentStatus() {
      switch(getGandiStatus()) {
        case "SUNNY": return "All Gandi services are operational";
        default: return "Gandi is experiencing a bit of trouble";
      };
    };
  ?>
  <html>
    <head>
      <title>Gandi Status Check</title>
    </head>
    <body>
      <h1><?php echo currentStatus(); ?></h1>
      <p><a href="http://status.gandi.net">More info</a></p>
    </body>
  </html>


===== Commit au dépôt Git =====

Votre application est désormais presque complète et vous pouvez sauvegardez vos changements sur Git.

====== Création d'un fichier .gitignore =====

Créez un fichier ".gitignore" à la racine de votre projet pour obliger Git à ignorer l'exécutable de Composer (composer.phar), ainsi que le dossier "vendor" où Composer installe les dépendances.

  ~/gstatus/htdocs $ cd ..
  ~/gstatus $ vim .gitignore

  composer.phar
  vendor

===  Git "commit" et "add" des fichiers à l'arbre ====

Vous pouvez désormais ajouter les autres fichiers ("stage") à l'arbre Git et enregistrer vos changements avec "commit".

  ~/gstatus $ git add .
  ~/gstatus $ git commit -m 'First commit'

===== Création d'une instance Simple Hosting =======

Vous pouvez facilement créer une instance Simple Hosting à partir du site web de Gandi et l'administrer à partir de sa page de gestion.

Nous n'utilisons pas de base de données dans ce projet d'exemple, mais vous pouvez sélectionner une instance de type PHP avec le serveur de base de données de votre choix.

Pour créer votre instance avec Gandi CLI, exécutez la commande suivante dans votre terminal :

    ~/gstatus $ gandi paas create gstatus --type phpmysql --size S --datacenter LU-BI1
    Password:

Cela va initier le processus de création qui devrait prendre une minute pour se finaliser si vous avez suffisamment de crédit sur le compte Prépayé. Dans le cas contraire, vous pourrez noter que cela prend trop de temps ou échoue. Connectez-vous alors à l'interface web pour effectuer le paiement et les opérations se finaliseront ensuite.

====== Configurer le dépôt Git distant =======

Les instances Simple Hosting PHP disposent d'une dépot Git par VHOST. Elles sont d'ailleurs pré-configurés avec un VHOST correspondant à une URL de test fournie par Gandi. Dans cet exemple, vous déploierez le code dans ce VHOST et l'application sera accessible à cette URL de test.

En utilisant Gandi.cli, vous pouvez récupérer le VHOST et l'utiliser pour ajouter un "remote" à votre dépôt local.

  ~/gstatus $ gandi paas info gstatus | grep vhost
  vhost      : 1234567890.testurl.ws

  ~/gstatus $ gandi paas attach gstatus --vhost 1234567890.testurl.ws

Sans Gandi.cli, vous pouvez accéder à la page de gestion de l'instance pour récupérer l'URL du dépot Git et du VHOST. Vous pourrez ensuite exécuter la commande suivante, en remplaçant par les bonnes valeurs les champs entre parenthèses:

  ~/gstatus $ git remote add gandi ssh+git://{login}@git.{datacenter_id}.gpaas.net/{vhost}.git

==== Push du code =====

Après avoir ajouté le dépôt distant "gandi", vous pouvez simplement pousser votre code sur la branche 'master' :

  ~/gstatus $ git push gandi master

===== Deploy du code ======

Il est maintenant nécessaire de checkout les fichiers du dépôt de votre VHOST dans le dossier du VHOST de l'instance. Le script "deploy" se charge de cette opération et va aussi exécuter Composer et installer les dépendances de votre application dans le processus.

Pour lancer le script de déploiement avec Gandi.cli, exécutez simplement la commande suivante :

  ~/gstatus $ gandi deploy

La méthode alternative consiste à exécuter la commande deploy directement via SSH. Utilisez l'exemple suivant et remplacez les champs entre parenthèses par les mêmes valeurs utilisées pour créer le "remote" dans votre dépôt git.

  ~/gstatus $ ssh {login}@git.{datacenter_id}.gpaas.net 'deploy 1234567890.testurl.ws.git'

Le script de déploiement est assez verbeux et vous permettra de suivre l'avancement du déploiement. Une fois le déploiement finalisé, votre code sera sur l'instance et accessible via le Web.

===== Ouvrir dans son navigateur =====

Vous pouvez maintenant visiter l'URL de votre VHOST pour vérifier que l'application s'exécute sur votre instance Simple Hosting : http://1234567890.testurl.ws

Vous devriez pouvoir consulter le statut des services Gandi. Félicitations :)