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.

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.

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');
});

Veröffentlichen von Migrationen

Mit publishesMigrations() lassen sich Migrationsdateien veröffentlichen. Laravel aktualisiert den Zeitstempel beim Veröffentlichen automatisch.

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

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.

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

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');
}

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',
        );
    }
}

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']);
}

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

Tests

テスト

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

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

​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

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