Configuration

Introduction

Tous les fichiers de configuration du framework Laravel sont stockés dans le répertoire config/. Chaque option est commentée : ouvrez les fichiers pour découvrir les options disponibles. Ils gèrent de nombreux paramètres essentiels : connexion à la base de données, serveur d’e-mails, URL de l’application, clé de chiffrement, etc.

Commande `about`

La commande Artisan about affiche un aperçu de la configuration, des drivers et de l’environnement de l’application.

php artisan about

Pour cibler une section spécifique, utilisez --only.

php artisan about --only=environment

Pour inspecter en détail un fichier de configuration, config:show est pratique.

php artisan config:show database

Configuration d’environnement (.env)

On souhaite souvent modifier les valeurs de configuration selon l’environnement (par exemple, un driver de cache différent entre local et production). Laravel s’appuie sur la bibliothèque PHP DotEnv. Lors d’une nouvelle installation, un fichier .env.example contenant les variables d’environnement usuelles est présent à la racine, et il est automatiquement copié en .env pendant l’installation.

Pour un travail en équipe, gardez .env.example versionné et à jour. Avec des valeurs placeholders, les autres développeurs savent immédiatement quelles variables d’environnement configurer.

Sécurité du fichier d’environnement

Ne versionnez pas le fichier .env. Chaque développeur/serveur a besoin d’une configuration différente, et l’inclure dans le dépôt risque d’exposer des informations sensibles en cas d’incident.

Laravel propose toutefois une fonctionnalité de chiffrement du fichier d’environnement : dans sa forme chiffrée, il peut être stocké en toute sécurité dans le dépôt.

Fichiers d’environnement supplémentaires

Au démarrage, Laravel vérifie la variable APP_ENV ou l’argument CLI --env. Si présent, il charge le fichier .env.[APP_ENV] s’il existe. Sinon, il utilise le fichier .env par défaut.

Types des variables d’environnement

Toutes les variables du .env sont analysées comme des chaînes, mais des valeurs spéciales permettent à env() de retourner d’autres types.

Valeur dans `.env`	Retour de `env()`
`true`	`(bool) true`
`(true)`	`(bool) true`
`false`	`(bool) false`
`(false)`	`(bool) false`
`empty`	`(string) ''`
`(empty)`	`(string) ''`
`null`	`(null) null`
`(null)`	`(null) null`

Pour une valeur avec espaces, entourez-la de guillemets doubles.

APP_NAME="My Application"

Récupération des variables d’environnement

Toutes les variables du .env sont chargées dans la superglobale $_ENV à la réception d’une requête. Dans les fichiers de configuration, récupérez-les via env().

'debug' => (bool) env('APP_DEBUG', false),

Le second argument est la valeur par défaut retournée si la variable est absente.

Vérifier l’environnement actuel

L’environnement courant est déterminé par APP_ENV. Utilisez la méthode environment de la façade App.

use Illuminate\Support\Facades\App;

$environment = App::environment();

Vous pouvez tester un environnement spécifique en passant un argument.

if (App::environment('local')) {
    // Environnement local
}

if (App::environment(['local', 'staging'])) {
    // Local ou staging
}

Chiffrement des fichiers d’environnement

Les fichiers d’environnement non chiffrés ne doivent pas être versionnés, mais Laravel offre une fonctionnalité pour les chiffrer.

Chiffrement

Pour chiffrer un fichier d’environnement, utilisez la commande env:encrypt.

php artisan env:encrypt

Lors de son exécution, .env est chiffré et son contenu chiffré est enregistré dans un fichier .env.encrypted. La clé de déchiffrement s’affiche en sortie de commande : conservez-la dans un gestionnaire de mots de passe sécurisé. Pour fournir votre propre clé de chiffrement, utilisez l’option --key.

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

La longueur de la clé fournie doit correspondre à celle exigée par le chiffrement utilisé. Par défaut, Laravel utilise le chiffrement AES-256-CBC, qui requiert une clé de 32 caractères. Vous êtes libre d’utiliser n’importe quel chiffrement pris en charge par le chiffrement de Laravel en passant l’option --cipher.

Si votre application dispose de plusieurs fichiers d’environnement, comme .env et .env.staging, vous pouvez spécifier lequel chiffrer via l’option --env.

php artisan env:encrypt --env=staging

Noms de variables lisibles

Lors du chiffrement d’un fichier d’environnement, l’option --readable permet de conserver les noms des variables visibles tout en ne chiffrant que leurs valeurs.

