Section: Les fichiers de configuration
^ La configuration | Les répertoires de modules » |
− Table des matières
Une application Jelix possède quelques fichiers de configuration :
- un fichier
project.xml
, décrivant des informations générales sur l'application - un fichier
module.xml
dans chaque module - un fichier
mainconfig.ini.php
pour la configuration globale - un fichier
localconfig.ini.php
pour les paramètres propres à l'environnement (dev, prod..) - un fichier
config.ini.php
pour chaque point d'entrée. - un fichier
liveconfig.ini.php
pour les paramètres propres à l'environnement mais changés à la volé par l'application. - un fichier
profiles.ini.php
pour les profils de connexion. - un fichier
urls.xml
définissant la correspondance entre des URLs et des contrôleurs. - un fichier
framework.ini.php
listant les points d'entrées
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.
Excepté project.xml
et les fichiers module.xml
, les fichiers de
configuration sont situés dans app/system/
pour les paramètres généraux
(mainconfig.ini.php
, config.ini.php
, urls.xml
...),
ou var/config/
pour les paramètres qui dépendent de l'environnement
serveur (localconfig.ini.php
, profiles.ini.php
...).
Note : avant Jelix 1.7, ils étaient tous dans var/config/
).
Ce chapitre présente ces fichiers. Voyez le chapitre sur les details de la configuration pour en savoir plus sur le contenu.
Le fichier project.xml ¶
Le fichier project.xml
contient des informations sur l'application.
Voici un exemple :
<?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="2017-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>2017 Laurent Jouanneau</copyright>
<creator name="Laurent Jouanneau" email="laurent@jelix.org"/>
<homepageURL>http://jelix.org</homepageURL>
</info>
</project>
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 et surtout les dépendances avec d'autres modules. Elles permettent d'installer les modules dans le bon ordre.
Voici un exemple:
<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.7" maxversion="1.9.*" />
<module name="testurls" minversion="1.0.2" maxversion="1.1b1" />
<module name="jauthdb" />
<module name="jacl2db" />
<module name="jacldb" />
</dependencies>
</module>
Le fichier app/system/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 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 "/".
Le fichier app/system/framework.ini.php ¶
Ce fichier contient la liste des points d'entrées de l'application. Cette liste sert principalement à l'installateur.
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.
Le fichier de configuration du framework est le fichier app/system/mainconfig.ini.php
.
Cependant, on peut vouloir des paramètres différents pour chaque point
d'entrée, et aussi selon l'environnement. D'où des fichiers ini additionnels
qui sont fusionnés par Jelix au fichier mainconfig.ini.php à l'execution.
app/system/mainconfig.ini.php
¶
Ce fichier contient les paramètres de configuration communs à tous les points d'entrée ou environnements, et également les valeurs par défaut.
Exemple d'un fichier mainconfig.ini.php
(extrait) :
locale = "fr_FR"
charset = "ISO-8859-1"
timeZone = "Europe/Paris"
theme = default
[modules]
mymodule.enabled = on
jauth.enabled = on
[coordplugins]
;...
[responses]
;...
<entrypoint>/config.ini.php
¶
Il s'agit d'un fichier de configuration spécifique à un point d'entrée. Il 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.
Il peut y avoir un exemplaire dans app/system/
mais aussi dans
var/config
si il y a des paramètres propres à l'environnement
du serveur.
Pour les requêtes classiques, passant par index.php
, on pourrait avoir le
fichier app/system/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 app/system/
.
Dans ce fichier, on ne va redéfinir que certaines choses, comme par exemple :
[coordplugins]
autolocale = index/autolocale.ini.php
[responses]
html=myHtmlResponse
var/config/localconfig.ini.php
¶
Un fichier 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 mainconfig.ini.php
.
Bien entendu, en général, ce fichier n'est pas dans votre dépôt de code source.
var/config/liveconfig.ini.php
¶
Depuis Jelix 1.6.18, un fichier liveconfig.ini.php
permet de stocker les
paramètres qui sont modifiés durant la vie de l'application. Il ne doit donc pas
être stocké dans votre dépôt de code source. Les paramètres de ce fichier
"écrasent" ceux des autres fichiers mainconfig.ini.php
,
localconfig.ini.php
et celui du point d'entrée.
Comment sont-ils lu ? ¶
Il faut savoir qu'il existe un fichier defaultconfig.ini.php
,
situé dans les sources de Jelix (dans lib/jelix/core/
). Il contient une
liste exhaustive de tous les paramètres possibles, leurs valeurs par défaut et des
commentaires expliquant leur signification.
Ainsi, pour connaître la valeur de tous les paramètres de configuration, Jelix lit les fichiers dans l'ordre suivant et les fusionne :
lib/jelix/core/defaultconfig.ini.php
,app/system/mainconfig.ini.php
app/system/<entrypoint>/config.ini.php
var/config/localconfig.ini.php
var/config/<entrypoint>/config.ini.php
var/config/liveconfig.ini.php
Les valeurs contenues dans un fichier "écrasent" celles du fichiers précédent.
Pour chaque point d'entrée, le contenu résultant de cette fusion est mis en cache.
Utiliser des variables d'environnement ¶
Les fichiers ini sont lus par parse_ini_file
, et de ce fait les valeurs
qui s'y trouvent peuvent prendre différente forme :
- Vous pouvez indiquer des constantes PHP :
# quelque part dans un fichier inclus par votre index.php
define("SOMETHING", "hello world");
Un des fichiers ini de configuration :
foo = SOMETHING
Et foo vaudra donc "hello world"
.
- Vous pouvez indiquer des variables d'environnement.
# variables définies dans l'environnement de PHP-FPM, PHP-CLI, ou Apache (avec le module PHP)
MYAPP_MYSQL_LOGIN=admin
MYAPP_MYSQL_PASSWORD=Sup3Rp4ssw0rd!
Dans votre fichier profiles.ini.php (voir ci-après), il faut utiliser cette notation particulière :
[jdb:default]
driver=mysqli
login= ${MYAPP_MYSQL_LOGIN}
password= ${MYAPP_MYSQL_PASSWORD}
Le fichier var/config/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.
- *Important** : ce fichier contient nécessairement des logins/mot de passe et autres informations sensibles. Il ne doit pas être stocké dans un gestionnaire de code source !
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 :
[jdb:default]
driver=mysqli
login=
password=
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.
Notez aussi que vous pouvez indiquer des variables d'environnement pour les valeurs. Voir la section précédente.
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' :
[jdb]
jacl2_profile = default
[jdb:default]
driver=mysqli
login=
password=
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 à tous 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 :
[jdb:__common__]
host=my.server.example.com
persistant=on
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
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
createVirtualProfile
de l'objet 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 :
$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');
Les paramètres communs s'appliquent bien sûr sur les profils virtuels.