Laravel-Paketentwicklung

Was ist ein Paket?

Ein Paket in Laravel ist ein Composer-Paket, das der Anwendung Funktionalität hinzufügt. Grob unterscheidet man zwei Arten:

Eigenständige Pakete — Allgemeine PHP-Bibliotheken, die nicht von Laravel abhängen (z. B. Carbon, Pest).
Laravel-Pakete — Pakete mit Funktionen, die eng mit Laravel integriert sind, etwa Routen, Controller, Views oder Konfiguration.

Diese Anleitung behandelt die zweite Kategorie: die Entwicklung Laravel-spezifischer Pakete. Für die Paketentwicklung müssen Sie die internen Strukturen von Laravel — Service Provider, Facades, das Veröffentlichen von Konfigurationsdateien und mehr — gut kennen.

Wenn Sie Tests für Ihr Paket schreiben, verwenden Sie Orchestra Testbench. Damit können Sie Tests für Ihr Paket schreiben, als befänden Sie sich in einer gewöhnlichen Laravel-Anwendung.

Automatische Paket-Erkennung

Sobald ein Paket installiert wird, liest Laravel den Abschnitt extra.laravel aus der composer.json und registriert Service Provider und Facades automatisch.

"extra": {
    "laravel": {
        "providers": [
            "Acme\\Courier\\CourierServiceProvider"
        ],
        "aliases": {
            "Courier": "Acme\\Courier\\Facades\\Courier"
        }
    }
}

Mit dieser Konfiguration wird das Paket automatisch geladen, ohne dass die Nutzer bootstrap/providers.php manuell bearbeiten müssen.

Wie diese automatische Erkennung intern implementiert ist und wann der Cache neu erstellt wird, erläutern wir ausführlich unter Interne Struktur der automatischen Paket-Erkennung.

Automatische Erkennung deaktivieren

Wenn Nutzer die automatische Erkennung für ein bestimmtes Paket deaktivieren möchten, konfigurieren sie dies in der composer.json der Anwendung.

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

Aufgaben des Service Providers

Der Service Provider ist der Einstiegspunkt eines Pakets. Hier bündeln Sie die Registrierung von Ressourcen wie Views, Konfiguration, Migrationen und Routen bei Laravel. Ein Service Provider erbt von Illuminate\Support\ServiceProvider und besitzt die zwei Methoden register und boot.

<?php

namespace Acme\Courier;

use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    /**
     * Registriert die Services des Pakets.
     */
    public function register(): void
    {
        // Bindings am Service Container werden hier vorgenommen
        $this->mergeConfigFrom(
            __DIR__.'/../config/courier.php', 'courier'
        );

        $this->app->singleton(CourierManager::class, function ($app) {
            return new CourierManager($app['config']['courier']);
        });
    }

    /**
     * Bootstrappt die Services des Pakets.
     */
    public function boot(): void
    {
        // Die Registrierung von Ressourcen erfolgt hier
        $this->loadRoutesFrom(__DIR__.'/../routes/web.php');
        $this->loadViewsFrom(__DIR__.'/../resources/views', 'courier');
        $this->loadTranslationsFrom(__DIR__.'/../lang', 'courier');

        $this->publishesMigrations([
            __DIR__.'/../database/migrations' => database_path('migrations'),
        ]);

        $this->publishes([
            __DIR__.'/../config/courier.php' => config_path('courier.php'),
        ], 'courier-config');

        $this->publishes([
            __DIR__.'/../resources/views' => resource_path('views/vendor/courier'),
        ], 'courier-views');
    }
}

Registrieren Sie in der register-Methode keine Event-Listener, Routen oder Views. Sie könnten sonst versehentlich Services eines noch nicht geladenen Service Providers verwenden. Alles außer Bindings gehört in die boot-Methode.

