====== Utiliser Composer avec Jelix 1.7 ======

[[http://getcomposer.org|Composer]] est un gestionnaire de paquet pour PHP. Grâce à lui, vous pouvez installer des bibliothèques tierces facilement. Il gère également les dépendances.

Depuis Jelix 1.7, il est possible de créer un projet basé sur Jelix avec Composer, et d'installer le framework Jelix avec Composer. Dans la future version 2.0 du framework, la plupart des modules seront disponibles via Composer: les sources du framework seront plus légères et on pourra installer que ce que l'on a besoin. Pour le moment, le paquet Composer de Jelix 1.7 contient tous les composants et modules "standards" (comme dans les versions précédentes de Jelix).


Si vous ne voulez pas utiliser Composer, il est toujours possible de le faire. Voyez alors dans le manuel comment faire. Sinon, installez Composer avant de poursuivre.

Voici les différents cas d'utilisation de Jelix avec Composer.

===== Créer un nouveau projet =====

Une application développée avec Composer ne comporte normalement pas les bibliothèques tierces. C'est à dire que le code source de l'application, dans un dépôt git, subversion ou mercurial, ne contient pas le code source de ces bibliothèques tierces. Elles sont installées par Composer lors du déploiement de l'application (que ce soit en local pour développer ou sur un serveur de déploiement pour la mise en production).

Ainsi, une application utilisant le framework Jelix 1.7+ avec Composer, ne devrait pas inclure Jelix dans son code source, et indiquer plutôt le paquet Jelix dans le fichier composer.json de l'application. Composer installera alors les fichiers de Jelix (et autres bibliothèques) dans un dossier @@vendor/@@ (que [[https://getcomposer.org/doc/faqs/should-i-commit-the-dependencies-in-my-vendor-directory.md|vous ne devez donc pas inclure dans votre dépôt]] git/svn/hg).

Pour créer un nouveau projet, deux choix.

==== Utilisation du paquet jelix-skeleton-app ====

La manière la plus rapide de créer une nouvelle application basée sur Jelix est d'utiliser le paquet [[https://packagist.org/packages/jelix/jelix-skeleton-app|jelix/jelix-skeleton-app]]. Ce paquet contient une arborescence et les fichiers nécessaires pour réaliser une application avec une page.

Pour ce faire, si vous voulez créer une application "myapp", utilisant la version de développement de Jelix 1.7 :

```
composer create-project jelix/jelix-skeleton-app myapp dev-jelix-1.7
```

Composer vous demandera si vous voulez garder le repertoire @@F@.git@@. Répondez non.

Quelques fichiers ensuite à copier avant d'initialiser l'application :

<code bash>
ln -s ../vendor/jelix/jelix/lib/jelix-www www/jelix
cp var/config/profiles.ini.php.dist var/config/profiles.ini.php
cp var/config/localconfig.ini.php.dist var/config/localconfig.ini.php

php install/installer.php
</code>

Lancez ensuite un serveur web, par exemple celui fourni avec PHP (uniquement pour du développement !)

<code bash>
php -S localhost:8080 -t www 
</code>

Et votre application est prête (ici sur http://localhost:8080).


==== Utilisation de la commande createapp ====

L'autre façon de créer une application Jelix, est l'utilisation de la commande createapp, qui est présente depuis les premières versions de Jelix. Elle permet de créer un squelette d'application. C'est une alternative encore crédible au paquet jelix-skeleton-app car elle permet de personnaliser la création du squelette.

Dans ce cas de figure, il suffira alors :

  - de créer le répertoire de votre application (prenons myapp comme nom) et y mettre un fichier composer.json dont voici un exemple de contenu

<code json>
{
    "name": "myorganisation/myapp",
    "type": "application",
    "description": "Cool app",
    "require": {
        "php": ">=5.3.3",
        "jelix/jelix": "dev-jelix-1.7"
    },
    "require-dev": {
        "phpunit/phpunit": "4.3.*"
    },
    "minimum-stability": "dev"
}
</code>

Dans ce répertoire, on y exécute Composer pour installer les paquets indiqués dans le composer.json :

<code bash>
cd myapp
composer install
</code>

Et on peut lancer ensuite la création du squelette de l'application

<code bash>
php vendor/jelix/jelix/lib/jelix-scripts/createapp.php ../myapp
</code>

Puisque l'on utilise Composer, il faut ensuite modifier le fichier application.init.php pour charger @@F@../vendor/autoload.php@@ au lieu du classique @@F@lib/jelix/init.php@@.

<code php>
// require(__DIR__.'/vendor/jelix/jelix/lib/jelix/init.php'),
require(__DIR__.'/vendor/autoload.php');
</code>

Lancez ensuite un serveur web, par exemple celui fourni avec PHP (uniquement pour du développement !)

<code bash>
php -S localhost:8080 -t www 
</code>

Et votre application est prête (ici sur http://localhost:8080).

===== Utiliser le paquet Jelix 1.7 dans une appli Jelix existante =====

Si votre application n'a pas de fichier Composer.json, il faut en créer un. Dans tous les cas, il faut donc indiquer le paquet jelix.1.7.

Le composer JSON doit alors ressembler à ceci :

<code json>
{
    "name": "myorganisation/myapp",
    "type": "application",
    "description": "Cool app",
    "require": {
        "php": ">=5.3.3",
        "jelix/jelix": "dev-jelix-1.7"
    },
    "require-dev": {
        "phpunit/phpunit": "4.3.*"
    },
    "minimum-stability": "dev"
}
</code>

La version à indiquer est "dev-jelix-1.7" car Jelix 1.7 n'est pas encore sorti (d'où le  "minimum-stability" à "dev").

Faire ensuite un @@composer install@@ et Jelix 1.7 sera installé dans @@F@vendor/jelix/jelix/@@.

Vous pouvez ensuite supprimer le répertoire @@F@lib@@ de jelix 1.6, et changer le require dans le fichier @@F@application.init.php@@ pour qu'il charge le fichier @@F@autoload.php@ de composer plutôt que le @@F@init.php@ de Jelix directement.

<code php>
// require(__DIR__.'/../lib/jelix/init.php'); // pour jelix 1.6
require(__DIR__.'/vendor/autoload.php'); // pour jelix 1.7 avec Composer
</code>

Et il faut ensuite suivre bien sûr les instructions de migration de Jelix 1.6 vers Jelix 1.7. Voir le manuel de Jelix 1.7.


===== Installer des paquets tiers =====

Il peut être nécessaire d'utiliser des bibliothèques tierces. La plupart sont disponibles via Composer. Il suffit de rechercher leur nom exact sur [[http://packagist.org]], de connaitre la version que l'on veut, et d'indiquer ces informations dans la section @@"require"@@ du fichier composer.json du projet. Ensuite un coup de @@composer update@@ et la bibliothèque sera prête à être utiliser dans votre application.

Si le paquet en question est un module Jelix, vous allez en plus devoir le déclarer dans la configuration de Jelix. Si par exemple le module "foo" se trouve dans vendor/the_vendor/the_package/foo, il faudra mettre dans le mainconfig.ini.php :

<code ini>

modulePath="<ici autres chemins>,app:vendor/the_vendor/the_package/"

[modules]
foo.access=2
</code>

Sans oublier ensuite de relancer l'initialisation de l'application :

<code bash>
php install/installer.php
</code>

===== Développer une application et des modules séparément =====

Il arrive que l'on développe une application qui utilise des modules externes (utilisés par d'autres projets) que l'on a soit-même développé ou auxquels on contribue. Et que l'on veuille dans le même temps améliorer le code de ces modules externes. 

On aurait donc une application dans un dépôt git, et les autres modules dans d'autres dépôt git. L'application aurait son composer.json référençant les paquets de ces modules, et donc au final un répertoire @@vendor/@@ contenant les fichiers de ces modules.

Cependant, installer ces modules avec Composer impose que l'on commit les modifications dans leurs dépôts respectifs. Cela veut dire qu'il va certainement falloir commiter à de nombreuses reprises lors du debuggage et la mise au point. De quoi "pourrir" l'historique du dépôt des modules. Et de nombreux "Composer update" en ligne de commande...

On peut bien sûr limiter ces commits en écrivant des tests unitaires dans les dépôts des modules, mais cela n'est pas toujours suffisant : on ne peut pas tester l'intégration du module dans une application... sans application.

La solution est donc la suivante.

   * Dans le composer JSON, vous indiquez non pas une version stable du paquet d'un module, mais sa branche de développement ("dev-quelquechose"). Vous avez alors, dans le répertoire du module dans @@F@vendor/@@, un clone Git du projet du module, et non pas uniquement ses sources (C'est une des raisons d'ailleurs pour laquelle il ne faut jamais inclure le répertoire vendor).
   * Vous pouvez alors faire des modifications dans les sources du module (dans vendor/), les tester avec votre application, et commiter dans le dépôt du module comme à votre habitude, quand les modifications sont terminées, en tenant compte des informations suivantes :
       * Dans le dépôt du module (dans vendor/), vous remarquerez que deux "remote" sont déclarés : "composer" et "origin". Il faut travailler sur une branche issue de "origin": le push sera facilité
       * **Attention** : ne manipulez pas Composer tant que vous n'avez rien commité et poussé sur les dépôts d'origine, en particulier si d'autres personnes sont susceptibles de commiter dans le dépôt d'origine. Un "composer update" pourrait écraser vos modifications ou vos commits locaux. Si vous avez vraiment besoin de faire un "composer update" et qu'il est succeptible d'avoir des nouveaux commits distant, travaillez alors sur une nouvelle branche locale : Composer n'y touchera pas.
   * Enfin, une fois que le module est stable, vous mettrez un tag de version (ex: v1.0) dans le dépôt du module.

Une fois que votre module et votre application sont "stables", vous changerez alors la version du module dans le composer.json de l'application, en indiquant le numéro de version stable du module.