> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Fichiers de configuration Laravel, variables d'environnement (.env), accès aux valeurs, cache, mode debug et mode maintenance.

## 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.

```mermaid theme={null}
flowchart LR
    A["Fichier .env"] -->|env()| B["Fichiers config/"]
    B -->|config()| C["Application"]
```

### Commande `about`

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

```shell theme={null}
php artisan about
```

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

```shell theme={null}
php artisan about --only=environment
```

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

```shell theme={null}
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](https://github.com/vlucas/phpdotenv). 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.

<Info>
  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.
</Info>

### Sécurité du fichier d'environnement

<Warning>
  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.
</Warning>

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.

```ini theme={null}
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()`.

```php theme={null}
'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`.

```php theme={null}
use Illuminate\Support\Facades\App;

$environment = App::environment();
```

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

```php theme={null}
if (App::environment('local')) {
    // Environnement local
}

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

### Chiffrement du fichier d'environnement

Un fichier `.env` non chiffré ne doit pas être versionné, mais Laravel permet de le chiffrer.

```shell theme={null}
php artisan env:encrypt
```

Le `.env` est chiffré dans `.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 déchiffrer :

```shell theme={null}
php artisan env:decrypt
```

## 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.

```php theme={null}
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()`.

```php theme={null}
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.

```php theme={null}
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.

```shell theme={null}
php artisan config:cache
```

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

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

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.

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

Pour vider le cache :

```shell theme={null}
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`.

```shell theme={null}
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`.

<Warning>
  **En production, `APP_DEBUG` doit être à `false`.** Si `true`, les paramètres sensibles de l'application peuvent être exposés aux utilisateurs.
</Warning>

```ini theme={null}
# 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

```shell theme={null}
php artisan down
```

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

```shell theme={null}
php artisan down --refresh=15
```

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

```shell theme={null}
php artisan down --retry=60
```

### Contourner le mode maintenance

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

```shell theme={null}
php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"
```

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

```shell theme={null}
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.

```ini theme={null}
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.

```shell theme={null}
php artisan down --render="errors::503"
```

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

```shell theme={null}
php artisan down --redirect=/
```

### Désactiver le mode maintenance

```shell theme={null}
php artisan up
```

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

<Tip>
  Pour éliminer totalement l'interruption, envisagez une plateforme entièrement managée comme [Laravel Cloud](https://cloud.laravel.com).
</Tip>

## Prochaines étapes

<Card title="Routage" icon="route" href="/fr/routing">
  Apprenez les bases du routage qui lie URL et contrôleurs.
</Card>


## Related topics

- [WebSocket (Jetstream / Firehose)](/fr/packages/laravel-bluesky/websocket.md)
- [Hachage (Hashing)](/fr/hashing.md)
- [Labeler](/fr/packages/laravel-bluesky/labeler.md)
- [Journalisation](/fr/logging.md)
- [Réinitialisation du mot de passe](/fr/passwords.md)