Wie Sie einen Service erweitern, ohne ihn vor seiner Verwendung zu erzeugen, und Einstellungen auch auf bereits aufgelöste Services anwenden, erfahren Sie unter Hooks nach der Service-Auflösung in Paketen. Dort werden der Ausführungszeitpunkt von callAfterResolving() und ein Design erläutert, das mehrfache Anwendung verträgt. Wie Sie Services so registrieren, dass auch in Octane und Queue-Workern kein Zustand mitgeschleppt wird, erfahren Sie unter Lebenszyklus-Design für Paket-Services. Dort werden die interne Implementierung von scoped() und die Fallstricke bei von Singletons gehaltenen Abhängigkeiten erläutert.

Veröffentlichen von Konfigurationsdateien

publishes() — Dateien veröffentlichen

Wenn Sie publishes() in der boot-Methode aufrufen, können Nutzer die Konfigurationsdatei mit dem Befehl vendor:publish in ihre eigene Anwendung kopieren.

public function boot(): void
{
    $this->publishes([
        __DIR__.'/../config/courier.php' => config_path('courier.php'),
    ]);
}

Nach der Veröffentlichung greifen Sie auf die Konfigurationswerte wie üblich zu.

$value = config('courier.option');

mergeConfigFrom() — Standardwerte zusammenführen

Wenn Sie mergeConfigFrom() in der register-Methode verwenden, werden die Standardwerte des Pakets auch dann genutzt, wenn Nutzer die Konfigurationsdatei nicht veröffentlicht haben.

public function register(): void
{
    $this->mergeConfigFrom(
        __DIR__.'/../config/courier.php', 'courier'
    );
}

mergeConfigFrom() führt verschachtelte Arrays nicht rekursiv zusammen. Bei Konfigurationen mit mehrdimensionalen Arrays kann es vorkommen, dass restliche Optionen nicht ergänzt werden, wenn Nutzer nur einen Teil definieren.

Den Unterschied zur rekursiven Ersetzungsmethode von Laravel 13, den Umgang mit Listen mit numerischen Schlüsseln und die Update-Schritte bei Verwendung des Konfigurations-Caches erläutert Paketkonfiguration zusammenführen und cachen.

Veröffentlichungsgruppen mit Tags trennen

Wenn Sie im zweiten Argument von publishes() einen Tag angeben, können Nutzer gezielt nur die benötigten Ressourcen veröffentlichen.

public function boot(): void
{
    $this->publishes([
        __DIR__.'/../config/courier.php' => config_path('courier.php'),
    ], 'courier-config');

    $this->publishesMigrations([
        __DIR__.'/../database/migrations/' => database_path('migrations'),
    ], 'courier-migrations');
}

# Nur die Konfigurationsdatei veröffentlichen
php artisan vendor:publish --tag=courier-config

# Alle vom Provider bereitgestellten Dateien veröffentlichen
php artisan vendor:publish --provider="Acme\Courier\CourierServiceProvider"

Registrieren von Routen

Sie laden Route-Dateien mit loadRoutesFrom(). Wenn der Route-Cache der Anwendung aktiv ist, wird der Aufruf automatisch übersprungen.

public function boot(): void
{
    $this->loadRoutesFrom(__DIR__.'/../routes/web.php');
}

In der Route-Datei geben Sie die Controller des Pakets an.

// routes/web.php
use Acme\Courier\Http\Controllers\TrackingController;
use Illuminate\Support\Facades\Route;

Route::prefix('courier')->group(function () {
    Route::get('/track/{id}', [TrackingController::class, 'show'])
        ->name('courier.track');
});

Die explizite Angabe von Middleware, das Vermeiden von Kollisionen bei URIs und Routennamen sowie die Schritte, mit denen Konfigurationsänderungen im Cache ankommen, erläutert Paket-Routen registrieren und cachen.

Veröffentlichen von Migrationen

Mit publishesMigrations() registrieren Sie Migrationsdateien zur Veröffentlichung. In der Standardkonfiguration von Laravel 13 ist database.migrations.update_date_on_publish aktiviert, daher wird der Zeitstempel im Dateinamen beim Veröffentlichen aktualisiert. Ist die Einstellung deaktiviert oder nicht vorhanden, findet diese Aktualisierung nicht statt.

