Anwendungsstruktur ab Laravel 11 - Knowledge of Laravel

Vergleich mit Laravel 10 und älter

Mit Laravel 11 wurde die Anwendungsstruktur als „Slim Application Skeleton” grundlegend überarbeitet. Die größte Änderung: verstreute Einstellungen werden nun an einer einzigen Stelle in bootstrap/app.php gebündelt.

Aspekt	Laravel 10 und älter	Laravel 11 und höher
HTTP-Kernel	`app/Http/Kernel.php`	Entfällt (in das Framework integriert)
Console-Kernel	`app/Console/Kernel.php`	Entfällt (in `routes/console.php` verschoben)
Exception-Handler	`app/Exceptions/Handler.php`	Entfällt (in `bootstrap/app.php` gebündelt)
Service Provider	5 Dateien	Nur noch `AppServiceProvider.php`
Routen-Dateien	`web.php` / `api.php` standardmäßig	Nur `web.php` standard, `api.php` per Opt-in
Bootstrap	Einstellungen auf mehrere Dateien verteilt	In `bootstrap/app.php` gebündelt
Standard-DB	MySQL/PostgreSQL	SQLite

Diese Änderung betrifft neue Projekte. Bestehende Laravel-10-Anwendungen laufen nach einem Upgrade in ihrer alten Struktur weiter.

Neue Verzeichnis- und Dateistruktur

Struktur des Skeletons

laravel-app/
├── app/
│   ├── Http/
│   │   └── Controllers/
│   ├── Models/
│   │   └── User.php
│   └── Providers/
│       └── AppServiceProvider.php
├── bootstrap/
│   ├── app.php          ← Zentraler Punkt der App-Konfiguration
│   ├── cache/
│   └── providers.php    ← Liste der Service Provider
├── config/
├── database/
├── public/
│   └── index.php        ← Einstiegspunkt
├── resources/
├── routes/
│   ├── web.php          ← Web-Routen (Standard)
│   └── console.php      ← Artisan-Commands und Scheduler
├── storage/
└── tests/

`bootstrap/app.php` — Zentrum der Konfiguration

<?php

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware): void {
        //
    })
    ->withExceptions(function (Exceptions $exceptions): void {
        //
    })->create();

Mit dieser einen Datei konfigurieren Sie Routing, Middleware und Exception-Handling. Was in Laravel 10 auf app/Http/Kernel.php, app/Console/Kernel.php und app/Exceptions/Handler.php verteilt war, ist hier zusammengefasst.

`bootstrap/providers.php` — Liste der Service Provider

<?php

use App\Providers\AppServiceProvider;

return [
    AppServiceProvider::class,
];

Diese Datei registriert die Service Provider. In Laravel 10 stand das im providers-Array von config/app.php; jetzt ist es in bootstrap/providers.php getrennt. Standardmäßig ist nur der AppServiceProvider eingetragen.

Beim composer require eines Pakets aktualisiert dieses ggf. bootstrap/providers.php automatisch. config/app.php wird zwar noch gelesen, aber Neuregistrierungen erfolgen bevorzugt in bootstrap/providers.php.

Änderungen am `routes/`-Verzeichnis

routes/
├── web.php      ← Web-Routen (standardmäßig geladen)
└── console.php  ← Artisan-Commands und Scheduler-Definitionen

api.php und channels.php sind standardmäßig nicht vorhanden. Erzeugen Sie sie bei Bedarf per Artisan.

# API-Routen ergänzen (api.php + Sanctum installieren)
php artisan install:api

# Broadcasting ergänzen (channels.php + Reverb installieren)
php artisan install:broadcasting

In routes/console.php können Sie auch Scheduler-Aufgaben definieren.

<?php

use Illuminate\Foundation\Inspiring;
use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Facades\Schedule;

Artisan::command('inspire', function () {
    $this->comment(Inspiring::quote());
})->purpose('Display an inspiring quote');

Schedule::command('emails:send')->daily();

Entfallene Dateien

Wegfall von app/Http/Kernel.php

Der HTTP-Kernel ist in Illuminate\Foundation\Http\Kernel im Framework integriert. Middleware-Anpassungen erfolgen über withMiddleware() in bootstrap/app.php.

// Laravel 10: app/Http/Kernel.php
protected $middleware = [
    \Illuminate\Http\Middleware\TrustProxies::class,
    // ...
];

protected $middlewareGroups = [
    'web' => [
        \App\Http\Middleware\EncryptCookies::class,
        // ...
    ],
];

