Configuration

Alors que les conventions enlèvent le besoin de configurer tout CakePHP, vous aurez tout de même besoin de configurer quelques options de configurations comme les accès à la base de données.

De plus, certaines options de configuration facultatives vous permettent de changer les valeurs par défaut & les implémentations avec des options qui conviennent à votre application.

Configurer votre Application

La configuration est généralement stockée soit dans les fichiers PHP ou INI, et chargée pendant le bootstrap de l’application. CakePHP est fourni avec un fichier de configuration par défaut, mais si cela et nécessaire, vous pouvez ajouter des fichiers supplémentaires de configuration et les charger dans le bootstrap de votre application. Cake\Core\Configure est utilisée pour la configuration globale, et les classes comme Cache fournissent les méthodes config() pour faciliter la configuration et la rendre plus transparente.

Charger les Fichiers de Configuration Supplémentaires

Si votre application a plusieurs options de configuration, il peut être utile de séparer la configuration dans plusieurs fichiers. Après avoir créé chacun des fichiers dans votre répertoire config/, vous pouvez les charger dans bootstrap.php:

use Cake\Core\Configure;
use Cake\Core\Configure\Engine\PhpConfig;

Configure::config('default', new PhpConfig());
Configure::load('app', 'default', false);
Configure::load('other_config', 'default');

Vous pouvez aussi utiliser des fichiers de configuration supplémentaires pour surcharger un environnement spécifique. Chaque fichier chargé après app.php peut redéfinir les valeurs déclarées précédemment ce qui vous permet de personnaliser la configuration pour les environnements de développement ou intermédiaires.

Configuration Générale

Ci-dessous se trouve une description des variables et la façon dont elles modifient votre application CakePHP.

debug
Change la sortie de debug de CakePHP. false = Mode Production. Pas de messages, d’erreurs ou d’avertissements montrés. true = Errors et avertissements montrés.
App.namespace

Le namespace sous lequel se trouvent les classes de l’app.

Note

Quand vous changez le namespace dans votre configuration, vous devez aussi mettre à jour le fichier composer.json pour utiliser aussi ce namespace. De plus, créer un nouvel autoloader en lançant php composer.phar dumpautoload.

App.baseUrl
Décommentez cette définition si vous n’ envisagez pas d’utiliser le mod_rewrite d’Apache avec CakePHP. N’oubliez pas aussi de retirer vos fichiers .htaccess.
App.base
Le répertoire de base où l’app se trouve. Si à false, il sera détecté automatiquement.
App.encoding
Définit l’encodage que votre application utilise. Cet encodage est utilisé pour générer le charset dans le layout, et les entities encodés. Cela doit correspondre aux valeurs d’encodage spécifiées pour votre base de données.
App.webroot
Le répertoire webroot.
App.wwwRoot
Le chemin vers webroot.
App.fullBaseUrl
Le nom de domaine complet (y compris le protocole) vers la racine de votre application. Ceci est utilisé pour la génération d’URLS absolues. Par défaut, cette valeur est générée en utilisant la variable d’environnement $_SERVER. Cependant, vous devriez la définir manuellement pour optimiser la performance ou si vous êtes inquiets sur le fait que des gens puissent manipuler le header Host. Dans un contexte de CLI (à partir des shells), fullBaseUrl ne peut pas être lu dans $_SERVER, puisqu’il n’y a aucun serveur web impliqué. Vous devez le spécifier vous-même si vous avez besoin de générer des URLs à partir d’un shell (par exemple pour envoyer des emails).
App.imageBaseUrl
Le chemin Web vers le répertoire public des images dans webroot. Si vous utilisez un CDN, vous devez définir cette valeur vers la localisation du CDN.
App.cssBaseUrl
Le chemin Web vers le répertoire public des css dans webroot. Si vous utilisez un CDN, vous devez définir cette valeur vers la localisation du CDN.
App.paths
Les chemins de Configure pour les ressources non basées sur les classes. Accepte les sous-clés plugins, templates, locales, qui permettent la définition de chemins respectivement pour les plugins, les templates de view et les fichiers de locales.
App.jsBaseUrl
Le chemin Web vers le répertoire public des js dans webroot. Si vous utilisez un CDN, vous devriez définir cette valeur vers la localisation du CDN.
Security.salt
Une chaîne au hasard utilisée dans les hashages. Cette valeur est aussi utilisée comme sel HMAC quand on fait des chiffrements symétriques.
Asset.timestamp

