Configuration de l'application – Using Zend Framework 3

Translation into this language is not yet finished. You can help this project by translating the chapters and contributing your changes.

3.8. Configuration de l'application

La plupart des composants Zend Framework utilisés sur votre site web nécessitent une configuration. Par exemple, dans le fichier de configuration, vous définissez les informations d'identification de connexion à la base de données, spécifiez les modules présents dans votre application et, facultativement, fournissez des paramètres personnalisés spécifiques à votre application.

Vous pouvez définir les paramètres de configuration à deux niveaux : au niveau de l'application ou au niveau du module. Au niveau de l'application, vous définissez généralement les paramètres qui contrôlent l'application entière et sont communs à tous les modules de votre application. Au niveau du module, vous définissez des paramètres qui affectent uniquement ce module.

Certains frameworks PHP préfèrent les conventions au concept de configuration, où la plupart de vos paramètres sont codés en dur et ne nécessitent aucune configuration. Cela accélère le développement de l'application, mais la rend moins personnalisable. Dans Zend Framework 3, le concept de configuration sur conventions est utilisé, vous pouvez donc personnaliser n'importe quel aspect de votre application mais vous devez prendre le temps d'apprendre à le faire.

3.8.1. Fichiers de configuration au niveau de l'application

Le sous-dossier APP_DIR/config contient des fichiers de configuration à l'échelle de l'application. Regardons ce sous-dossier plus en détail (figure 3.4).

Figure 3.4. Fichiers de configuration

Le fichier APP_DIR/config/application.config.php est le fichier de configuration principal. Il est utilisé par l'application au démarrage pour déterminer les modules d'application à charger et les services à créer par défaut.

Ci-dessous, le contenu du fichier application.config.php est présenté. Vous pouvez voir que le fichier de configuration est juste un tableau associatif imbriqué et que chaque composant peut avoir une clé spécifique dans ce tableau. Vous pouvez fournir des commentaires en ligne pour les clés du tableau afin de permettre aux autres de mieux comprendre ce que chaque clé signifie.

Par convention, les noms de clé doivent être en minuscules et si le nom de clé est constitué de plusieurs mots, les mots doivent être séparés par le symbole underscore ('_').

return [
    // Récupère la liste des modules utilisés dans cette application.
    'modules' => require __DIR__ . '/modules.config.php',

    // Ce sont différentes options pour les écouteurs attachés au ModuleManager
    'module_listener_options' => [
        // Doit être un tableau de chemins dans lequel les modules résident.
        // Si une clé est fournie, l'écouteur considérera que c'est le namespace
        // d'un module, la valeur de cette clé est le chemin spécifique de ce module.
        // Module class.
        'module_paths' => [
            './module',
            './vendor',
        ],

        // Un tableau de chemins à partir duquel globaliser les fichiers de configuration
        // après le chargement des modules. Ils remplacent la configuration fournie
        // par les modules eux-mêmes. Les chemins peuvent utiliser la notation GLOB_BRACE.
        'config_glob_paths' => [
            realpath(__DIR__) . '/autoload/{{,*.}global,{,*.}local}.php',
        ],

        // Active ou non un cache de configuration.
        // Si activé, la configuration fusionnée sera mise en cache et
        // utilisée dans les requêtes suivantes.
        'config_cache_enabled' => true,

        // La clé utilisée pour créer le nom du fichier de cache de configuration.
        'config_cache_key' => 'application.config.cache',

        // Activer ou non un cache de class map de module.
        //  Si activé, crée un cache de class map  de module qui sera utilisé par les
        // futures requêtes, afin de réduire le processus de chargement automatique.
        'module_map_cache_enabled' => true,

        // La clé utilisée pour créer le nom du fichier de cache du class map.
        'module_map_cache_key' => 'application.module.cache',

        // Le chemin dans lequel mettre en cache la configuration fusionnée.
        'cache_dir' => 'data/cache/',

        // Active ou non la vérification des dépendances des modules.
        // Activé par défaut, empêche l'utilisation des modules qui dépendent
        // d'autres modules  qui n'ont pas été chargés.
        // 'check_dependencies' => true,
    ],

    // Utilisé pour créer un propre gestionnaire de services.
    // Peut contenir un ou plusieurs tableaux enfants.
    //'service_listener_options' => [
    //     [
    //         'service_manager' => $stringServiceManagerName,
    //         'config_key'      => $stringConfigKey,
    //         'interface'       => $stringOptionalInterface,
    //         'method'          => $stringRequiredMethodName,
    //     ],
    // ],

   // Configuration initiale avec laquelle lancer le ServiceManager.
   // Doit être compatible avec Zend\ServiceManager\Config.
   // 'service_manager' => [],
];

A la ligne 3, nous avons la clé des modules qui définit quels modules seront chargés au démarrage. Vous pouvez voir que les noms des modules sont stockés dans un autre fichier de configuration modules.config.php, qui répertorie tous les modules présents sur votre site web.