public function boot(): void
{
    $this->publishesMigrations([
        __DIR__.'/../database/migrations' => database_path('migrations'),
    ]);
}

Wann Sie veröffentlichen oder direkt laden sollten, unter welchen Bedingungen sich Zeitstempel ändern, welche Risiken erneutes Veröffentlichen birgt und wie Sie Schemaänderungen an bestehende Nutzer ausliefern, erfahren Sie unter Paket-Migrationen veröffentlichen und aktualisieren.

Veröffentlichen von Views

loadViewsFrom() — Views registrieren

Mit loadViewsFrom() registrieren Sie ein View-Verzeichnis. Über den Namespace im zweiten Argument referenzieren Sie die Views im Format package::view.

public function boot(): void
{
    $this->loadViewsFrom(__DIR__.'/../resources/views', 'courier');
}

Nach der Registrierung sprechen Sie Views über den Paket-Namespace an.

Route::get('/dashboard', function () {
    return view('courier::dashboard');
});

Laravel sucht die Views an zwei Orten: Zuerst wird das Verzeichnis resources/views/vendor/courier der Anwendung geprüft, andernfalls das View-Verzeichnis des Pakets. So können Nutzer die Views anpassen. Die Suchreihenfolge in der Implementierung, den Fallback pro Datei, die Auslieferung von Änderungen an veröffentlichte Templates und den Unterschied zum Blade-Cache erläutert Paket-Views überschreiben und aktualisieren.

Views veröffentlichen

public function boot(): void
{
    $this->loadViewsFrom(__DIR__.'/../resources/views', 'courier');

    $this->publishes([
        __DIR__.'/../resources/views' => resource_path('views/vendor/courier'),
    ], 'courier-views');
}

Blade-Komponenten registrieren

Wenn Sie Komponenten in Ihr Paket aufnehmen möchten, registrieren Sie sie in der boot-Methode.

use Illuminate\Support\Facades\Blade;
use Acme\Courier\View\Components\AlertComponent;

public function boot(): void
{
    Blade::component('courier-alert', AlertComponent::class);
}

Sie können Komponenten auch en bloc über einen Komponenten-Namespace registrieren.

use Illuminate\Support\Facades\Blade;

public function boot(): void
{
    Blade::componentNamespace('Acme\\Courier\\View\\Components', 'courier');
}

{{-- Bei Einzelregistrierung --}}
<x-courier-alert />

{{-- Bei Namespace-Registrierung --}}
<x-courier::alert />

Öffentliche Assets ausliefern

Um JavaScript, CSS und Bilder Ihres Pakets auszuliefern, registrieren Sie mit publishes() eine Kopie etwa nach public_path('vendor/courier'). Wenn Sie das Paket aktualisieren, ändern sich bereits veröffentlichte Dateien nicht automatisch. Die Auswahl über Tags und Provider, den Unterschied zwischen --force und --existing, den Umgang mit gelöschten Dateien und Updates über laravel-assets erläutert Öffentliche Paket-Assets veröffentlichen und aktualisieren.

Veröffentlichen von Übersetzungsdateien

Mit loadTranslationsFrom() registrieren Sie Übersetzungsdateien. Übersetzungen werden im Format package::file.key angesprochen.

public function boot(): void
{
    $this->loadTranslationsFrom(__DIR__.'/../lang', 'courier');

    $this->publishes([
        __DIR__.'/../lang' => $this->app->langPath('vendor/courier'),
    ]);
}

// Verwendung der Übersetzung
echo trans('courier::messages.welcome');

Wenn Sie JSON-Übersetzungsdateien nutzen, verwenden Sie loadJsonTranslationsFrom().

public function boot(): void
{
    $this->loadJsonTranslationsFrom(__DIR__.'/../lang');
}

Das teilweise Überschreiben von PHP-Übersetzungen, Ladereihenfolge und Überschreibungsziel von JSON-Übersetzungen sowie die Kompatibilität von Übersetzungsschlüsseln und das Aktualisieren veröffentlichter Dateien werden unter Paketübersetzungen überschreiben und aktualisieren erläutert.