php artisan env:encrypt --readable

Cela produit un fichier chiffré au format suivant :

APP_NAME=eyJpdiI6...
APP_ENV=eyJpdiI6...
APP_KEY=eyJpdiI6...
APP_DEBUG=eyJpdiI6...
APP_URL=eyJpdiI6...

Le format lisible permet de voir quelles variables d’environnement existent sans exposer de données sensibles. Il facilite également la relecture des pull requests, puisque vous pouvez identifier les variables ajoutées, supprimées ou modifiées sans avoir à déchiffrer le fichier. Lors du déchiffrement, Laravel détecte automatiquement le format utilisé, aucune option supplémentaire n’est donc requise pour la commande env:decrypt.

Lors de l’utilisation de l’option --readable, les commentaires et les lignes vides du fichier d’environnement d’origine ne sont pas inclus dans le fichier chiffré généré.

Mise à jour des fichiers d’environnement chiffrés lisibles

Lors de la mise à jour d’un fichier d’environnement chiffré au format lisible, Laravel conserve les valeurs inchangées et supprime les variables qui n’existent plus dans le fichier d’environnement source.

php artisan env:encrypt --readable --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

Le fichier chiffré est créé s’il n’existe pas encore. Lors de la mise à jour d’un fichier existant, fournissez la même clé de chiffrement et le même chiffrement que ceux utilisés lors de sa création. Si le fichier ne peut être déchiffré, la commande échoue sans l’écraser. Pour rechiffrer toutes les valeurs, utilisez l’option --force. Cela permet de changer la clé de chiffrement ou de remplacer un fichier chiffré devenu invalide.

php artisan env:encrypt --readable --force --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

Déchiffrement

Pour déchiffrer un fichier d’environnement, utilisez la commande env:decrypt. Elle nécessite une clé de déchiffrement, que Laravel récupère depuis la variable d’environnement LARAVEL_ENV_ENCRYPTION_KEY.

php artisan env:decrypt

Vous pouvez également fournir la clé directement via l’option --key.

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

Lorsque la commande env:decrypt s’exécute, Laravel déchiffre le contenu du fichier .env.encrypted et l’écrit dans le fichier .env. Utilisez l’option --cipher pour déchiffrer avec un chiffrement personnalisé.

php artisan env:decrypt --key=qUWuNRdfuImXcKxZ --cipher=AES-128-CBC

Si votre application dispose de plusieurs fichiers d’environnement, comme .env et .env.staging, vous pouvez spécifier lequel déchiffrer via l’option --env.

php artisan env:decrypt --env=staging

Pour écraser un fichier d’environnement existant, utilisez l’option --force.

php artisan env:decrypt --force

Accès aux valeurs de configuration

Utilisez la façade Config ou le helper global config() pour accéder aux valeurs depuis n’importe où. Utilisez la « notation point » : nom de fichier et nom d’option.

use Illuminate\Support\Facades\Config;

$value = Config::get('app.timezone');

// Fonction globale équivalente
$value = config('app.timezone');

// Valeur par défaut si absente
$value = config('app.timezone', 'Asia/Tokyo');

Pour modifier une valeur à l’exécution, utilisez Config::set() ou passez un tableau à config().

Config::set('app.timezone', 'America/Chicago');

config(['app.timezone' => 'America/Chicago']);

Des méthodes typées existent et lancent une exception si le type ne correspond pas.

Config::string('config-key');
Config::integer('config-key');
Config::float('config-key');
Config::boolean('config-key');
Config::array('config-key');
Config::collection('config-key');

Cache de configuration

Pour améliorer les performances, mettez toutes les configurations en cache dans un seul fichier.

php artisan config:cache

Cette commande fusionne toutes les options en un fichier unique lu rapidement par le framework.

Lancez config:cache dans votre pipeline de déploiement en production. Évitez-la en développement local où les configurations changent souvent.

Une fois le cache créé, le .env n’est plus lu pendant les requêtes ni pour les commandes Artisan. env() ne renvoie alors que les variables système.

Pour cette raison, appelez toujours env() uniquement dans les fichiers du répertoire config/. Ailleurs, utilisez config().

Pour vider le cache :

php artisan config:clear

Publication des fichiers de configuration

Beaucoup de fichiers sont déjà publiés dans config/, mais certains (cors.php, view.php, etc.) ne le sont pas par défaut. Publiez-les avec config:publish.

php artisan config:publish

php artisan config:publish --all

