configuration.gtw

~~LANG:EN@enman:config~~

Une application Jelix possède quelques fichiers de configuration :

  * un fichier @@F@project.xml@@, décrivant des informations générales sur
    l'application
  * un fichier @@F@module.xml@@ dans chaque module
  * un fichier @@F@mainconfig.ini.php@@ pour la configuration globale
  * un fichier @@F@localconfig.ini.php@@ pour les paramètres propres à l'environnement (dev, prod..)
  * un fichier @@F@config.ini.php@@ pour chaque point d'entrée.
  * un fichier @@F@profiles.ini.php@@ pour les profils de connexion.
  * un fichier @@F@urls.xml@@ définissant la correspondance entre des URLs
    et des contrôleurs.

Ils sont tous générés automatiquement lorsque vous créez une application ou un
module. Cependant, vous devez bien souvent les modifier pour apporter des
renseignements supplémentaires ou changer des paramètres.

Ce chapitre présente ces fichiers. Voyez [[details-configuration|le chapitre sur les details de la configuration]]
pour en savoir plus sur le contenu.

===== Le fichier project.xml =====

Le fichier @@F@project.xml@@ contient des informations sur l'application, dont
certaines sont importantes puisqu'elles servent à l'installateur, entre autres.
Voici un exemple :

<code xml>
<?xml version="1.0" encoding="iso-8859-1"?>
<project xmlns="http://jelix.org/ns/project/1.0">
    <info id="testapp@jelix.org" name="testapp" createdate="2015-01-01">
        <version>1.3</version>
        <label lang="en_US">Testapp</label>
        <description lang="en_US">Application to test Jelix</description>
        <licence URL="http://www.gnu.org/licenses/gpl.html">GPL</licence>
        <copyright>2005-2016 Laurent Jouanneau and other contributors</copyright>
        <creator name="Laurent Jouanneau" email="laurent@jelix.org" />
        <homepageURL>http://jelix.org</homepageURL>
    </info>
    <dependencies>
       <jelix minversion="1.7" maxversion="1.7.*" />
    </dependencies>
    <entrypoints>
        <entry file="index.php" config="index/config.ini.php" />
        <entry file="soap.php" config="soap/config.ini.php" type="soap"/>
    </entrypoints>
</project>
</code>

===== Les fichiers module.xml =====

Un fichier module.xml doit se trouver dans chacun des répertoires de module. Il
contient des informations générales, mais aussi les dépendances avec d'autres
modules. Voici un exemple:

<code xml>
<module xmlns="http://jelix.org/ns/module/1.0">
    <info id="jelix_tests@testapp.jelix.org" name="jelix_tests">
        <version>1.0</version>
        <label>Jelix tests</label>
        <description>unit tests for jelix</description>
    </info>
    <dependencies>
        <jelix minversion="1.6" maxversion="1.7.*" />
        <module name="testurls" minversion="1.0.2" maxversion="1.1b1" />
        <module name="jauthdb" />
        <module name="jacl2db" />
        <module name="jacldb" />
    </dependencies>
</module>
</code>

===== Le fichier urls.xml =====

Il définit la correspondance entre des URLs et des contrôleurs.

Il n'est pas obligatoire de déclarer les urls pour chaque contrôleurs/méthodes
mais cela peut être indispensable pour avoir des urls sympas, autre que
@@index.php/mon_module/mon_controleur/ma_methode@@.

Voir [[urls|le chapitre qui lui est dédié]].

Note : avant Jelix 1.7, ce fichier était facultatif, suivant le moteur d'urls
que l'on utilisait. Depuis Jelix 1.7, il n'y a plus de plugins de moteur d'urls,
et ce fichier devient donc obligatoire. Il doit déclarer au moins l'url "/".

===== Les fichiers de configuration ini =====

La configuration du framework est stockée dans un fichier de type "ini". Il
s'agit d'un fichier contenant des sections, débutant par un nom entre crochets.
Chacune de ces sections contenant une série de paramètres "nom=valeur". Il y a
une section "générale", qui n'a pas de nom, et dont les paramètres sont en début
du fichier.

Les fichiers de configuration sont situés dans @@F@var/config/@@.


=== mainconfig.ini.php ===

Chaque point d'entrée peut avoir son fichier de configuration spécifique. Mais la plupart
du temps ils ont beaucoup de valeurs de paramètres identiques entre eux. Pour éviter de
répéter ces paramètres identiques dans chaque fichier, il y a un fichier de configuration
commun, qui a pour nom @@F@mainconfig.ini.php@@. Il est automatiquement lu, en plus du
fichier spécifique au point d'entrée, et il n'est pas besoin de l'indiquer dans les points
d'entrée.

=== localconfig.ini.php ===

Depuis Jelix 1.6, un fichier @@F@localconfig.ini.php@@ est pris en charge. Il est censé
contenir la configuration propre à la machine locale, donc différent en fonction
de l'environnement : developpement, production, tests... Les paramètres
de ce fichier "écrasent" ceux de @@F@mainconfig.ini.php@@. Bien entendu, en général
ce fichier n'est pas dans votre dépot de code source.

=== <entrypoint>/config.ini.php ===

Un fichier de configuration spécifique ne contiendra donc que les valeurs
spécifiques pour le point d'entrée, et peut bien sûr redéfinir des paramètres
définis dans le fichier commun.