// Laravel 11+: bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        EnsureUserIsSubscribed::class,
    ]);

    $middleware->validateCsrfTokens(except: ['stripe/*']);
})

Wegfall von app/Console/Kernel.php

Die beiden Aufgaben des Console-Kernels sind getrennt: Artisan-Commands liegen in app/Console/Commands/ und werden automatisch erkannt, Scheduler-Definitionen stehen in routes/console.php.

// Laravel 10: app/Console/Kernel.php
protected function schedule(Schedule $schedule): void
{
    $schedule->command('emails:send')->daily();
}

// Laravel 11+: routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('emails:send')->daily();

Wegfall von app/Exceptions/Handler.php

Der Exception-Handler ist in Illuminate\Foundation\Exceptions\Handler im Framework integriert. Anpassungen erfolgen über withExceptions() in bootstrap/app.php.

// Laravel 10: app/Exceptions/Handler.php
public function register(): void
{
    $this->reportable(function (InvalidOrderException $e) {
        // ...
    });
}

// Laravel 11+: bootstrap/app.php
->withExceptions(function (Exceptions $exceptions) {
    $exceptions->report(function (InvalidOrderException $e) {
        // ...
    });
})

Wie `Application::configure()` funktioniert

Implementierung im Framework

Application::configure() ist eine statische Methode von Illuminate\Foundation\Application.

// Aus Illuminate\Foundation\Application
public static function configure(?string $basePath = null)
{
    $basePath = match (true) {
        is_string($basePath) => $basePath,
        default => static::inferBasePath(),
    };

    return (new Configuration\ApplicationBuilder(new static($basePath)))
        ->withKernels()
        ->withEvents()
        ->withCommands()
        ->withProviders();
}

Die Methode:

Bestimmt aus basePath das Wurzelverzeichnis der Anwendung.
Erzeugt eine Application-Instanz.
Verpackt sie in einem ApplicationBuilder und wendet Standardeinstellungen an.
Gibt den ApplicationBuilder zurück.

Wichtig: In configure() werden bereits withKernels(), withEvents(), withCommands() und withProviders() aufgerufen — in bootstrap/app.php müssen Sie sie nicht erneut aufrufen.

Konfiguration per Method-Chain

Application::configure(basePath: dirname(__DIR__))  // liefert ApplicationBuilder
    ->withRouting(...)       // konfiguriert Routing, gibt $this zurück
    ->withMiddleware(...)    // konfiguriert Middleware, gibt $this zurück
    ->withExceptions(...)    // konfiguriert Exception-Handling, gibt $this zurück
    ->create();              // gibt die Application-Instanz zurück

create() extrahiert aus dem ApplicationBuilder die Application; genau diese Instanz gibt bootstrap/app.php per return zurück.

Ablauf vom Request bis zum App-Start

public/index.php ist der Einstiegspunkt; die Datei lädt bootstrap/app.php und erhält die Application. Danach führt der HTTP-Kernel den Request durch die Middleware-Pipeline, der Router dispatched an den Controller.

Wichtige Methoden des `ApplicationBuilder` im Detail

`withRouting()` — interne Routen-Registrierung

public function withRouting(
    ?Closure $using = null,
    array|string|null $web = null,
    array|string|null $api = null,
    ?string $commands = null,
    ?string $channels = null,
    ?string $pages = null,
    ?string $health = null,
    string $apiPrefix = 'api',
    ?callable $then = null
)

Intern wird an AppRouteServiceProvider::loadRoutesUsing() ein Callback registriert; beim Booting wird der AppRouteServiceProvider eingehängt.

// Vereinfachte interne Verarbeitung von withRouting()
protected function buildRoutingCallback(...)
{
    return function () use ($web, $api, $pages, $health, $apiPrefix, $then) {
        if (is_string($api) || is_array($api)) {
            Route::middleware('api')->prefix($apiPrefix)->group($api);
        }

        if (is_string($health)) {
            Route::get($health, function () {
                Event::dispatch(new DiagnosingHealth);
                return response(View::file(...), status: 200);
            });
        }

        if (is_string($web) || is_array($web)) {
            Route::middleware('web')->group($web);
        }

        if (is_callable($then)) {
            $then($this->app);
        }
    };
}

Wichtige Punkte:

Für api-Routen werden automatisch die Middleware-Gruppe api und der Prefix /api angewandt.
Ein String an health registriert einen Health-Check-Endpoint (Default /up) automatisch.
Der health-Pfad ist im Wartungsmodus ausgeschlossen (PreventRequestsDuringMaintenance::except()).
api wird vor web registriert. Bei identischen Pfaden hat api Vorrang.
Ein String an pages aktiviert das Routing von Laravel Folio.