Registrieren von Kommandos

Artisan-Kommandos eines Pakets registrieren Sie mit der Methode commands(). Üblich ist, sie nur in der Konsolenumgebung zu registrieren.

use Acme\Courier\Console\Commands\InstallCommand;
use Acme\Courier\Console\Commands\SyncCommand;

public function boot(): void
{
    if ($this->app->runningInConsole()) {
        $this->commands([
            InstallCommand::class,
            SyncCommand::class,
        ]);
    }
}

Integration in den optimize-Befehl

Wenn Ihr Paket eigene Caches besitzt, können Sie diese mit der Methode optimizes() in php artisan optimize und php artisan optimize:clear einbinden.

public function boot(): void
{
    if ($this->app->runningInConsole()) {
        $this->optimizes(
            optimize: 'courier:cache',
            clear: 'courier:clear-cache',
        );
    }
}

Das Registrieren von Befehlsklassen und das Registrieren von Optimierungs-Tasks sind getrennte Vorgänge. Kollisionen von Registrierungsschlüsseln, Ausschlüsse mit --except, die Ausführungsreihenfolge gegenüber den Standard-Tasks und Exit-Codes bei Fehlern werden unter Paket-Caches in optimize integrieren erläutert.

Informationen zum `about`-Befehl hinzufügen

Um Paketinformationen zur Ausgabe von php artisan about hinzuzufügen, verwenden Sie AboutCommand::add().

use Illuminate\Foundation\Console\AboutCommand;

public function boot(): void
{
    AboutCommand::add('Courier Package', fn () => ['Version' => '1.0.0']);
}

Wann die Daten ausgewertet werden, wie --only und die JSON-Ausgabe funktionieren, wie Sie keine Geheimnisse ausgeben und wie Sie den Registrierungszustand in Tests behandeln, erfahren Sie unter Paket-Diagnoseinformationen zu about hinzufügen.

Facades erstellen

Mit einer Facade können Sie Bindings des Service Containers so aufrufen, als handele es sich um statische Methoden.

Service-Klasse erstellen

<?php

namespace Acme\Courier;

class CourierManager
{
    public function __construct(
        protected array $config,
    ) {}

    public function send(string $to, string $message): bool
    {
        // Nachrichtenversand
        return true;
    }

    public function track(string $id): array
    {
        // Ermitteln der Tracking-Informationen
        return ['status' => 'delivered'];
    }
}

Facade-Klasse erstellen

Erben Sie von Illuminate\Support\Facades\Facade und geben Sie in getFacadeAccessor() den Binding-Schlüssel des Service Containers zurück.

<?php

namespace Acme\Courier\Facades;

use Illuminate\Support\Facades\Facade;

/**
 * @method static bool send(string $to, string $message)
 * @method static array track(string $id)
 *
 * @see \Acme\Courier\CourierManager
 */
class Courier extends Facade
{
    protected static function getFacadeAccessor(): string
    {
        return \Acme\Courier\CourierManager::class;
    }
}

Binding im Service Provider

public function register(): void
{
    $this->app->singleton(\Acme\Courier\CourierManager::class, function ($app) {
        return new \Acme\Courier\CourierManager($app['config']['courier']);
    });
}

Registrierung in composer.json

"extra": {
    "laravel": {
        "providers": [
            "Acme\\Courier\\CourierServiceProvider"
        ],
        "aliases": {
            "Courier": "Acme\\Courier\\Facades\\Courier"
        }
    }
}

Mit @method-Annotationen im PHPDoc der Facade-Methoden aktivieren Sie die Autovervollständigung Ihrer IDE.

// Aufruf des Service über die Facade
use Acme\Courier\Facades\Courier;

Courier::send('[email protected]', 'Ihr Paket ist eingetroffen');
$status = Courier::track('ABC-123');

DeferrableProvider — Lazy Loading umsetzen