Ligne 11, il y a la clé module_paths qui indique à ZF3 dans quels dossiers chercher les fichiers source appartenant aux modules. Les modules de l'application que vous développez se trouvent dans le dossier APP_DIR/module et les modules tiers se trouvent dans le dossier APP_DIR/vendor.

Et à la ligne 19, nous avons la clé config_glob_paths qui indique à ZF3 où chercher les fichiers de configuration supplémentaires. Vous voyez que les fichiers de APP_DIR/config/autoload qui ont un suffixe global.php ou local.php sont automatiquement chargés.

Pour résumer, vous utilisez généralement le fichier principal application.config.php pour stocker les informations sur les modules qui doivent être chargés dans votre application, où ils se trouvent et comment ils sont chargés (par exemple, vous pouvez contrôler les options de mise en cache). Dans ce fichier, vous pouvez également paramétrer le gestionnaire de service. Il n'est pas recommandé d'ajouter plus de clés dans ce fichier. Il vaut mieux alors utiliser le fichier autoload/global.php.

Jetons aussi un oeil au fichier modules.config.php. Actuellement, les modules suivants sont installés sur votre site web :

return [
    'Zend\Session',
    'Zend\Mvc\Plugin\Prg',
    'Zend\Mvc\Plugin\Identity',
    'Zend\Mvc\Plugin\FlashMessenger',
    'Zend\Mvc\Plugin\FilePrg',
    'Zend\Form',
    'Zend\Router',
    'Zend\Validator',
    'Application',
];

Le module Application est un module contenant les fichiers de votre application. Tous les autres modules répertoriés sont des composants Zend Framework.

Dans ZF3, un plugin Composer spécial appelé component installer a été introduit. Si vous vous souvenez, dans le chapitre Zend Skeleton Application, nous avons répondu à plusieurs questions oui/non de l'installateur, en déterminant les composants à installer. Et le programme d'installation a injecté les noms des modules de ces composants ici, dans modules.config.php.

3.8.2. Fichiers de configuration supplémentaires au niveau de l'application

Les fichiers de configuration "suplémentaires" : APP_DIR/config/autoload/global.php et APP_DIR/config/autoload/local.php définissent respectivement les paramètres indifférents à l'environnement et dépendants de l'environnement de l'application. Ces fichiers de configuration sont automatiquement chargés et fusionnés avec les fichiers de configuration fournis par le module, c'est pourquoi leur répertoire est nommé autoload.

En ayant différents fichiers de configuration dans le dossier APP_DIR/config/autoload vous pourriez être perdus quant aux paramètres qui doivent être placés dans chacun d'entre eux. Voici quelques conseils :