Ajoute un timestamp qui est le dernier temps modifié du fichier particulier à la fin des URLs des fichiers d’asset (CSS, JavaScript, Image) lors de l’utilisation des helpers adéquats. Valeurs valides:

  • (bool) false - Ne fait rien (par défaut)
  • (bool) true - Ajoute le timestamp quand debug est à true
  • (string) ‘force’ - Ajoute toujours le timestamp.

Configuration de la Base de Données

Regardez la Configuration de la Base de Données pour plus d’informations sur la configuration de vos connections à la base de données.

Configuration de la Mise en Cache

Consultez Configuration de la classe Cache pour plus d’informations sur la configuration de la mise en cache dans CakePHP.

Configuration de Gestion des Erreurs et des Exceptions

Consultez les sections sur Configuration des Erreurs et des Exceptions pour des informations sur la configuration des gestionnaires d’erreur et d’exception.

Configuration des Logs

Consultez Configuration des flux d’un log (journal) pour des informations sur la configuration des logs dans CakePHP.

Configuration de Email

Consultez Configuration pour avoir des informations sur la configuration prédéfinie d’email dans CakePHP.

Configuration de Session

Consultez Configuration de Session pour avoir des informations sur la configuration de la gestion des sessions dans CakePHP.

Configuration du Routing

Consultez Connecter les Routes pour plus d’informations sur la configuration du routing et de la création de routes pour votre application.

Chemins de Classe Supplémentaires

Les chemins de classe supplémentaires sont définis dans les autoloaders que votre application utilise. Quand vous utilisez Composer pour générer votre autoloader, vous pouvez faire ce qui suit, pour fournir des chemins à utiliser pour les controllers dans votre application:

"autoload": {
    "psr-4": {
        "App\\Controller\\": "/path/to/directory/with/controller/folders",
        "App\": "src"
    }
}

Ce qui est au-dessus va configurer les chemins pour les namespaces App et App\Controller. La première clé va être cherchée, et si ce chemin ne contient pas la classe/le fichier, la deuxième clé va être cherchée. Vous pouvez aussi faire correspondre un namespace unique vers plusieurs répertoires avec ce qui suit:

"autoload": {
    "psr-4": {
        "App\": ["src", "/path/to/directory"]
    }
}

Les chemins de Plugin, View Template et de Locale

Puisque les plugins, view templates et locales ne sont pas des classes, ils ne peuvent pas avoir un autoloader configuré. CakePHP fournit trois variables de configuration pour configurer des chemins supplémentaires pour vos ressources. Dans votre config/app.php, vous pouvez définir les variables:

return [
    // Plus de configuration
    'App' => [
        'paths' => [
            'plugins' => [
                ROOT . DS . 'plugins' . DS,
                '/path/to/other/plugins/'
            ],
            'templates' => [
                APP . 'Template' . DS,
                APP . 'Template2' . DS
            ],
            'locales' => [
                APP . 'Locale' . DS
            ]
        ]
    ]
];

Les chemins doivent finir par un séparateur de répertoire, ou ils ne fonctionneront pas correctement.

Configuration de Inflection

Regardez Configuration d’Inflexion pour plus d’informations.

Classe Configure

class Cake\Core\Configure

La nouvelle classe Configure de CakePHP peut être utilisée pour stocker et récupérer des valeurs spécifiques d’exécution ou d’application. Attention, cette classe vous permet de stocker tout dedans, puis de l’utiliser dans toute autre partie de votre code: une tentative évidente de casser le modèle MVC avec lequel CakePHP a été conçu. Le but principal de la classe Configure est de garder les variables centralisées qui peuvent être partagées entre beaucoup d’objets. Souvenez-vous d’essayer de suivre la règle “convention plutôt que configuration” et vous ne casserez pas la structure MVC que nous avons mis en place.

Vous pouvez accéder à Configure partout dans votre application:

Configure::read('debug');

Ecrire des Données de Configuration

static Cake\Core\Configure::write($key, $value)

Utilisez write() pour stocker les données de configuration de l’application:

Configure::write('Company.name','Pizza, Inc.');
Configure::write('Company.slogan','Pizza for your body and soul');

Note

La notation avec points utilisée dans le paramètre $key peut être utilisée pour organiser vos paramètres de configuration dans des groupes logiques.

L’exemple ci-dessus pourrait aussi être écrit en un appel unique:

Configure::write('Company', [
    'name' => 'Pizza, Inc.',
    'slogan' => 'Pizza for your body and soul'
]);

Vous pouvez utiliser Configure::write('debug', $bool) pour intervertir les modes de debug et de production à la volée. C’est particulièrement pratique pour les interactions JSON quand les informations de debug peuvent entraîner des problèmes de parsing.

Lire les Données de Configuration

static Cake\Core\Configure::read($key = null)

Utilisée pour lire les données de configuration à partir de l’application. Par défaut, la valeur de debug de CakePHP est au plus important. Si une clé est fournie, la donnée est retournée. En utilisant nos exemples du write() ci-dessus, nous pouvons lire cette donnée:

Configure::read('Company.name');    // Renvoie: 'Pizza, Inc.'
Configure::read('Company.slogan');  // Renvoie: 'Pizza for your body and soul'

Configure::read('Company');

//yields:
['name' => 'Pizza, Inc.', 'slogan' => 'Pizza for your body and soul'];

Si $key est laissée à null, toutes les valeurs dans Configure seront retournées.

static Cake\Core\Configure::readOrFail($key)

Permet de lire les données de configuration tout comme Cake\Core\Configure::read mais s’attend à trouver une paire clé/valeur. Dans le cas où la paire demandée n’existe pas, une RuntimeException sera lancée:

Configure::readOrFail('Company.name');    // Renvoie: 'Pizza, Inc.'
Configure::readOrFail('Company.geolocation');  // Lancera un exception

Configure::readOrFail('Company');

//  Renvoie:
['name' => 'Pizza, Inc.', 'slogan' => 'Pizza for your body and soul'];

Nouveau dans la version 3.1.7: Configure::readOrFail() a été ajoutée dans 3.1.7

Vérifier si les Données de Configuration sont Définies

static Cake\Core\Configure::check($key)

Utilisée pour vérifier si une clé/chemin existe et a une valeur non-null:

$exists = Configure::check('Company.name');

Supprimer une Donnée de Configuration

static Cake\Core\Configure::delete($key)

Utilisée pour supprimer l’information à partir de la configuration de l’application:

Configure::delete('Company.name');

Lire & Supprimer les Données de Configuration

static Cake\Core\Configure::consume($key)

Lit et supprime une clé de Configure. C’est utile quand vous voulez combiner la lecture et la suppression de valeurs en une seule opération.

Lire et Ecrire les Fichiers de Configuration

CakePHP est fourni avec deux lecteurs de fichiers de configuration intégrés. Cake\Core\Configure\Engine\PhpConfig est capable de lire les fichiers de config de PHP, dans le même format dans lequel Configure a lu historiquement. Cake\Core\Configure\Engine\IniConfig est capable de lire les fichiers de config ini du cœur. Regardez la documentation PHP pour plus d’informations sur les fichiers ini spécifiés. Pour utiliser un lecteur de config du cœur, vous aurez besoin de l’attacher à Configure en utilisant Configure::config():

use Cake\Core\Configure\Engine\PhpConfig;

// Lire les fichiers de config à partir de config
Configure::config('default', new PhpConfig());

// Lire les fichiers de config à partir du chemin
Configure::config('default', new PhpConfig('/path/to/your/config/files/'));

Vous pouvez avoir plusieurs lecteurs attachés à Configure, chacun lisant différents types de fichiers de configuration, ou lisant à partir de différents types de sources. Vous pouvez interagir avec les lecteurs attachés en utilisant certaines autres méthodes de Configure. Pour vérifier les alias qui sont attachés au lecteur, vous pouvez utiliser Configure::configured():

// Récupère le tableau d'alias pour les lecteurs attachés.
Configure::configured();

// Vérifie si un lecteur spécifique est attaché
Configure::configured('default');
static Cake\Core\Configure::drop($name)

Vous pouvez aussi retirer les lecteurs attachés. Configure::drop('default') retirerait l’alias du lecteur par défaut. Toute tentative future pour charger les fichiers de configuration avec ce lecteur serait en échec:

Configure::drop('default');

Chargement des Fichiers de Configuration

static Cake\Core\Configure::load($key, $config = 'default', $merge = true)

Une fois que vous attachez un lecteur de config à Configure, vous pouvez charger les fichiers de configuration:

// Charge my_file.php en utilisant l'objet de lecture 'default'.
Configure::load('my_file', 'default');

Les fichiers de configuration chargés fusionnent leurs données avec la configuration exécutée existante dans Configure. Cela vous permet d’écraser et d’ajouter de nouvelles valeurs dans la configuration existante exécutée. En configurant $merge à true, les valeurs ne vont pas toujours écraser la configuration existante.

Créer et Modifier les Fichiers de Configuration

static Cake\Core\Configure::dump($key, $config = 'default', $keys = [])

Déverse toute ou quelques données de Configure dans un fichier ou un système de stockage supporté par le lecteur. Le format de sérialisation est décidé en configurant le lecteur de config attaché dans $config. Par exemple, si l’adaptateur ‘default’ est Cake\Core\Configure\Engine\PhpConfig, le fichier généré sera un fichier de configuration PHP qu’on pourra charger avec Cake\Core\Configure\Engine\PhpConfig.

Etant donné que le lecteur ‘default’ est une instance de PhpReader. Sauvegarder toutes les données de Configure dans le fichier my_config.php:

Configure::dump('my_config', 'default');

Sauvegarde seulement les erreurs gérant la configuration:

Configure::dump('error', 'default', ['Error', 'Exception']);

Configure::dump() peut être utilisée pour soit modifier, soit surcharger les fichiers de configuration qui sont lisibles avec Configure::load()

Stocker la Configuration de Runtime

static Cake\Core\Configure::store($name, $cacheConfig = 'default', $data = null)

Vous pouvez aussi stocker les valeurs de configuration exécutées pour l’utilisation dans une requête future. Comme configure ne se souvient seulement que des valeurs pour la requête courante, vous aurez besoin de stocker toute information de configuration modifiée si vous souhaitez l’utiliser dans des requêtes suivantes:

// Stocke la configuration courante dans la clé 'user_1234' dans le cache 'default'.
Configure::store('user_1234', 'default');

Les données de configuration stockées persistent dans la configuration appelée Cache. Consultez la documentation sur La mise en cache pour plus d’informations sur la mise en cache.

Restaurer la configuration de runtime

static Cake\Core\Configure::restore($name, $cacheConfig = 'default')

Une fois que vous avez stocké la configuration exécutée, vous aurez probablement besoin de la restaurer afin que vous puissiez y accéder à nouveau. Configure::restore() fait exactement cela:

// restaure la configuration exécutée à partir du cache.
Configure::restore('user_1234', 'default');

Quand on restaure les informations de configuration, il est important de les restaurer avec la même clé, et la configuration de cache comme elle était utilisée pour les stocker. Les informations restaurées sont fusionnées en haut de la configuration existante exécutée.

Créer vos Propres Lecteurs de Configuration

Comme les lecteurs de configuration sont une partie extensible de CakePHP, vous pouvez créer des lecteurs de configuration dans votre application et plugins. Les lecteurs de configuration ont besoin d’implémenter l’ Cake\Core\Configure\ConfigEngineInterface. Cette interface définit une méthode de lecture, comme seule méthode requise. Si vous aimez vraiment les fichiers XML, vous pouvez créer un lecteur de config simple Xml pour votre application:

// Dans src/Configure/Engine/XmlConfig.php
namespace App\Configure\Engine;

use Cake\Core\Configure\ConfigEngineInterface;
use Cake\Utility\Xml;

class XmlConfig implements ConfigEngineInterface
{

    public function __construct($path = null)
    {
        if (!$path) {
            $path = CONFIG;
        }
        $this->_path = $path;
    }

    public function read($key)
    {
        $xml = Xml::build($this->_path . $key . '.xml');
        return Xml::toArray($xml);
    }

    public function dump($key, array $data)
    {
        // Code to dump data to file
    }
}

Dans votre config/bootstrap.php, vous pouvez attacher ce lecteur et l’utiliser:

use App\Configure\Engine\XmlConfig;