Provider, die ausschließlich Bindings am Service Container vornehmen, können Lazy Loading realisieren, indem sie das Interface DeferrableProvider implementieren. Der Provider wird dann erst geladen, wenn der Service tatsächlich benötigt wird, was die Anwendungsleistung verbessert.

<?php

namespace Acme\Courier;

use Illuminate\Contracts\Support\DeferrableProvider;
use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider implements DeferrableProvider
{
    public function register(): void
    {
        $this->app->singleton(CourierManager::class, function ($app) {
            return new CourierManager($app['config']['courier']);
        });
    }

    /**
     * Liefert die Liste der von diesem Provider bereitgestellten Services.
     *
     * @return array<int, string>
     */
    public function provides(): array
    {
        return [CourierManager::class];
    }
}

Laravel kompiliert die Liste der von deferred Providern bereitgestellten Services und speichert sie ab. Der Provider wird erst geladen, wenn ein in provides() aufgeführter Service aufgelöst wird.

Verwenden Sie DeferrableProvider nicht für Provider, die Ressourcen registrieren (Views, Routen, Event-Listener usw.). Beim Lazy Loading würden diese Ressourcen nicht registriert werden.

Testen von Paketen

Um ein Paket isoliert zu testen, verwenden Sie Orchestra Testbench. Damit lassen sich Tests wie in einer regulären Laravel-Anwendung schreiben.

composer require --dev orchestra/testbench

Überschreiben Sie in Ihren Testfällen getPackageProviders(), um den Service Provider des Pakets zu registrieren.

<?php

namespace Acme\Courier\Tests;

use Acme\Courier\CourierServiceProvider;
use Orchestra\Testbench\TestCase as BaseTestCase;

class TestCase extends BaseTestCase
{
    /**
     * Registriert die Service Provider des Pakets.
     */
    protected function getPackageProviders($app): array
    {
        return [
            CourierServiceProvider::class,
        ];
    }

    /**
     * Registriert die Facade-Aliase des Pakets.
     */
    protected function getPackageAliases($app): array
    {
        return [
            'Courier' => \Acme\Courier\Facades\Courier::class,
        ];
    }

    /**
     * Konfiguration der Testumgebung.
     */
    protected function defineEnvironment($app): void
    {
        $app['config']->set('courier.api_key', 'test-key');
    }
}

<?php

namespace Acme\Courier\Tests\Feature;

use Acme\Courier\Facades\Courier;
use Acme\Courier\Tests\TestCase;

class CourierTest extends TestCase
{
    public function test_can_send_message(): void
    {
        $result = Courier::send('[email protected]', 'Testnachricht');

        $this->assertTrue($result);
    }
}

Veröffentlichung auf Composer

Best Practices für die Veröffentlichung Ihres Pakets auf Packagist: Grundkonfiguration der composer.json

{
    "name": "acme/courier",
    "description": "A Laravel courier package",
    "type": "library",
    "license": "MIT",
    "require": {
        "php": "^8.2",
        "illuminate/support": "^11.0||^12.0||^13.0"
    },
    "require-dev": {
        "orchestra/testbench": "^9.0||^10.0",
        "phpunit/phpunit": "^11.0"
    },
    "autoload": {
        "psr-4": {
            "Acme\\Courier\\": "src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "Acme\\Courier\\Tests\\": "tests/"
        }
    },
    "extra": {
        "laravel": {
            "providers": [
                "Acme\\Courier\\CourierServiceProvider"
            ],
            "aliases": {
                "Courier": "Acme\\Courier\\Facades\\Courier"
            }
        }
    },
    "minimum-stability": "stable",
    "prefer-stable": true
}

Durch die Abhängigkeit von illuminate/support binden Sie nur die tatsächlich benötigten Laravel-Komponenten ein und nicht das gesamte illuminate/framework. Halten Sie den Abhängigkeitsbaum Ihres Pakets klein.

Beispielhafte Verzeichnisstruktur