Vous utilisez le fichier autoload/global.php pour stocker les paramètres qui ne dépendent pas de l'environnement de la machine. Par exemple, vous pouvez stocker ici les paramètres qui remplacent les paramètres par défaut de certains modules. Ne stockez pas d'informations sensibles (comme les informations d'identification de la base de données), dans ce cas là, il vaut mieux utiliser autoload/local.php.
Vous utilisez le fichier autoload/local.php pour stocker les paramètres spécifiques à l'environnement utilisé. Par exemple, vous pouvez stocker ici vos informations d'identification de base de données. Chaque développeur a généralement une base de données locale lors du développement et du test du site web. Le développeur va donc éditer le fichier local.php et entrer ses propres références de base de données. Lorsque vous installez votre site sur le serveur de production, vous modifiez le fichier local.php et entrez les informations d'identification de la base de données "de prod".

Comme le fichier autoload/local.php contient des paramètres spécifiques à l'environnement, dans le système de contrôle de version, vous stockez son "modèle de distribution" local.php.dist. Chaque développeur de votre équipe renomme alors le fichier local.php.dist en local.php et entre ses propres paramètres. Ce fichier local.php ne doit pas être stocké sous le contrôle de version car il peut contenir des informations sensibles telles que les informations d'identification de la base de données (nom d'utilisateur et mot de passe) et vous ne souhaitez peut-être qu'elles soient connus par d'autres personnes.

3.8.3. Fichier de configuration de développement au niveau de l'application

Le fichier de configuration de développement au niveau de l'application (APP_DIR/config/development.config.php) entre en jeu uniquement lorsque vous activez le mode développement. Si vous vous en souvenez, nous avons activé le mode développement plus tôt dans le chapitre Zend Skeleton Application.

Vous activez le mode développement avec la commande suivante :

php composer.phar development-enable

Le fichier development.config.php est fusionné avec le fichier principal application.config.php. Cela vous permet de remplacer certains paramètres. Par exemple, vous pouvez :

désactiver la mise en cache de la configuration. Lorsque vous développez votre site, vous modifiez fréquemment vos fichiers de configuration, la mise en cache de la configuration peut avoir des conséquences indésirables, telles que l'impossibilité de voir immédiatement le résultat de vos modifications.
charger des modules supplémentaires. Par exemple, vous pouvez charger le module ZendDeveloperTools uniquement en mode développement.

Si vous désactivez le mode de développement, le fichier development.config.php sera supprimé. Donc, vous ne devriez pas stocker ce fichier sous le contrôle de version. Au lieu de cela, stockez sa version de distribution development.config.php.dist sous le contrôle de version.

3.8.4. Fichiers de configuration de développement supplémentaire au niveau de l'application

Le fichier de configuration de développement supplémentaire au niveau de l'application (APP_DIR/config/autoload/development.local.php) s'affiche uniquement lorsque vous activez le mode développement.

Le fichier development.local.php est fusionné avec d'autres fichiers de configuration au niveau du module. Cela vous permet de remplacer certains paramètres spécifiques au module utilisés uniquement dans l'environnement de développement.

Si vous désactivez le mode développement, le fichier development.local.php sera supprimé. Donc, vous ne devriez pas stocker ce fichier sous le contrôle de version. Au lieu de cela, stockez sa version de distribution development.local.php.dist sous le contrôle de version.

3.8.5. Fichiers de configuration au niveau du module

Dans la figure 3.4, vous pouvez voir que le module Application livré avec votre application contient le fichier module.config.php dans lequel vous placez les paramètres spécifiques au module. Regardons le fichier module.config.php du module Application :

<?php
namespace Application;

use Zend\Router\Http\Literal;
use Zend\Router\Http\Segment;
use Zend\ServiceManager\Factory\InvokableFactory;

return [
    'router' => [
        'routes' => [
            'home' => [
                'type' => Literal::class,
                'options' => [
                    'route'    => '/',
                    'defaults' => [
                        'controller' => Controller\IndexController::class,
                        'action'     => 'index',
                    ],
                ],
            ],
            'application' => [
                'type'    => Segment::class,
                'options' => [
                    'route'    => '/application[/:action]',
                    'defaults' => [
                        'controller'    => Controller\IndexController::class,
                        'action'        => 'index',
                    ],
                ],
            ],
        ],
    ],
    'controllers' => [
        'factories' => [
            Controller\IndexController::class => InvokableFactory::class,
        ],
    ],
    'view_manager' => [
        'display_not_found_reason' => true,
        'display_exceptions'       => true,
        'doctype'                  => 'HTML5',
        'not_found_template'       => 'error/404',
        'exception_template'       => 'error/index',
        'template_map' => [
            'layout/layout'           => __DIR__ . '/../view/layout/layout.phtml',
            'application/index/index' => __DIR__ . '/../view/application/index/index.phtml',
            'error/404'               => __DIR__ . '/../view/error/404.phtml',
            'error/index'             => __DIR__ . '/../view/error/index.phtml',
        ],
        'template_path_stack' => [
            __DIR__ . '/../view',
        ],
    ],
];

Dans ce fichier, vous déclarez les contrôleurs du module, vous fournissez des informations sur les règles de routage pour le mappage des URL vers vos contrôleurs, déclarez les plugins de contrôleurs, les vues et les aides de vues (nous en apprendrons plus sur ces termes dans ce chapitre et dans les chapitres suivants ).

3.8.6. Combiner les fichiers de configuration

Lors de la création d'une application, les fichiers de configuration fournis par le module et les fichiers de configuration supplémentaires provenant du dossier APP_DIR/config/autoload sont fusionnés en un seul grand tableau imbriqué. Ainsi, chaque paramètre de configuration devient disponible n'importe où dans le site web. Donc, potentiellement, vous êtes capable de remplacer certains paramètres spécifiés par les modules.

Vous avez peut-être également vu le fichier de configuration "combiné" lors de l'installation de PHP où se trouve le fichier principal php.ini et plusieurs fichiers de configuration supplémentaires qui sont inclus dans le fichier principal. Une telle séparation rend la configuration de votre application précise et flexible car vous n'avez pas besoin de placer tous vos paramètres dans un seul fichier et de les modifier chaque fois que vous avez besoin de changer quelque chose.

Les fichiers de configuration sont chargés dans l'ordre suivant :

Le fichier principal application.config.php est chargé en premier. Il est utilisé pour initialiser le gestionnaire de service et charger les modules d'application. Les données chargées à partir de cette configuration sont stockées seules et ne sont pas fusionnées avec d'autres fichiers de configuration.
Les fichiers de configuration pour chaque module d'application sont chargés et fusionnés. Les modules sont chargés dans le même ordre qu'ils sont déclarés dans le fichier application.config.php. Si deux modules stockent (intentionnellement ou par erreur) des paramètres dans les clés nommées similairement, ces paramètres peuvent être écrasés.
Les fichiers de configuration supplémentaires du dossier APP_DIR/config/autoload sont chargés et fusionnés en un seul tableau. Ensuite, ce tableau est fusionné avec le tableau de configuration du module produit à l'étape précédente, lors du chargement de la configuration du module. La configuration à l'échelle de l'application a une priorité plus élevée que la configuration du module, de sorte que vous pouvez remplacer les clés du module ici si vous le souhaitez.