Mode debug

L’option debug de config/app.php détermine le niveau d’information d’erreur affiché à l’utilisateur. Par défaut, elle suit la valeur de APP_DEBUG dans .env.

En production, APP_DEBUG doit être à false. Si true, les paramètres sensibles de l’application peuvent être exposés aux utilisateurs.

# Développement local
APP_DEBUG=true

# Production
APP_DEBUG=false

Mode maintenance

Quand l’application est en mode maintenance, une vue personnalisée est affichée pour toutes les requêtes. Cela permet de la « désactiver » temporairement pendant une mise à jour ou une opération de maintenance.

Activer le mode maintenance

php artisan down

L’option --refresh recharge automatiquement le navigateur après le nombre de secondes indiqué.

php artisan down --refresh=15

L’option --retry définit la valeur de l’en-tête HTTP Retry-After.

php artisan down --retry=60

Contourner le mode maintenance

Utilisez --secret pour n’autoriser que certains utilisateurs via un token.

php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"

Avec --with-secret, Laravel génère automatiquement le token.

php artisan down --with-secret

Mode maintenance sur plusieurs serveurs

Par défaut, Laravel gère la maintenance via un fichier. Pour un déploiement multi-serveurs, préférez la méthode basée sur le cache.

APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database

Pré-rendu de la vue maintenance

Pendant php artisan down, si des utilisateurs accèdent au site alors que les dépendances sont en cours de mise à jour, ils peuvent voir une erreur. Utilisez --render pour pré-rendre la vue.

php artisan down --render="errors::503"

Vous pouvez aussi rediriger toutes les requêtes vers une URL pendant la maintenance.

php artisan down --redirect=/

Désactiver le mode maintenance

php artisan up

Personnalisez le template par défaut du mode maintenance en créant resources/views/errors/503.blade.php.

Pour éliminer totalement l’interruption, envisagez une plateforme entièrement managée comme Laravel Cloud.

Prochaines étapes

Routage

Apprenez les bases du routage qui lie URL et contrôleurs.

Pour commencer

Bases

Traitement des requêtes

Base de données

Authentification

Helpers et communication externe

Tests et déploiement

Assistance au développement IA

Introduction

Commande `about`

Configuration d’environnement (.env)

Sécurité du fichier d’environnement

Fichiers d’environnement supplémentaires

Types des variables d’environnement

Récupération des variables d’environnement

Vérifier l’environnement actuel

Chiffrement des fichiers d’environnement

Chiffrement

Noms de variables lisibles

Mise à jour des fichiers d’environnement chiffrés lisibles

Déchiffrement

Accès aux valeurs de configuration

Cache de configuration

Publication des fichiers de configuration

Mode debug

Mode maintenance

Activer le mode maintenance

Contourner le mode maintenance

Mode maintenance sur plusieurs serveurs

Pré-rendu de la vue maintenance

Désactiver le mode maintenance

Prochaines étapes

Routage

​Introduction

​Commande about

​Configuration d’environnement (.env)

​Sécurité du fichier d’environnement

​Fichiers d’environnement supplémentaires

​Types des variables d’environnement

​Récupération des variables d’environnement

​Vérifier l’environnement actuel

​Chiffrement des fichiers d’environnement

​Chiffrement

​Noms de variables lisibles

​Mise à jour des fichiers d’environnement chiffrés lisibles

​Déchiffrement

​Accès aux valeurs de configuration

​Cache de configuration

​Publication des fichiers de configuration

​Mode debug

​Mode maintenance

​Activer le mode maintenance

​Contourner le mode maintenance

​Mode maintenance sur plusieurs serveurs

​Pré-rendu de la vue maintenance

​Désactiver le mode maintenance

​Prochaines étapes

Routage

Introduction

Commande `about`

Configuration d’environnement (.env)

Sécurité du fichier d’environnement

Fichiers d’environnement supplémentaires

Types des variables d’environnement

Récupération des variables d’environnement

Vérifier l’environnement actuel

Chiffrement des fichiers d’environnement

Chiffrement

Noms de variables lisibles

Mise à jour des fichiers d’environnement chiffrés lisibles

Déchiffrement

Accès aux valeurs de configuration

Cache de configuration

Publication des fichiers de configuration

Mode debug

Mode maintenance

Activer le mode maintenance

Contourner le mode maintenance

Mode maintenance sur plusieurs serveurs

Pré-rendu de la vue maintenance

Désactiver le mode maintenance

Prochaines étapes