Exemple d'un fichier @@F@mainconfig.ini.php@@ (extrait) : 

<code ini>
locale = "fr_FR"
charset = "ISO-8859-1"
timeZone = "Europe/Paris"
theme = default

[modules]
mymodule = 2
jauth = 2


[coordplugins]
;nom = nom_fichier_ini

[responses]
...

</code>

Pour les requêtes classiques, passant par @@F@index.php@@, on pourrait avoir le
fichier @@F@var/config/index/config.ini.php@@. On le met ici dans un
sous-répertoire index pour une meilleure organisation (il peut en effet y avoir
des fichiers de configuration de plugins propres à chaque point d'entrée, ça
peut donc vite devenir peu lisible dans @@F@var/config/@@).

Dans ce fichier, on ne va redéfinir que certaines choses :

<code ini>

[coordplugins]
autolocale = index/autolocale.ini.php

[responses]
html=myHtmlResponse
</code>

Pour le fichier de configuration de xmlrpc.php, on pourrait ne rien avoir par exemple.

etc.


=== Comment sont-ils lu ===

Il faut savoir qu'il existe un fichier @@F@defaultconfig.ini.php@@,
situé dans le répertoire @@F@lib/jelix/core/@@. Il contient une liste exhaustive
de tous les paramètres possibles.

Ainsi, pour connaître la valeur de tous les paramètres de configuration, Jelix lit les fichiers
dans l'ordre suivant et les fusionne :

  - @@F@lib/jelix/core/defaultconfig.ini.php@@,
  - @@F@mainconfig.ini.php@@
  - @@F@localconfig.ini.php@@
  - @@F<entrypoint>/config.ini.php@@

Les valeurs contenues dans un fichier "écrasent" celles du fichiers précédent.

Pour chaque point d'entrée, le contenu résulant de cette fusion est mis en
cache.


===== Le fichier profiles.ini.php =====

Ce fichier contient tous les paramètres de connexions de certains composants de
Jelix : base de données SQL, NOSQL, services web, cache etc.

C'est un fichier au format ini. Chaque section correspond à un profil, un profil
étant les paramètres d'une connexion. Les noms des sections sont composés de
deux noms séparés par ":":

   * Le premier nom est le nom d'un type de connexion (correspondant au
     composant qui l'utilise)
   * Le deuxième est le nom du profil, choisi par vous même. Deux noms ont une
     signification spéciale. Le nom de profil "default" qui est le profil par
     défaut utilisé quand on n'indique pas de profil au composant. Et le nom
     "__common__".

Le contenu de la section contient les paramètres de connexions.

Exemple, d'un profil de connexion pour jDb, le composant d’accès aux bases de
données :

<code ini>
[jdb:default]
driver=mysqli
login=
password=
</code>


Note: le contenu du fichier profiles.ini.php est analysé et complété par
des plugins, et le résultat est mis en cache pour améliorer les performances.

=== Alias de profil ===

Vous pouvez définir des alias de profils. C'est à dire donner plusieurs noms à
un profil. C'est utile par exemple si un module utilise un nom de profil
particulier. Il est alors possible d'indiquer que ce nom de profil soit rattaché
à un profil existant.

Les alias sont définis dans une section dont le nom contient uniquement le nom
du type de connexion.

Un exemple pour jDb, en définissant un alias 'jacl2_profile' :

<code ini>
[jdb]
jacl2_profile = default

[jdb:default]
driver=mysqli
login=
password=

</code>

Un alias ne doit pas indiquer le nom d'un autre alias.

=== Paramètres communs ===

Il est possible de définir des paramètres qui sont communs à tout les profils
d'un même type. Cela évite de les répéter dans chaque profil. Pour ce faire, il
faut les déclarer dans un profil spécial, @@__common__@@.

Par exemple, si toutes les connexions aux bases de données SQL (jDb) doivent
être persistantes et se font toutes sur le même serveur :

<code ini>
[jdb:__common__]
host=my.server.example.com
persistant=on
</code>

Vous pouvez bien sûr redéfinir ces paramètres dans les profils, pour les
exceptions.

=== Profil virtuel ===

Vous pouvez utiliser un profil qui n'existe pas dans le fichier
@@F@profiles.ini.php@@. Cela permet d'utiliser une connexion dont on ne connaît
pas les caractéristiques à l'avance.

Pour cela, avant d'appeler les différentes méthodes du composant concerné, il
vous faut déclarer ce profil "virtuel". Vous appellerez alors la méthode
@@M@createVirtualProfile@@ de l'objet @@C@jProfiles@@ qui gère les profils. À
cette méthode, vous donnerez le type de profil, un nom de profil, ainsi qu'un
tableau de paramètres de connexion.

Exemple :

<code php>
   $params = array(
       'driver'=>'mysqli',
       'host'=>'localhost',
       'database'=>'jelix',
       'user'=>'toto',
       'password'=>'blabla',
       'persistent'=>false,
       'force_encoding'=>true
   );
   jProfiles::createVirtualProfile('jdb', 'mon_profil', $params);

   $cnx = jDb::getConnection('mon_profil');

</code>


Les paramètres communs s'appliquent bien sûr sur les profils virtuels.