`withMiddleware()` — Middleware anpassen

public function withMiddleware(?callable $callback = null)
{
    $this->app->afterResolving(HttpKernel::class, function ($kernel) use ($callback) {
        $middleware = (new Middleware)
            ->redirectGuestsTo(fn () => route('login'));

        if (! is_null($callback)) {
            $callback($middleware);
        }

        $kernel->setGlobalMiddleware($middleware->getGlobalMiddleware());
        $kernel->setMiddlewareGroups($middleware->getMiddlewareGroups());
        $kernel->setMiddlewareAliases($middleware->getMiddlewareAliases());
        // ...
    });

    return $this;
}

withMiddleware() führt den Callback aus, nachdem der HttpKernel aufgelöst wurde — mittels afterResolving(). Dem Callback wird ein Middleware-Objekt mit vielen Anpassungsmethoden übergeben.

->withMiddleware(function (Middleware $middleware) {
    // Globale Middleware anhängen
    $middleware->append(MyGlobalMiddleware::class);

    // Middleware zur web-Gruppe hinzufügen
    $middleware->web(append: [EnsureUserIsSubscribed::class]);

    // Middleware in der api-Gruppe ersetzen
    $middleware->api(replace: [
        OldMiddleware::class => NewMiddleware::class,
    ]);

    // Pfade vom CSRF-Schutz ausnehmen
    $middleware->validateCsrfTokens(except: ['stripe/*', 'webhook/*']);

    // Weiterleitung für Gäste ändern
    $middleware->redirectGuestsTo('/custom-login');

    // Priorität setzen
    $middleware->priority([
        \Illuminate\Session\Middleware\StartSession::class,
        \Illuminate\View\Middleware\ShareErrorsFromSession::class,
    ]);
})

`withExceptions()` — Exception-Handling konfigurieren

public function withExceptions(?callable $using = null)
{
    $this->app->singleton(
        \Illuminate\Contracts\Debug\ExceptionHandler::class,
        \Illuminate\Foundation\Exceptions\Handler::class
    );

    if ($using !== null) {
        $this->app->afterResolving(
            \Illuminate\Foundation\Exceptions\Handler::class,
            fn ($handler) => $using(new Exceptions($handler)),
        );
    }

    return $this;
}

withExceptions() registriert die Handler-Klasse als Singleton und setzt den Callback per afterResolving(). Dem Callback wird ein Exceptions-Wrapper übergeben.

->withExceptions(function (Exceptions $exceptions) {
    // Bestimmte Exceptions nicht melden
    $exceptions->dontReport(MissedFlightException::class);

    // Eigenes Reporting für bestimmte Exceptions
    $exceptions->report(function (InvalidOrderException $e) {
        // z. B. Slack benachrichtigen
    });

    // HTTP-Response bestimmter Exceptions anpassen
    $exceptions->render(function (NotFoundHttpException $e, Request $request) {
        if ($request->is('api/*')) {
            return response()->json(['message' => 'Not Found'], 404);
        }
    });

    // Throttling (nicht dieselbe Exception in Folge melden)
    $exceptions->throttle(function (Throwable $e) {
        return Limit::perMinute(20);
    });
})

`withProviders()` — Service Provider registrieren

public function withProviders(array $providers = [], bool $withBootstrapProviders = true)
{
    RegisterProviders::merge(
        $providers,
        $withBootstrapProviders
            ? $this->app->getBootstrapProvidersPath()
            : null
    );

    return $this;
}

Da withProviders() innerhalb von Application::configure() automatisch aufgerufen wird, lädt Laravel bootstrap/providers.php von selbst. Für zusätzliche Provider rufen Sie es in bootstrap/app.php explizit auf.

Application::configure(basePath: dirname(__DIR__))
    ->withProviders([
        // Zusätzlich zur bootstrap/providers.php Provider hinzufügen
        App\Providers\CustomServiceProvider::class,
    ])
    ->withRouting(...)
    ->create();

withBootstrapProviders: false überspringt bootstrap/providers.php. Nur mit gutem Grund weglassen.

Weitere wichtige Methoden

