Interne Struktur der automatischen Paket-Erkennung

Über diese Seite

Unter Grundlagen der Paketentwicklung haben wir vorgestellt, dass Service Provider und Facades automatisch registriert werden, sobald Sie den Abschnitt extra.laravel in der composer.json angeben. Auf dieser Seite erläutern wir die Interna dahinter, konkret die Funktionsweise der Klasse Illuminate\Foundation\PackageManifest auf Quellcode-Ebene.

Diese Seite ist die Ergänzung zu Grundlagen der Paketentwicklung. Wir empfehlen, die Grundlagen der automatischen Erkennung zuerst zu lesen.

Gesamtüberblick zur automatischen Erkennung

Die Klasse `PackageManifest`

Der Kern der automatischen Erkennung ist Illuminate\Foundation\PackageManifest. Nachfolgend eine Zusammenfassung der Implementierung zum Zeitpunkt von Framework 13.x.

class PackageManifest
{
    public function providers()
    {
        return $this->config('providers');
    }

    public function aliases()
    {
        return $this->config('aliases');
    }

    public function config($key)
    {
        return (new Collection($this->getManifest()))
            ->flatMap(fn ($configuration) => (array) ($configuration[$key] ?? []))
            ->filter()
            ->all();
    }

    protected function getManifest()
    {
        if (! is_null($this->manifest)) {
            return $this->manifest;
        }

        if (! is_file($this->manifestPath)) {
            $this->build();
        }

        return $this->manifest = is_file($this->manifestPath)
            ? $this->files->getRequire($this->manifestPath)
            : [];
    }
}

Wichtig sind die folgenden drei Punkte:

Das Manifest wird nach dem ersten Laden im Speicher zwischengespeichert (Property $this->manifest). Wenn providers() innerhalb eines Requests mehrfach aufgerufen wird, entsteht nur ein einziger Datei-I/O.
build() wird ausschließlich dann ausgeführt, wenn die Manifest-Datei nicht existiert. Im normalen Betrieb wird das Manifest also nicht bei jedem Aufruf neu gebaut.
Die tatsächliche Datei ist eine schlichte PHP-Datei, die ein Array returnt (bootstrap/cache/packages.php) — das schnellstmögliche Format, da require genügt.

Bau des Manifests

Die Methode build() ist der Teil, der die Informationen aus der composer.json tatsächlich zusammenträgt.

public function build()
{
    $packages = [];

    if ($this->files->exists($path = $this->vendorPath.'/composer/installed.json')) {
        $installed = json_decode($this->files->get($path), true);
        $packages = $installed['packages'] ?? $installed;
    }

    $ignoreAll = in_array('*', $ignore = $this->packagesToIgnore());

    $this->write((new Collection($packages))->mapWithKeys(function ($package) {
        return [$this->format($package['name']) => $package['extra']['laravel'] ?? []];
    })->each(function ($configuration) use (&$ignore) {
        $ignore = array_merge($ignore, $configuration['dont-discover'] ?? []);
    })->reject(function ($configuration, $package) use ($ignore, $ignoreAll) {
        return $ignoreAll || in_array($package, $ignore);
    })->filter()->all());
}

Wichtig ist, dass nicht die composer.json direkt geparst wird, sondern vendor/composer/installed.json gelesen wird. Diese Datei wird von Composer bei composer install bzw. composer update erzeugt und enthält die Metadaten aller installierten Pakete. Da die Abschnitte extra aus den composer.json-Dateien der einzelnen Pakete hier gebündelt sind, greift Laravel ausschließlich auf die von Composer verwalteten Informationen zurück.

installed.json ist üblicherweise in .gitignore enthalten, daher funktioniert die automatische Erkennung beim initialen Setup (wenn noch kein vendor/ existiert) nicht. Der Cache wird erst nach Abschluss von composer install aufgebaut.

Zwei Schreibweisen für `dont-discover`

dont-discover kann sowohl in der composer.json eines Pakets als auch der Anwendung stehen, hat aber unterschiedliche Bedeutungen.

composer.json auf Paketseite

"extra": {
    "laravel": {
        "providers": ["Acme\\Courier\\CourierServiceProvider"],
        "dont-discover": []
    }
}

