Stap 2. .env en config-bestanden in Laravel: zo werkt het echt

(Basis — Fase 1)

Introductie

Je eerste Laravel-project draait. Nu wil je de naam van je app aanpassen of een database koppelen, en dan zie je twee dingen: een bestand .env vol variabelen in hoofdletters, en een map config met een stapel PHP-bestanden. Waar pas je nu wat aan? Het goede nieuws is dat hier een simpel systeem achter zit. Zodra je het doorhebt, kom je het in elk Laravel-project weer tegen.

Wat je gaat leren

• Wat het verschil is tussen .env en de bestanden in config/
• Hoe een waarde van .env via een config-bestand in je code terechtkomt
• Hoe je instellingen uitleest met config()
• Hoe je een eigen config-bestand maakt voor je app
• Welke fout bijna iedere beginner maakt met env(), en hoe je die voorkomt

Voorkennis

• Een Laravel-project dat lokaal draait (zie Laravel installeren)
• Je kunt een terminal openen en een php artisan-commando uitvoeren
• Je weet ongeveer wat een PHP-array is

Twee lagen: waarden en structuur

Laravel-configuratie bestaat uit twee lagen die elk hun eigen taak hebben.

.env bevat de waarden die per omgeving verschillen. Op je laptop gebruik je een andere database, andere mail-instellingen en een andere debug-stand dan op je live server. Wachtwoorden en API-keys staan hier ook. Dit bestand gaat daarom nooit mee in Git.

config/ bevat de structuur. Dat zijn gewone PHP-bestanden die een array teruggeven, en ze gaan wél mee in Git. Hier staat welke instellingen je app kent, en per instelling een standaardwaarde als .env niets opgeeft.

De informatie stroomt altijd in één richting:

.env  →  config/*.php (via env())  →  jouw code (via config())

Onthoud vooral die laatste stap: jouw code praat met config(), niet met .env. Verderop zie je waarom dat uitmaakt.

Stap voor stap

Stap 1 — Bekijk je .env

Open .env in de root van je project. Bovenaan staat ongeveer dit:

APP_NAME=Laravel
APP_ENV=local
APP_KEY=base64:...
APP_DEBUG=true
APP_URL=http://localhost

DB_CONNECTION=sqlite

Een paar waarden die je moet kennen:

• APP_ENV: de omgeving waarin je app draait, zoals local of production
• APP_DEBUG: met true krijg je uitgebreide foutmeldingen. Op productie zet je dit altijd op false.
• APP_KEY: de sleutel voor encryptie van sessies en cookies. Is deze leeg? Dan genereer je er een:

php artisan key:generate

Naast .env staat .env.example. Dat is een sjabloon zonder geheimen, en dat bestand gaat wél mee in Git, zodat een collega (of jijzelf op een nieuwe laptop) weet welke variabelen er nodig zijn.

Stap 2 — Pas een waarde aan

Verander de naam van je app:

APP_NAME="Laravel Academy"

Let op de aanhalingstekens. Zonder aanhalingstekens geeft een waarde met een spatie een foutmelding bij het inlezen van .env.

Stap 3 — Zie hoe een config-bestand .env leest

Open config/app.php. Daar staat onder andere:

'name' => env('APP_NAME', 'Laravel'),

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

env('APP_NAME', 'Laravel') betekent: haal APP_NAME uit .env, en gebruik 'Laravel' als die er niet in staat. Het tweede argument is dus je vangnet.

Stap 4 — Lees de config uit in je code

Overal in je app (in een controller, een route of Blade) gebruik je config() met dot notation: eerst de bestandsnaam, dan de sleutel.

$appName = config('app.name');            // "Laravel Academy"
$database = config('database.default');   // "sqlite"

In een Blade-view:

<title>{{ config('app.name') }}</title>

Wil je snel zien wat Laravel daadwerkelijk heeft ingelezen? Gebruik dan:

php artisan config:show app

Of voor een algemeen overzicht van je omgeving:

php artisan about

Stap 5 — Maak een eigen config-bestand

Heeft je app eigen instellingen, zoals het maximale aantal cursisten per klas of een supportadres? Maak dan een eigen bestand. Maak config/academy.php aan:

<?php

return [
    'max_students_per_class' => env('ACADEMY_MAX_STUDENTS', 12),
    'support_email' => env('ACADEMY_SUPPORT_EMAIL', 'info@example.com'),
    'show_beta_banner' => env('ACADEMY_BETA_BANNER', false),
];

Voeg de waarden toe aan .env:

ACADEMY_MAX_STUDENTS=10
ACADEMY_SUPPORT_EMAIL=support@laravel-academy.nl
ACADEMY_BETA_BANNER=true

Zet ze ook in .env.example, zonder echte geheimen:

ACADEMY_MAX_STUDENTS=12
ACADEMY_SUPPORT_EMAIL=
ACADEMY_BETA_BANNER=false

Nu kun je ze overal gebruiken:

@if (config('academy.show_beta_banner'))
    <div class="banner">
        Deze site is in beta. Vragen? Mail {{ config('academy.support_email') }}
    </div>
@endif

Handig om te weten: env() zet true en false in .env automatisch om naar echte booleans. ACADEMY_BETA_BANNER=true werkt dus zoals je verwacht.

Stap 6 — Controleer in welke omgeving je zit

Soms wil je iets alleen lokaal tonen, zoals een debug-balk of testknop:

if (app()->environment('local')) {
    // alleen op je eigen machine
}

In Blade:

@env('local')
    <p>Je draait lokaal.</p>
@endenv

Veelgemaakte fouten

1. env() gebruiken buiten de config-bestanden

Dit werkt lokaal prima, en daardoor is het verraderlijk:

// ❌ in een controller
$max = env('ACADEMY_MAX_STUDENTS', 12);

Op productie draai je (als het goed is) php artisan config:cache. Laravel bundelt dan alle config in één bestand en leest .env daarna niet meer in. Elke env()-aanroep buiten config/ geeft dan null terug, of je standaardwaarde, en je app gedraagt zich ineens anders dan lokaal. De oplossing:

// ✅ altijd via config
$max = config('academy.max_students_per_class');

De vuistregel: env() gebruik je alleen in config/, en overal anders config().

2. .env aangepast, maar er verandert niets

Heb je ooit php artisan config:cache gedraaid, ook lokaal? Dan gebruikt Laravel die cache en negeert het je wijzigingen in .env. Leeg de cache:

php artisan config:clear

3. .env in Git zetten, of .env.example vergeten

Laravel zet .env standaard in .gitignore. Haal het daar niet uit, want dan staan je wachtwoorden en API-keys in je repository. Andersom gaat het ook vaak mis: je voegt een nieuwe variabele toe aan .env, maar niet aan .env.example. De volgende die het project installeert, krijgt dan een app die half werkt zonder duidelijke foutmelding.

Samenvatting

• .env bevat waarden per omgeving en geheimen, en gaat nooit in Git.
• config/ bevat de structuur met standaardwaarden, en gaat wél in Git.
• Config-bestanden lezen .env via env(), en jouw code leest config via config('bestand.sleutel').
• Eigen instellingen horen in een eigen config-bestand, zoals config/academy.php.
• Gebruik env() nooit buiten config/, want na config:cache geeft het null.

Hoe verder?

Nu je weet waar je instellingen staan, is de logische volgende stap je database echt gebruiken. In Je database koppelen en je eerste migration gebruik je de DB_-variabelen uit deze tutorial om je eerste tabel aan te maken.

Leer je liever met iemand naast je die meekijkt als het misgaat? In de klassikale training Laravel 13 voor beginners bouw je in drie dagen een complete mini-app, van .env tot deployment.