Les premiers pas
Tous les fichiers de configuration du cadre d'application Laravel sont entreposés dans le répertoire `config`. Chaque option est documentée; n'hésitez pas à consulter les fichiers pour vous familiariser avec les options disponibles.
Ces fichiers vous permettent de configurer des éléments tels que les informations de connexion à votre base de données, les informations de votre serveur de messagerie, ainsi que diverses autres valeurs de configuration essentielles comme l'URL de votre application et votre clé de chiffrement.
La commande about
Laravel peut afficher un aperçu de la configuration, des pilotes et de l'environnement de votre application via la commande Artisan about :
| php artisan about |
Si vous ne vous intéressez qu'à une section particulière du rapport d'aperçu de l'application, vous pouvez filtrer cette section à l'aide de l'option --only :
| php artisan about --only=environment |
Ou, pour explorer en détail les valeurs d'un fichier de configuration spécifique, vous pouvez utiliser la commande Artisan config:show :
| php artisan config:show database |
Configuration de l'environnement
Il est souvent utile d'avoir des valeurs de configuration différentes selon l'environnement d'exécution de l'application. Par exemple, vous pouvez utiliser un pilote de cache différent en local et sur votre serveur de production.
Pour simplifier cette opération, Laravel utilise la bibliothèque PHP DotEnv. Lors d'une nouvelle installation de Laravel, le répertoire racine de votre application contient un fichier `.env.example` définissant de nombreuses variables d'environnement courantes. Ce fichier est automatiquement copié dans `.env` lors de l'installation de Laravel.
Le fichier `.env` par défaut de Laravel contient des valeurs de configuration communes pouvant varier selon que votre application s'exécute en local ou sur un serveur web de production. Ces valeurs sont ensuite lues par les fichiers de configuration du répertoire `config` grâce à la fonction `env` de Laravel.
Si vous développez en équipe, vous pouvez continuer à inclure et à mettre à jour le fichier `.env.example` avec votre application. En y insérant des valeurs fictives, les autres développeurs de votre équipe peuvent identifier clairement les variables d'environnement nécessaires à l'exécution de votre application.
Toute variable de votre fichier .env peut être remplacée par des variables d'environnement externes, telles que les variables d'environnement au niveau du serveur ou du système.
Sécurité des fichiers d'environnement
Il est déconseillé d'inclure votre fichier `.env` dans le système de gestion de versions de votre application, car chaque développeur ou serveur utilisant votre application peut nécessiter une configuration d'environnement différente. De plus, cela représenterait un risque de sécurité si un intrus accédait à votre dépôt de contrôle de version, car toutes les informations d'identification sensibles seraient exposées.
Cependant, il est possible de chiffrer votre fichier d'environnement à l'aide du système de chiffrement intégré de Laravel. Les fichiers d'environnement chiffrés peuvent être placés en toute sécurité dans le système de gestion de versions.
Fichiers d'environnement supplémentaires
Avant de charger les variables d'environnement de votre application, Laravel vérifie si une variable d'environnement APP_ENV a été fournie en externe ou si l'argument de ligne de commande --env a été spécifié. Le cas échéant, Laravel tentera de charger un fichier .env.[APP_ENV] s'il existe. Sinon, le fichier .env par défaut sera chargé.
Types de variables d'environnement
Toutes les variables de vos fichiers .env sont généralement interprétées comme des chaînes de caractères. Des valeurs réservées ont donc été créées afin de vous permettre de renvoyer une plus grande variété de types depuis la fonction env() :
| Valeur .env | Valeur env() |
|---|---|
| true | (bool) true |
| (true) | (bool) true |
| false | (bool) false |
| (false) | (bool) false |
| empty | (string) '' |
| (empty) | (string) '' |
| null | (null) null |
| (null) | (null) null |
Si vous devez définir une variable d'environnement avec une valeur contenant des espaces, vous pouvez le faire en plaçant la valeur entre guillemets doubles :
- APP_NAME="Mon Application"
Récupération de la configuration d'environnement
Toutes les variables listées dans le fichier `.env` seront chargées dans la super-variable PHP `$_ENV` lors de la réception d'une requête par votre application. Vous pouvez toutefois utiliser la fonction `env` pour récupérer les valeurs de ces variables dans vos fichiers de configuration. En effet, si vous consultez les fichiers de configuration de Laravel, vous constaterez que de nombreuses options utilisent déjà cette fonction :
- 'debug' => (bool) env('APP_DEBUG', false),
La deuxième valeur transmise à la fonction `env` est la «valeur par défaut». Cette valeur sera renvoyée si aucune variable d'environnement n'est définie pour la clef spécifiée.
Détermination de l'environnement actuel
L'environnement actuel de l'application est déterminé par la variable `APP_ENV` de votre fichier `.env`. Vous pouvez accéder à cette valeur via la méthode `environment` de la façade `App` :
- use Illuminate\Support\Facades\App;
-
- $environment = App::environment();
Vous pouvez également transmettre des arguments à la méthode `environment` pour déterminer si l'environnement correspond à une valeur donnée. La méthode renverra `true` si l'environnement correspond à l'une des valeurs fournies :
La détection de l'environnement applicatif actuel peut être modifiée en définissant une variable d'environnement APP_ENV au niveau du serveur.
Chiffrement des fichiers d'environnement
Les fichiers d'environnement non chiffrés ne doivent jamais être entreposés dans le système de gestion de versions. Laravel vous permet toutefois de chiffrer vos fichiers d'environnement afin de les ajouter en toute sécurité au système de gestion de versions avec le reste de votre application.
Chiffrement
Pour chiffrer un fichier d'environnement, vous pouvez utiliser la commande env:encrypt :
| php artisan env:encrypt |
L'exécution de la commande `env:encrypt` chiffrera votre fichier `.env` et placera son contenu chiffré dans un fichier `.env.encrypted`. La clef de déchiffrement est affichée dans le résultat de la commande et doit être conservée dans un gestionnaire de mots de passe sécurisé. Si vous souhaitez fournir votre propre clef de chiffrement, vous pouvez utiliser l'option `--key` lors de l'exécution de la commande :
| php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF |
La longueur de la clef fournie doit correspondre à celle requise par l'algorithme de chiffrement utilisé. Par défaut, Laravel utilise l'algorithme AES-256-CBC, nécessitant une clef de 32 caractères. Vous pouvez utiliser n'importe quel algorithme pris en charge par le système de chiffrement de Laravel en spécifiant l'option `--cipher` lors de l'exécution de la commande.
Si votre application comporte plusieurs fichiers d'environnement, tels que `.env` et `.env.staging`, vous pouvez spécifier le fichier à chiffrer en indiquant son nom via l'option `--env`.
| php artisan env:encrypt --env=staging |
Noms de variables lisibles
Lors du chiffrement de votre fichier d'environnement, vous pouvez utiliser l'option `--readable` pour conserver les noms de variables visibles tout en chiffrant leurs valeurs :
| php artisan env:encrypt --readable |
Cela générera un fichier chiffré au format suivant :
- APP_NAME=eyJpdiI6...
- APP_ENV=eyJpdiI6...
- APP_KEY=eyJpdiI6...
- APP_DEBUG=eyJpdiI6...
- APP_URL=eyJpdiI6...
L'utilisation du format lisible permet de visualiser les variables d'environnement existantes sans exposer de données sensibles. Elle facilite également la vérification des demandes de fusion, car elle permet de voir quelles variables ont été ajoutées, supprimées ou renommées sans avoir à déchiffrer le fichier.
Lors du déchiffrement des fichiers d'environnement, Laravel détecte automatiquement le format utilisé ; aucune option supplémentaire n'est donc nécessaire pour la commande `env:decrypt`.
Lorsque l'option `--readable` est utilisée, les commentaires et les lignes vides du fichier d'environnement d'origine ne sont pas inclus dans le résultat chiffré.
Déchiffrement
Pour déchiffrer un fichier d'environnement, vous pouvez utiliser la commande `env:decrypt`. Cette commande requiert une clef de déchiffrement, que Laravel récupérera à partir de la variable d'environnement `LARAVEL_ENV_ENCRYPTION_KEY` :
| php artisan env:decrypt |
Ou bien, la clef peut être fournie directement à la commande via l'option --key :
| php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF |
Lorsque la commande `env:decrypt` est appelée, Laravel déchiffre le contenu du fichier `.env.encrypted` et place le contenu déchiffré dans le fichier `.env`.
L'option `--cipher` peut être fournie à la commande `env:decrypt` pour utiliser un algorithme de chiffrement personnalisé :
| php artisan env:decrypt --key=qUWuNRdfuImXcKxZ --cipher=AES-128-CBC |
Si votre application comporte plusieurs fichiers d'environnement, tels que .env et .env.staging, vous pouvez spécifier le fichier d'environnement à déchiffrer en fournissant son nom via l'option --env :
| php artisan env:decrypt --env=staging |
Pour écraser un fichier d'environnement existant, vous pouvez utiliser l'option --force avec la commande env:decrypt :
| php artisan env:decrypt --force |
Accès aux valeurs de configuration
Vous pouvez facilement accéder à vos valeurs de configuration depuis n'importe quel endroit de votre application, via la façade Config ou la fonction de configuration globale. L'accès aux valeurs de configuration se fait à l'aide de la syntaxe «point», incluant le nom du fichier et l'option souhaitée. Une valeur par défaut peut également être spécifiée et sera renvoyée si l'option de configuration n'existe pas :
- use Illuminate\Support\Facades\Config;
-
- $value = Config::get('app.timezone');
-
- $value = config('app.timezone');
-
- // Récupérer une valeur par défaut si la valeur de configuration n'existe pas...
- $value = config('app.timezone', 'Asia/Seoul');
Pour définir les valeurs de configuration lors de l'exécution, vous pouvez appeler la méthode set de la façade Config ou passer un tableau à la fonction config :
- Config::set('app.timezone', 'America/Chicago');
-
- config(['app.timezone' => 'America/Chicago']);
Pour faciliter l'analyse statique, la façade Config fournit également des méthodes de récupération de configuration typées. Si la valeur de configuration récupérée ne correspond pas au type attendu, une exception sera levée :
- Config::string('config-key');
- Config::integer('config-key');
- Config::float('config-key');
- Config::boolean('config-key');
- Config::array('config-key');
- Config::collection('config-key');
Mise en cache de la configuration
Pour optimiser les performances de votre application, il est recommandé de mettre en cache tous vos fichiers de configuration dans un seul fichier à l'aide de la commande Artisan `config:cache`. Cela regroupera toutes les options de configuration de votre application dans un fichier unique, rapidement chargeable par le cadre d'application.
Il est généralement conseillé d'exécuter la commande `php artisan config:cache` lors du déploiement en production. Cette commande ne doit pas être exécutée pendant le développement local, car les options de configuration seront fréquemment modifiées au cours du développement de votre application.
Une fois la configuration mise en cache, le fichier `.env` de votre application ne sera plus chargé par le cadre d'application lors des requêtes ou des commandes Artisan ; par conséquent, la fonction `env` ne renverra que les variables d'environnement externes, au niveau système.
Pour cette raison, assurez-vous d'appeler la fonction `env` uniquement depuis les fichiers de configuration (`config`) de votre application. Vous trouverez de nombreux exemples dans les fichiers de configuration par défaut de Laravel. Les valeurs de configuration sont accessibles depuis n'importe quel endroit de votre application grâce à la fonction `config` décrite ci-dessus.
La commande config:clear peut être utilisée pour purger la configuration mise en cache :
| php artisan config:clear |
Si vous exécutez la commande `config:cache` lors de votre déploiement, assurez-vous d'appeler la fonction `env` uniquement depuis vos fichiers de configuration. Une fois la configuration mise en cache, le fichier `.env` ne sera plus chargé ; par conséquent, la fonction `env` ne renverra que des variables d'environnement externes, au niveau système.
Publication de la configuration
La plupart des fichiers de configuration de Laravel sont déjà publiés dans le répertoire `config` de votre application. Cependant, certains fichiers, comme `cors.php` et `view.php`, ne sont pas publiés par défaut, car la plupart des applications n'auront jamais besoin de les modifier.
Vous pouvez néanmoins utiliser la commande Artisan `config:publish` pour publier les fichiers de configuration qui ne sont pas publiés par défaut :
|
php artisan config:publish php artisan config:publish --all |
Mode débogage
L'option de débogage de votre fichier de configuration `config/app.php` détermine la quantité d'informations affichées à l'utilisateur en cas d'erreur. Par défaut, cette option est configurée pour respecter la valeur de la variable d'environnement `APP_DEBUG`, stockée dans votre fichier `.env`.
Pour le développement local, vous devez définir la variable d'environnement `APP_DEBUG` sur `true`. En production, sa valeur doit toujours être `false`. Si cette variable est définie sur `true` en production, vous risquez d'exposer des valeurs de configuration sensibles aux utilisateurs finaux de votre application.
Mode maintenance
Lorsque votre application est en mode maintenance, une vue personnalisée s'affiche pour toutes les requêtes. Cela permet de désactiver facilement l'application pendant une mise à jour ou une opération de maintenance. Un contrôle du mode maintenance est intégré à la pile de middlewares par défaut. Si l'application est en mode maintenance, une exception de type Symfony\Component\HttpKernel\Exception\HttpException est levée avec le code d'état 503.
Pour activer le mode maintenance, exécutez la commande Artisan «down» :
| php artisan down |
Si vous souhaitez que l'en-tête HTTP Refresh soit envoyé avec toutes les réponses en mode maintenance, vous pouvez spécifier l'option de rafraîchissement lors de l'appel de la commande down. L'en-tête Refresh indiquera au navigateur d'actualiser automatiquement la page après le nombre de secondes spécifié :
| php artisan down --refresh=15 |
Vous pouvez également fournir une option de nouvelle tentative à la commande down, étant définie comme la valeur de l'en-tête Retry-After de HTTP, bien que les navigateurs ignorent généralement cet en-tête :
| php artisan down --retry=60 |
Contournement du mode maintenance
Pour contourner le mode maintenance à l'aide d'un jeton secret, vous pouvez utiliser l'option secrète pour spécifier un jeton de contournement du mode maintenance :
| php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515" |
Après avoir placé l'application en mode maintenance, vous pouvez accéder à l'URL de l'application correspondant à ce jeton et Laravel enverra un cookie de contournement du mode maintenance à votre navigateur :
| https://example.com/1630542a-246b-4b66-afa1-dd72a4c43515 |
Si vous souhaitez que Laravel génère le jeton secret pour vous, vous pouvez utiliser l'option `with-secret`. Le secret vous sera affiché une fois l'application en mode maintenance :
| php artisan down --with-secret |
En accédant à cette route cachée, vous serez redirigé vers la route principale (/) de l'application. Une fois le cookie émis dans votre navigateur, vous pourrez naviguer normalement dans l'application, comme si elle n'était pas en mode maintenance.
Votre clef secrète pour le mode maintenance doit généralement être composée de caractères alphanumériques et, éventuellement, de tirets. Évitez d'utiliser des caractères spéciaux dans les URL, tels que ? ou &.
Mode maintenance sur plusieurs serveurs
Par défaut, Laravel détermine si votre application est en mode maintenance à l'aide d'un système de fichiers. Cela signifie que pour activer le mode maintenance, la commande `php artisan down` doit être exécutée sur chaque serveur hébergeant votre application.
Laravel propose également une méthode basée sur le cache pour gérer le mode maintenance. Cette méthode nécessite l'exécution de la commande `php artisan down` sur un seul serveur. Pour utiliser cette approche, modifiez les variables du mode maintenance dans le fichier `.env` de votre application. Choisissez un cache accessible par tous vos serveurs. Cela garantit une mise à jour cohérente du statut du mode maintenance sur chaque serveur :
- APP_MAINTENANCE_DRIVER=cache
- APP_MAINTENANCE_STORE=database
Pré-affichage de la vue en mode maintenance
Si vous utilisez la commande `php artisan down` lors du déploiement, vos utilisateurs peuvent rencontrer des erreurs s'ils accèdent à l'application pendant la mise à jour des dépendances Composer ou d'autres composants d'infrastructure. Cela est dû au fait qu'une partie importante du cadre d'application Laravel doit démarrer pour déterminer que votre application est en mode maintenance et afficher la vue correspondante à l'aide du moteur de gabarits.
C'est pourquoi Laravel vous permet de pré-afficher une vue en mode maintenance qui sera renvoyée au tout début du cycle de requête. Cette vue est affichée avant le chargement de toutes les dépendances de votre application. Vous pouvez pré-afficher un template de votre choix à l'aide de l'option `render` de la commande `down` :
| php artisan down --render="errors::503" |
Redirection des requêtes en mode maintenance
En mode maintenance, Laravel affiche la vue de maintenance pour toutes les URL de l'application auxquelles l'utilisateur tente d'accéder. Vous pouvez configurer Laravel pour qu'il redirige toutes les requêtes vers une URL spécifique. Pour ce faire, utilisez l'option de redirection. Par exemple, vous pouvez rediriger toutes les requêtes vers l'URI `/`.
| php artisan down --redirect=/ |
Désactivation du mode maintenance
Pour désactiver le mode maintenance, utilisez la commande up :
| php artisan up |
Vous pouvez personnaliser le modèle par défaut du mode maintenance en définissant votre propre modèle dans resources/views/errors/503.blade.php.
Mode maintenance et files d'attente
Pendant que votre application est en mode maintenance, aucune tâche en file d'attente ne sera traitée. Le traitement des tâches reprendra normalement une fois le mode maintenance terminé.
Alternatives au mode maintenance
Le mode maintenance nécessitant une interruption de service de quelques secondes, envisagez d'exécuter vos applications sur une plateforme entièrement gérée comme Laravel Cloud pour un déploiement sans interruption avec Laravel.