composer.json auf Anwendungsseite

"extra": {
    "laravel": {
        "dont-discover": [
            "acme/courier"
        ]
    }
}

Wie die Implementierung von build() zeigt, wird das Array $ignore per array_merge mit den configuration['dont-discover']-Einträgen jedes Pakets gefüllt. Technisch ist es somit auch möglich, dass ein Paket selbst „die automatische Erkennung seiner eigenen Abhängigkeiten deaktiviert” — etwa, wenn ein intern verwendetes Sub-Paket sonst doppelt registriert würde. In der Praxis wird jedoch meist auf Anwendungsseite deaktiviert.

`*` in `dont-discover` angeben

Enthält das von packagesToIgnore() zurückgegebene Array den Wert *, wird $ignoreAll = true — und damit die automatische Erkennung für sämtliche Pakete deaktiviert. Nützlich in CI- oder Testumgebungen, um den Overhead der automatischen Erkennung zu vermeiden, oder wenn Sie in bootstrap/providers.php alles vollständig manuell verwalten möchten.

"extra": {
    "laravel": {
        "dont-discover": ["*"]
    }
}

Die Cache-Datei

getCachedPackagesPath() gibt die Umgebungsvariable APP_PACKAGES_CACHE zurück, falls gesetzt, andernfalls bootstrap/cache/packages.php.

public function getCachedPackagesPath()
{
    return $this->normalizeCachePath('APP_PACKAGES_CACHE', 'cache/packages.php');
}

Wenn Sie diese Datei direkt öffnen, sehen Sie, dass sie lediglich ein einfaches assoziatives Array returnt.

<?php return array (
  'acme/courier' => 
  array (
    'providers' => 
    array (
      0 => 'Acme\\Courier\\CourierServiceProvider',
    ),
  ),
);

Da der Paketname als Schlüssel dient, können Sie an der Ausgabe von php artisan package:discover ablesen, welche Pakete erkannt wurden.

Wann der Cache neu aufgebaut wird

Illuminate\Foundation\ComposerScripts hängt sich in drei Composer-Events ein, die alle dieselbe Methode clearCompiled() aufrufen.

public static function postInstall(Event $event)
{
    require_once $event->getComposer()->getConfig()->get('vendor-dir').'/autoload.php';
    static::clearCompiled();
}

protected static function clearCompiled()
{
    $laravel = new Application(getcwd());

    if (is_file($configPath = $laravel->getCachedConfigPath())) {
        @unlink($configPath);
    }

    if (is_file($servicesPath = $laravel->getCachedServicesPath())) {
        @unlink($servicesPath);
    }

    if (is_file($packagesPath = $laravel->getCachedPackagesPath())) {
        @unlink($packagesPath);
    }
}

Egal, ob Sie also composer install, composer update oder composer dump-autoload ausführen — der Konfigurations-, Services- und Paket-Cache werden alle zusammen gelöscht. Beim nächsten Start von Laravel wird PackageManifest::build() ausgeführt und der Cache aus dem aktuellen Stand der installed.json neu erstellt. Dies ist das Standardverhalten eines Laravel-Projekts, das über den Abschnitt scripts in der composer.json konfiguriert ist.

composer.json einer Laravel-App (Auszug)

"scripts": {
    "post-autoload-dump": [
        "Illuminate\\Foundation\\ComposerScripts::postAutoloadDump"
    ],
    "post-update-cmd": [
        "@php artisan vendor:publish --tag=laravel-assets --ansi --force"
    ],
    "post-root-package-install": [
        "@php -r \"file_exists('.env') || copy('.env.example', '.env');\""
    ],
    "post-create-project-cmd": [
        "@php artisan key:generate --ansi"
    ]
}

Manueller Neuaufbau mit `php artisan package:discover`

Wenn der Cache veraltet ist oder Sie vendor/ verändert haben, ohne Composer zu benutzen, können Sie den Cache mit package:discover manuell neu aufbauen.

php artisan package:discover

Die tatsächliche Implementierung dieses Kommandos ist ein sehr dünner Wrapper.