Configure::config('xml', new XmlConfig());
...

Configure::load('my_xml', 'xml');

La méthode read() du lecteur de config, doit retourner un tableau d’informations de configuration que la ressource nommée $key contient.

interface Cake\Core\Configure\ConfigEngineInterface

Définit l’interface utilisée par les classes qui lisent les données de configuration et les stockent dans Configure.

Cake\Core\Configure\ConfigEngineInterface::read($key)
Paramètres:
  • $key (string) – Le nom de la clé ou l’identifieur à charger.

Cette méthode devrait charger/parser les données de configuration identifiées par $key et retourner un tableau de données dans le fichier.

Cake\Core\Configure\ConfigEngineInterface::dump($key)
Paramètres:
  • $key (string) – L’identifieur dans lequel écrire.
  • $data (array) – La donnée à supprimer.

Cette méthode doit supprimer/stocker la donnée de configuration fournie à une clé identifié par $key.

Moteurs de Configuration intégrés

Fichiers de Configuration PHP

class Cake\Core\Configure\Engine\PhpConfig

Vous permet de lire les fichiers de configuration de votre application qui sont stockés en fichiers PHP simples. Vous pouvez lire soit les fichiers à partir de votre config, soit des répertoires configs du plugin en utilisant la syntaxe de plugin. Les fichiers doivent retourner un tableau. Un fichier de configuration d’exemple ressemblerait à cela:

return [
    'debug' => 0,
    'Security' => [
        'salt' => 'its-secret'
    ],
    'App' => [
        'namespace' => 'App'
    ]
];

Chargez votre fichier de configuration personnalisé en insérant ce qui suit dans config/bootstrap.php:

Configure::load('customConfig');

Fichiers de Configuration Ini

class Cake\Core\Configure\Engine\IniConfig

Vous permet de lire les fichiers de configuration qui sont stockés en fichiers .ini simples. Les fichiers ini doivent être compatibles avec la fonction php parse_ini_file(), et bénéficie des améliorations suivantes:

  • Les valeurs séparées par des points sont étendues dans les tableaux.
  • Les valeurs de la famille des booléens comme ‘on’ et ‘off’ sont converties en booléens.

Un fichier ini d’exemple ressemblerait à cela:

debug = 0

[Security]
salt = its-secret

[App]
namespace = App

Le fichier ini ci-dessus aboutirait aux mêmes données de configuration que dans l’exemple PHP du dessus. Les structures de tableau peuvent être créées soit à travers des valeurs séparées de point, soit des sections. Les sections peuvent contenir des clés séparées de point pour des imbrications plus profondes.

Fichiers de Configuration Json

class Cake\Core\Configure\Engine\JsonConfig

Vous permet de lire / effacer les fichiers de configuration qui sont stockés en chaînes encodées JSON dans des fichiers .json.

Un exemple de fichier JSON ressemblerait à ceci:

{
    "debug": false,
    "App": {
        "namespace": "MyApp"
    },
    "Security": {
        "salt": "its-secret"
    }
}

Bootstrapping CakePHP

Si vous avez des besoins de configuration supplémentaires, utilisez le fichier bootstrap de CakePHP dans config/bootstrap.php. Ce fichier est inclus juste avant chaque requête et commande CLI.

Ce fichier est idéal pour un certain nombre de tâches de bootstrapping courantes:

  • Définir des fonctions commodes.
  • Déclarer des constantes.
  • Créer des configurations de cache.
  • Définir la configuration des logs.
  • Configurer les inflections personnalisées.
  • Charger les fichiers de configuration.

Il pourrait être tentant de placer des fonctions de formatage ici pour les utiliser dans vos controllers. Comme vous le verrez dans les documentations sur les Controllers (Contrôleurs) et les Views (Vues), il y a de meilleurs moyens pour vous d’ajouter de la logique personnalisée dans votre application.

Application::bootstrap()

En plus du fichier config/bootstrap.php qui doit être utilisé pour faire de la configuration “bas niveau” de votre application, vous pouvez également utiliser la méthode “hook” Application::bootstrap() pour charger / initialiser des plugins et attacher des écouteurs d’événements globaux:

// in src/Application.php
namespace App;

use Cake\Core\Plugin;
use Cake\Http\BaseApplication;