acme/courier/
├── config/
│   └── courier.php
├── database/
│   └── migrations/
│       └── 2024_01_01_000000_create_courier_logs_table.php
├── lang/
│   └── de/
│       └── messages.php
├── resources/
│   └── views/
│       └── dashboard.blade.php
├── routes/
│   └── web.php
├── src/
│   ├── Console/
│   │   └── Commands/
│   │       └── InstallCommand.php
│   ├── Facades/
│   │   └── Courier.php
│   ├── Http/
│   │   └── Controllers/
│   │       └── TrackingController.php
│   ├── CourierManager.php
│   └── CourierServiceProvider.php
├── tests/
│   ├── Feature/
│   └── TestCase.php
├── composer.json
└── README.md

Service Provider

Details zu den Methoden register und boot sowie zu deferred Providern.

Verwaltung der Versionskompatibilität

Strategien für den Umgang mit Major-Updates von Laravel und PHP sowie Konfiguration der Testmatrix in GitHub Actions.

KI-Entwicklung

Design Patterns

Paketentwicklung

Anwendungsstruktur

Neue Funktionen in Laravel 13

Eloquent im Detail

Validierungserweiterungen

Erweiterung der Authentifizierung

Sicherheit

Warteschlangen

Tests

Echtzeit

Was ist ein Paket?

Automatische Paket-Erkennung

Automatische Erkennung deaktivieren

Aufgaben des Service Providers

Veröffentlichen von Konfigurationsdateien

publishes() — Dateien veröffentlichen

mergeConfigFrom() — Standardwerte zusammenführen

Veröffentlichungsgruppen mit Tags trennen

Registrieren von Routen

Veröffentlichen von Migrationen

Veröffentlichen von Views

loadViewsFrom() — Views registrieren

Views veröffentlichen

Blade-Komponenten registrieren

Öffentliche Assets ausliefern

Veröffentlichen von Übersetzungsdateien

Registrieren von Kommandos

Integration in den optimize-Befehl

Informationen zum `about`-Befehl hinzufügen

Facades erstellen

DeferrableProvider — Lazy Loading umsetzen

Testen von Paketen

Veröffentlichung auf Composer

Verwandte Seiten

Service Provider

Verwaltung der Versionskompatibilität

​Was ist ein Paket?

​Automatische Paket-Erkennung

​Automatische Erkennung deaktivieren

​Aufgaben des Service Providers

​Veröffentlichen von Konfigurationsdateien

​publishes() — Dateien veröffentlichen

​mergeConfigFrom() — Standardwerte zusammenführen

​Veröffentlichungsgruppen mit Tags trennen

​Registrieren von Routen

​Veröffentlichen von Migrationen

​Veröffentlichen von Views

​loadViewsFrom() — Views registrieren

​Views veröffentlichen

​Blade-Komponenten registrieren

​Öffentliche Assets ausliefern

​Veröffentlichen von Übersetzungsdateien

​Registrieren von Kommandos

​Integration in den optimize-Befehl

​Informationen zum about-Befehl hinzufügen

​Facades erstellen

​DeferrableProvider — Lazy Loading umsetzen

​Testen von Paketen

​Veröffentlichung auf Composer

​Verwandte Seiten

Service Provider

Verwaltung der Versionskompatibilität

Was ist ein Paket?

Automatische Paket-Erkennung

Automatische Erkennung deaktivieren

Aufgaben des Service Providers

Veröffentlichen von Konfigurationsdateien

publishes() — Dateien veröffentlichen

mergeConfigFrom() — Standardwerte zusammenführen

Veröffentlichungsgruppen mit Tags trennen

Registrieren von Routen

Veröffentlichen von Migrationen

Veröffentlichen von Views

loadViewsFrom() — Views registrieren

Views veröffentlichen

Blade-Komponenten registrieren

Öffentliche Assets ausliefern

Veröffentlichen von Übersetzungsdateien

Registrieren von Kommandos

Integration in den optimize-Befehl

Informationen zum `about`-Befehl hinzufügen

Facades erstellen

DeferrableProvider — Lazy Loading umsetzen

Testen von Paketen

Veröffentlichung auf Composer

Verwandte Seiten