Methode	Beschreibung
`withKernels()`	Registriert HTTP-/Console-Kernel als Singleton. Wird von `configure()` automatisch aufgerufen.
`withEvents()`	Aktiviert Event-Discovery. Wird von `configure()` automatisch aufgerufen.
`withCommands(array $commands)`	Fügt zusätzliche Artisan-Commands oder Command-Verzeichnisse hinzu.
`withSchedule(callable $callback)`	Scheduler-Definitionen in `bootstrap/app.php` ablegen.
`withBroadcasting(string $channels)`	Broadcasting-Channels-Datei registrieren.
`withBindings(array $bindings)`	Container-Bindings registrieren.
`withSingletons(array $singletons)`	Singleton-Bindings registrieren.
`registered(callable $callback)`	Callback, nachdem Service Provider registriert wurden.
`booting(callable $callback)`	Callback während des Bootings.
`booted(callable $callback)`	Callback nach dem Booting.
`create()`	Gibt die `Application`-Instanz zurück.

Designintention: warum es so ist

„Code-First”-Konfiguration

In app/Http/Kernel.php (Laravel 10) wurde Middleware als Array aufgelistet — eher wie eine Config-Datei. Das erschwerte Typunterstützung und IDE-Feedback. In Laravel 11 hat sich das zu einem Callback-Stil geändert: withMiddleware(function (Middleware $middleware) { ... }). So funktioniert Typvervollständigung, und Sie schreiben Verzweigungen oder Schleifen natürlich für dynamische Konfiguration.

Von „Convention over Configuration” zu „Explicit Configuration”

api.php ist Opt-in geworden, damit Anwendungen ohne API-Routen nicht permanent die api-Middleware-Gruppe laden. Was nicht gebraucht wird, existiert per Default nicht.

Nutzung von `afterResolving()`-Hooks

withMiddleware() und withExceptions() verwenden afterResolving(), um Konfigurationsreihenfolge-Probleme zu vermeiden. Die Methoden am ApplicationBuilder werden vor dem vollständigen Start aufgerufen; die tatsächliche Anwendung erfolgt verzögert beim ersten Auflösen des Kernels.

Praktische Anpassungsbeispiele

API und Web nebeneinander

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
        apiPrefix: 'api/v1',  // Standard /api geändert
    )
    ->withMiddleware(function (Middleware $middleware): void {
        //
    })
    ->withExceptions(function (Exceptions $exceptions): void {
        //
    })->create();

Middleware anpassen

->withMiddleware(function (Middleware $middleware) {
    // Authentifizierungs-Check für Web-Routen
    $middleware->web(append: [
        \App\Http\Middleware\EnsureEmailIsVerified::class,
    ]);

    // Bestimmte Middleware für API-Routen entfernen
    $middleware->api(remove: [
        \Illuminate\Session\Middleware\StartSession::class,
    ]);

    // Webhook-Endpoints vom CSRF-Schutz ausnehmen
    $middleware->validateCsrfTokens(except: [
        'webhook/*',
        'stripe/webhook',
    ]);

    // Alias vergeben
    $middleware->alias([
        'subscribed' => \App\Http\Middleware\EnsureUserIsSubscribed::class,
    ]);
})

Scheduler in `bootstrap/app.php` bündeln

Sie können den Scheduler in routes/console.php beschreiben — oder alles über withSchedule() in bootstrap/app.php bündeln.

use Illuminate\Console\Scheduling\Schedule;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withSchedule(function (Schedule $schedule) {
        $schedule->command('emails:send')->daily();
        $schedule->command('reports:generate')->weeklyOn(1, '8:00');
        $schedule->job(new PruneOldRecords)->daily();
    })
    ->withMiddleware(function (Middleware $middleware): void {
        //
    })
    ->withExceptions(function (Exceptions $exceptions): void {
        //
    })->create();

Exception-Handling anpassen

->withExceptions(function (Exceptions $exceptions) {
    // API-Requests immer als JSON beantworten
    $exceptions->render(function (Throwable $e, Request $request) {
        if ($request->is('api/*') || $request->wantsJson()) {
            $status = match (true) {
                $e instanceof NotFoundHttpException => 404,
                $e instanceof AuthenticationException => 401,
                $e instanceof AuthorizationException => 403,
                $e instanceof ValidationException => 422,
                default => 500,
            };

            return response()->json([
                'message' => $e->getMessage(),
            ], $status);
        }
    });

    // Nur in Produktion Slack benachrichtigen
    if (app()->isProduction()) {
        $exceptions->report(function (Throwable $e) {
            app(SlackNotifier::class)->notify($e);
        })->stop();
    }
})

Container-Bindings in `bootstrap/app.php` verwalten