class Application extends BaseApplication
{
    public function bootstrap()
    {
        // Appeler la méthode parente permet de faire le `require_once`
        // pour charger le fichier config/bootstrap.php
        parent::bootstrap();

        Plugin::load('MyPlugin', ['bootstrap' => true, 'routes' => true]);
    }
}

Charger les plugins et les événements dans Application::bootstrap() rend les Test d’Intégrations des Controllers plus faciles car les événements et les routes seront ainsi à nouveau traités pour chaque méthode de test.

Variables d’environnement

Certains fournisseurs d’architectures dans le cloud comme Heroku, vous permettent de définir des variables d’environnement. En définissant des variables d’environnement, vous pouvez configurer vos applications comme des applications 12factor. Suivre les instructions pour les applications 12factor vous permet de créer des applications “stateless” et donc de faciliter le déploiement de votre application. Cela signifie ainsi que si vous avez besoin par exemple de changer votre base de données, vous avez juste besoin de changer la variable DATABASE_URL dans la configuration sur votre fournisseur sans rien avoir à changer dans votre code.

Comme vous pouvez le voir dans le fichier app.php, les variables suivantes sont concernés :

  • DEBUG (0 or 1)
  • APP_ENCODING (ex: UTF-8)
  • APP_DEFAULT_LOCALE (ex: en_US)
  • SECURITY_SALT
  • CACHE_DEFAULT_URL (ex: File:///?prefix=myapp_&serialize=true&timeout=3600&path=../tmp/cache/)
  • CACHE_CAKECORE_URL (ex: File:///?prefix=myapp_cake_core_&serialize=true&timeout=3600&path=../tmp/cache/persistent/)
  • CACHE_CAKEMODEL_URL (ex: File:///?prefix=myapp_cake_model_&serialize=true&timeout=3600&path=../tmp/cache/models/)
  • EMAIL_TRANSPORT_DEFAULT_URL (ex: smtp://user:password@hostname:port?tls=null&client=null&timeout=30)
  • DATABASE_URL (ex: mysql://user:pass@db/my_app)
  • DATABASE_TEST_URL (ex: mysql://user:pass@db/test_my_app)
  • LOG_DEBUG_URL (ex: file:///?levels[]=notice&levels[]=info&levels[]=debug&file=debug&path=../logs/)
  • LOG_ERROR_URL (ex: file:///?levels[]=warning&levels[]=error&levels[]=critical&levels[]=alert&levels[]=emergency&file=error&path=../logs/)

Comme vous pouvez le voir dans ces exemples, nous définissons certaines options de configuration à l’aide de chaînes DSN. C’est le cas pour les bases de données, les logs, le transport d’emails et les configurations du cache.

Si certaines variables d’environnement ne sont pas définies dans votre environnement, CakePHP utilisera les valeurs définies dans app.php. Vous pouvez utiliser la librairie php-dotenv pour utiliser les variables d’environnement dans vos développements en local. Reportez-vous aux instructions dans le README pour plus d’informations.

Désactiver les tables génériques

Bien qu’utiliser les classes génériques de Table (aussi appeler les “auto-tables”) soit pratique lorsque vous développez rapidement de nouvelles applications, les tables génériques rendent le debug plus difficile dans certains cas.

Vous pouvez vérifier si une requête a été générée à partir d’une table générique via le DebugKit, dans le panel SQL. Si vous avez encore des difficultés à diagnostiquer un problème qui pourrait être causé par les auto-tables, vous pouvez lancer une exception quand CakePHP utilise implicitement une Cake\ORM\Table générique plutôt que la vraie classe du Model:

// Dans votre fichier bootstrap.php
use Cake\Event\EventManager;
use Cake\Network\Exception\InternalErrorException;

$isCakeBakeShellRunning = (PHP_SAPI === 'cli' && isset($argv[1]) && $argv[1] === 'bake');
if (!$isCakeBakeShellRunning) {
    EventManager::instance()->on('Model.initialize', function($event) {
        $subject = $event->getSubject();
        if (get_class($subject === 'Cake\ORM\Table') {
            $msg = sprintf(
                'Missing table class or incorrect alias when registering table class for database table %s.',
                $subject->getTable());
            throw new InternalErrorException($msg);
        }
    });
}