#[AsCommand(name: 'package:discover')]
class PackageDiscoverCommand extends Command
{
    public function handle(PackageManifest $manifest)
    {
        $this->components->info('Discovering packages');

        $manifest->build();

        (new Collection($manifest->manifest))
            ->keys()
            ->each(fn ($description) => $this->components->task($description))
            ->whenNotEmpty(fn () => $this->newLine());
    }
}

Der Befehl ruft lediglich $manifest->build() auf und gibt das Ergebnis aus — eine spezifische Kommandologik gibt es kaum. In Situationen, in denen Composer-Events nicht ausgelöst werden (z. B. wenn Sie in der CI-Pipeline composer install --no-scripts verwenden), müssen Sie diesen Befehl explizit aufrufen.

Wenn Sie Orchestra Testbench zum Testen Ihres Pakets verwenden, stellt Testbench einen eigenen Befehl vendor/bin/testbench package:discover bereit. Details finden Sie unter Paket-Tests mit Testbench. Er unterscheidet sich vom Artisan-Befehl package:discover und baut das Manifest speziell für die Skelett-Anwendung von Testbench auf.

Hinweise für das Deployment

Im Produktions-Deployment ist es üblich, composer install --no-dev --optimize-autoloader auszuführen. Fügen Sie jedoch --no-scripts hinzu, wird der Paket-Cache nicht aktualisiert. Es ist daher sicherer, Ihrem Deployment-Skript einen expliziten Neuaufbau hinzuzufügen.

composer install --no-dev --optimize-autoloader --no-scripts
php artisan package:discover --ansi
php artisan config:cache
php artisan route:cache

Die Reihenfolge ist wichtig: Führen Sie package:discover vor config:cache aus. Wird der Konfigurations-Cache zuerst erstellt, werden nachträglich hinzugefügte Paketkonfigurationen (etwa die per mergeConfigFrom registrierten) möglicherweise nicht berücksichtigt.

Zusammenfassung

Die automatische Erkennung basiert nicht auf dem statischen Inhalt der composer.json, sondern auf vendor/composer/installed.json, das Composer erzeugt.
Das Ergebnis wird in bootstrap/cache/packages.php als reines PHP-Array zwischengespeichert und lässt sich mit require allein schnell laden.
Der Cache wird bei den Events composer install/update/dump-autoload automatisch gelöscht und beim nächsten Start neu aufgebaut.
In Umgebungen, in denen Composer mit --no-scripts läuft, müssen Sie php artisan package:discover explizit aufrufen.
Mit * in dont-discover lässt sich die automatische Erkennung insgesamt deaktivieren.

KI-Entwicklung

Design Patterns

Paketentwicklung

Anwendungsstruktur

Neue Funktionen in Laravel 13

Eloquent im Detail

Validierungserweiterungen

Erweiterung der Authentifizierung

Sicherheit

Tests

テスト

Interne Struktur der automatischen Paket-Erkennung

Über diese Seite

Gesamtüberblick zur automatischen Erkennung

Die Klasse `PackageManifest`

Bau des Manifests

Zwei Schreibweisen für `dont-discover`

`*` in `dont-discover` angeben

Die Cache-Datei

Wann der Cache neu aufgebaut wird

Manueller Neuaufbau mit `php artisan package:discover`

Hinweise für das Deployment

Zusammenfassung

Verwandte Seiten

​Über diese Seite

​Gesamtüberblick zur automatischen Erkennung

​Die Klasse PackageManifest

​Bau des Manifests

​Zwei Schreibweisen für dont-discover

​* in dont-discover angeben

​Die Cache-Datei

​Wann der Cache neu aufgebaut wird

​Manueller Neuaufbau mit php artisan package:discover

​Hinweise für das Deployment

​Zusammenfassung

​Verwandte Seiten

Über diese Seite

Gesamtüberblick zur automatischen Erkennung

Die Klasse `PackageManifest`

Bau des Manifests

Zwei Schreibweisen für `dont-discover`

`*` in `dont-discover` angeben

Die Cache-Datei

Wann der Cache neu aufgebaut wird

Manueller Neuaufbau mit `php artisan package:discover`

Hinweise für das Deployment

Zusammenfassung

Verwandte Seiten