In kleinen Anwendungen können Sie einfache Bindings statt im AppServiceProvider direkt in bootstrap/app.php beschreiben.

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(...)
    ->withSingletons([
        \App\Contracts\PaymentGateway::class => \App\Services\StripeGateway::class,
        \App\Contracts\MailService::class => \App\Services\SendgridMailService::class,
    ])
    ->withMiddleware(...)
    ->withExceptions(...)
    ->create();

Reihenfolge des Anwendungsstarts

Beim Start der Laravel-Anwendung laufen Service Provider und Application-Hooks in dieser Reihenfolge:

register() aller Service Provider.
registered() der Application.
booting() der Application.
boot() aller Service Provider.
booted() der Application.

Mit folgendem Code im AppServiceProvider lässt sich das nachverfolgen.

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        info('1. AppServiceProvider register');

        $this->booting(function () {
            info('4. AppServiceProvider booting');
        });

        $this->booted(function () {
            info('5. AppServiceProvider booted');
        });

        $this->app->registered(function () {
            info('2. app registered');
        });

        $this->app->booting(function () {
            info('3. app booting');
        });

        $this->app->booted(function () {
            info('6. AppServiceProvider@register app booted');
        });
    }

    public function boot(): void
    {
        $this->app->booted(function () {
            info('7. AppServiceProvider@boot app booted');
        });
    }
}

registered(), booting() und booted() am ApplicationBuilder registrieren nur Callbacks. Üblicherweise braucht man sie nicht, aber sie erlauben Sonderfälle — etwa Anpassungen am bereits gebooteten Kernel per booted().

// bootstrap/app.php

use Illuminate\Contracts\Http\Kernel;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(...)
    ->withMiddleware(...)
    ->withExceptions(...)
    ->booted(function (Application $app) {
        $kernel = $app->make(Kernel::class);

        //

        $app->instance(Kernel::class, $kernel);
    })
    ->create();

Nächste Schritte

Service Container

Verstehen Sie den Service Container, den der ApplicationBuilder intern nutzt.

FAQ zur neuen App-Struktur

Häufige Fragen und Antworten zur neuen Anwendungsstruktur.

​Vergleich mit Laravel 10 und älter

​Neue Verzeichnis- und Dateistruktur

​Struktur des Skeletons

​bootstrap/app.php — Zentrum der Konfiguration

​bootstrap/providers.php — Liste der Service Provider

​Änderungen am routes/-Verzeichnis

​Entfallene Dateien

​Wie Application::configure() funktioniert

​Implementierung im Framework

​Konfiguration per Method-Chain

​Ablauf vom Request bis zum App-Start

​Wichtige Methoden des ApplicationBuilder im Detail

​withRouting() — interne Routen-Registrierung

​withMiddleware() — Middleware anpassen

​withExceptions() — Exception-Handling konfigurieren

​withProviders() — Service Provider registrieren

​Weitere wichtige Methoden

​Designintention: warum es so ist

​„Code-First”-Konfiguration

​Von „Convention over Configuration” zu „Explicit Configuration”

​Nutzung von afterResolving()-Hooks

​Praktische Anpassungsbeispiele

​API und Web nebeneinander

​Middleware anpassen

​Scheduler in bootstrap/app.php bündeln

​Exception-Handling anpassen

​Container-Bindings in bootstrap/app.php verwalten

​Reihenfolge des Anwendungsstarts

​Nächste Schritte

Service Container

FAQ zur neuen App-Struktur

Vergleich mit Laravel 10 und älter

Neue Verzeichnis- und Dateistruktur

Struktur des Skeletons

`bootstrap/app.php` — Zentrum der Konfiguration

`bootstrap/providers.php` — Liste der Service Provider

Änderungen am `routes/`-Verzeichnis

Entfallene Dateien

Wie `Application::configure()` funktioniert

Implementierung im Framework

Konfiguration per Method-Chain

Ablauf vom Request bis zum App-Start

Wichtige Methoden des `ApplicationBuilder` im Detail

`withRouting()` — interne Routen-Registrierung

`withMiddleware()` — Middleware anpassen

`withExceptions()` — Exception-Handling konfigurieren

`withProviders()` — Service Provider registrieren

Weitere wichtige Methoden

Designintention: warum es so ist

„Code-First”-Konfiguration

Von „Convention over Configuration” zu „Explicit Configuration”

Nutzung von `afterResolving()`-Hooks

Praktische Anpassungsbeispiele

API und Web nebeneinander

Middleware anpassen

Scheduler in `bootstrap/app.php` bündeln

Exception-Handling anpassen

Container-Bindings in `bootstrap/app.php` verwalten

Reihenfolge des Anwendungsstarts

Nächste Schritte