Laravel-packages ontwikkelen

Wat is een package?

Een package in Laravel is een Composer-package dat functionaliteit toevoegt aan je applicatie. Er zijn grofweg twee soorten packages:

Standalone packages — generieke PHP-libraries die niet van Laravel afhankelijk zijn (bijvoorbeeld Carbon, Pest)
Laravel-packages — packages met functionaliteit die met Laravel is geïntegreerd, zoals routes, controllers, views en configuratie

Deze gids behandelt de tweede soort: het ontwikkelen van Laravel-specifieke packages. Voor packageontwikkeling heb je diepgaande kennis nodig van de interne structuur van Laravel, zoals service providers, facades en het publiceren van configuratiebestanden.

Voor het schrijven van tests voor je package gebruik je Orchestra Testbench. Je kunt packagetests schrijven zoals je dat in een gewone Laravel-applicatie doet.

Automatische detectie van packages

Wanneer een package wordt geïnstalleerd, leest Laravel de sectie extra.laravel uit composer.json en registreert de service providers en facades automatisch.

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

Met deze configuratie wordt je package automatisch geladen, zonder dat gebruikers bootstrap/providers.php handmatig hoeven aan te passen.

Hoe deze automatische detectie is geïmplementeerd en wanneer de cache opnieuw wordt opgebouwd, lees je in detail in De interne structuur van package discovery.

Automatische detectie uitschakelen

Als een gebruiker de automatische detectie van een specifiek package wil uitschakelen, stelt die dat in de composer.json van de applicatie in.

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

De rol van de service provider

De service provider is het toegangspunt van je package. Hier centraliseer je alle logica om resources zoals views, configuratie, migrations en routes bij Laravel te registreren. Een service provider erft van Illuminate\Support\ServiceProvider en heeft twee methodes: register en boot.

<?php

namespace Acme\Courier;

use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    /**
     * Registreer de services van het package
     */
    public function register(): void
    {
        // Bindings aan de service container doe je hier
        $this->mergeConfigFrom(
            __DIR__.'/../config/courier.php', 'courier'
        );

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

    /**
     * Bootstrap de services van het package
     */
    public function boot(): void
    {
        // Resources registreer je 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');
    }
}

Registreer geen event listeners, routes of views in de register-methode. Je zou per ongeluk services kunnen gebruiken van een andere service provider die nog niet is geladen. Doe alles behalve bindings altijd in de boot-methode.

Zie Hooks na het resolven van packageservices om een service uit te breiden zonder deze aan te maken voordat hij wordt gebruikt, en om configuratie ook toe te passen als de service al is geresolved. Daar wordt uitgelegd wanneer callAfterResolving() wordt uitgevoerd en hoe je ontwerpt voor herhaalde toepassing. Zie Levensduur van packageservices ontwerpen voor registratiemethoden die ook in Octane en queue workers geen state meenemen. Daar worden de interne implementatie van scoped() en de aandachtspunten bij afhankelijkheden die een singleton vasthoudt uitgelegd.

Configuratiebestanden publiceren

publishes() — bestanden publiceren

Als je in de boot-methode publishes() aanroept, kunnen gebruikers met het vendor:publish-commando het configuratiebestand naar hun eigen applicatie kopiëren.

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

Na publicatie haal je de configuratiewaarden op zoals bij elke andere config-toegang.

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

mergeConfigFrom() — samenvoegen met standaardwaarden

Als je mergeConfigFrom() gebruikt in de register-methode, worden de standaardwaarden van het package ook gebruikt wanneer de gebruiker het configuratiebestand niet heeft gepubliceerd.

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

mergeConfigFrom() voegt geneste arrays niet tot op diepere niveaus samen. Bij configuraties met multidimensionale arrays kan het gebeuren dat, wanneer de gebruiker maar een deel definieert, de overige opties niet worden samengevoegd.

Het verschil met de recursieve vervangmethode van Laravel 13, de omgang met lijsten met numerieke sleutels en de updatestappen wanneer je de configuratiecache gebruikt, worden uitgelegd in Packageconfiguratie samenvoegen en cachen.

Publicatiegroepen scheiden met tags

Als je een tag opgeeft als tweede argument van publishes(), kunnen gebruikers alleen de resources publiceren die ze nodig hebben.

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

# Alleen het configuratiebestand publiceren
php artisan vendor:publish --tag=courier-config

# Alle bestanden publiceren die de provider aanbiedt
php artisan vendor:publish --provider="Acme\Courier\CourierServiceProvider"

Routes registreren

Laad routebestanden met loadRoutesFrom(). Als de routecache van de applicatie actief is, wordt dit automatisch overgeslagen.

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

In het routebestand verwijs je naar de controllers van het package.

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

Hoe je middleware expliciet opgeeft, botsingen van URI’s en routenamen voorkomt en configuratiewijzigingen in de cache verwerkt, wordt uitgelegd in Routes van packages registreren en cachen.

Migrations publiceren

Met publishesMigrations() registreer je migrationbestanden om te publiceren. In de standaardconfiguratie van Laravel 13 is database.migrations.update_date_on_publish ingeschakeld, waardoor de timestamp in de bestandsnaam bij publicatie wordt bijgewerkt. Als de instelling is uitgeschakeld of ontbreekt, gebeurt dit niet.

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

Wanneer je publiceert of direct laadt, wanneer timestamps veranderen, de risico’s van opnieuw publiceren en schemawijzigingen voor bestaande gebruikers worden uitgelegd in Migrations van packages publiceren en bijwerken.

Views publiceren

loadViewsFrom() — views registreren

Registreer de viewsmap met loadViewsFrom(). Met de namespace uit het tweede argument verwijs je naar views in het formaat package::view.

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

Na registratie verwijs je naar views via de package-namespace.

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

Laravel zoekt views op twee plekken. Eerst controleert het de map resources/views/vendor/courier van de applicatie; als die er niet is, gebruikt het de viewsmap van het package. Zo kunnen gebruikers de views aanpassen. De zoekvolgorde in de implementatie en de terugval per bestand, hoe je wijzigingen bij gepubliceerde templates krijgt en het verschil met de Blade-cache worden uitgelegd in Views van packages overschrijven en bijwerken.

Views publiceren

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

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

Blade-componenten registreren

Als je componenten in je package opneemt, registreer je die in de boot-methode.

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

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

Je kunt ook in één keer registreren via een componentnamespace.

use Illuminate\Support\Facades\Blade;

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

{{-- Bij individuele registratie --}}
<x-courier-alert />

{{-- Bij namespace-registratie --}}
<x-courier::alert />

Publieke assets distribueren

Om de JavaScript, CSS en afbeeldingen van je package te distribueren, registreer je met publishes() een kopie naar bijvoorbeeld public_path('vendor/courier'). Als je het package bijwerkt, veranderen al gepubliceerde bestanden niet automatisch. Het filteren op tag en provider, het verschil tussen --force en --existing, de afhandeling van verwijderde bestanden en updates via laravel-assets worden uitgelegd in Publieke assets van packages publiceren en bijwerken.

Vertaalbestanden publiceren

Registreer vertaalbestanden met loadTranslationsFrom(). Naar vertalingen verwijs je in het formaat package::file.key.

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

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

// Vertalingen gebruiken
echo trans('courier::messages.welcome');

Voor JSON-vertaalbestanden gebruik je loadJsonTranslationsFrom().

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

Het gedeeltelijk overschrijven van PHP-vertalingen, de laadvolgorde en overschrijvingslocatie van JSON-vertalingen, en de compatibiliteit van vertaalsleutels en het bijwerken van gepubliceerde bestanden worden uitgelegd in Packagevertalingen overschrijven en bijwerken.

Commando’s registreren

Artisan-commando’s van je package registreer je met de commands()-methode. Het is gebruikelijk om ze alleen in de console-omgeving te registreren.

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

Integratie met het optimize-commando

Als je package een eigen cache heeft, kun je met de optimizes()-methode integreren met php artisan optimize en php artisan optimize:clear.

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

Het registreren van commandoklassen en het registreren van optimalisatietaken zijn afzonderlijke handelingen. Botsende registratiesleutels, uitsluiten met --except, de uitvoeringsvolgorde ten opzichte van de standaardtaken en exitcodes bij fouten worden uitgelegd in Packagecaches integreren in optimize.

Informatie toevoegen aan het `about`-commando

Gebruik AboutCommand::add() om package-informatie toe te voegen aan de uitvoer van php artisan about.

use Illuminate\Foundation\Console\AboutCommand;

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

Wanneer de gegevens worden geëvalueerd, --only en JSON-uitvoer, een ontwerp zonder geheimen in de uitvoer en de registratiestatus in tests worden uitgelegd in Diagnostische package-informatie toevoegen aan about.

Een facade maken

Met een facade kun je een binding uit de service container aanroepen alsof het statische methodes zijn.

Maak een serviceklasse

<?php

namespace Acme\Courier;

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

    public function send(string $to, string $message): bool
    {
        // Logica voor het versturen van berichten
        return true;
    }

    public function track(string $id): array
    {
        // Logica voor het ophalen van trackinginformatie
        return ['status' => 'delivered'];
    }
}

Maak een facade-klasse

Erf van Illuminate\Support\Facades\Facade en geef in getFacadeAccessor() de bindingssleutel van de service container terug.

<?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;
    }
}

Bind in de service provider

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

Registreer in composer.json

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

Door PHPDoc-@method-annotaties aan de facademethodes toe te voegen, werkt de autocomplete van je IDE.

// De service aanroepen via de facade
use Acme\Courier\Facades\Courier;

Courier::send('[email protected]', 'Je pakket is aangekomen');
$status = Courier::track('ABC-123');

DeferrableProvider — lazy loading implementeren

Een provider die alleen bindings aan de service container toevoegt, kan lazy loading realiseren door de interface DeferrableProvider te implementeren. Omdat de provider pas wordt geladen wanneer de service echt nodig is, verbetert de performance van je applicatie.

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

    /**
     * Geef de lijst van services terug die deze provider aanbiedt
     *
     * @return array<int, string>
     */
    public function provides(): array
    {
        return [CourierManager::class];
    }
}

Laravel compileert en bewaart de lijst van services die deferred providers aanbieden. De provider wordt alleen geladen wanneer een van de services uit provides() wordt opgelost.

Gebruik DeferrableProvider niet voor providers die resources moeten registreren (views, routes, event listeners, enz.). Bij lazy loading blijven die resources anders ongeregistreerd.

Packages testen

Om je package op zichzelf te testen gebruik je Orchestra Testbench. Je kunt packagetests schrijven alsof je in een gewone Laravel-applicatie zit.

composer require --dev orchestra/testbench

Overschrijf in je testcase getPackageProviders() om de service provider van je package te registreren.

<?php

namespace Acme\Courier\Tests;

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

class TestCase extends BaseTestCase
{
    /**
     * Registreer de service providers van het package
     */
    protected function getPackageProviders($app): array
    {
        return [
            CourierServiceProvider::class,
        ];
    }

    /**
     * Registreer de facade-aliassen van het package
     */
    protected function getPackageAliases($app): array
    {
        return [
            'Courier' => \Acme\Courier\Facades\Courier::class,
        ];
    }

    /**
     * Omgevingsconfiguratie voor tests
     */
    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]', 'Testbericht');

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

Publiceren op Composer

Best practices voor het publiceren van je package op Packagist. Basisconfiguratie van 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
}

Door afhankelijk te zijn van illuminate/support in plaats van heel illuminate/framework, neem je alleen de Laravel-componenten op die je nodig hebt. Houd de dependency tree van je package klein.

Voorbeeld van een directorystructuur

acme/courier/
├── config/
│   └── courier.php
├── database/
│   └── migrations/
│       └── 2024_01_01_000000_create_courier_logs_table.php
├── lang/
│   └── ja/
│       └── 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

Gerelateerde pagina’s

Service providers

Bekijk de details van de register- en boot-methodes van service providers en van deferred providers.

Versiecompatibiliteit beheren

Uitleg over strategieën voor major-upgrades van Laravel en PHP en de testmatrixconfiguratie van GitHub Actions.

AI-ontwikkeling

Design patterns

Package-ontwikkeling

Applicatiestructuur

Nieuwe functies in Laravel 13

Eloquent in detail

Validatie-uitbreidingen

Authenticatie uitbreiden

Beveiliging

Queues

Testen

Realtime

Wat is een package?

Automatische detectie van packages

Automatische detectie uitschakelen

De rol van de service provider

Configuratiebestanden publiceren

publishes() — bestanden publiceren

mergeConfigFrom() — samenvoegen met standaardwaarden

Publicatiegroepen scheiden met tags

Routes registreren

Migrations publiceren

Views publiceren

loadViewsFrom() — views registreren

Views publiceren

Blade-componenten registreren

Publieke assets distribueren

Vertaalbestanden publiceren

Commando’s registreren

Integratie met het optimize-commando

Informatie toevoegen aan het `about`-commando

Een facade maken

DeferrableProvider — lazy loading implementeren

Packages testen

Publiceren op Composer

Gerelateerde pagina’s

Service providers

Versiecompatibiliteit beheren

​Wat is een package?

​Automatische detectie van packages

​Automatische detectie uitschakelen

​De rol van de service provider

​Configuratiebestanden publiceren

​publishes() — bestanden publiceren

​mergeConfigFrom() — samenvoegen met standaardwaarden

​Publicatiegroepen scheiden met tags

​Routes registreren

​Migrations publiceren

​Views publiceren

​loadViewsFrom() — views registreren

​Views publiceren

​Blade-componenten registreren

​Publieke assets distribueren

​Vertaalbestanden publiceren

​Commando’s registreren

​Integratie met het optimize-commando

​Informatie toevoegen aan het about-commando

​Een facade maken

​DeferrableProvider — lazy loading implementeren

​Packages testen

​Publiceren op Composer

​Gerelateerde pagina’s

Service providers

Versiecompatibiliteit beheren

Wat is een package?

Automatische detectie van packages

Automatische detectie uitschakelen

De rol van de service provider

Configuratiebestanden publiceren

publishes() — bestanden publiceren

mergeConfigFrom() — samenvoegen met standaardwaarden

Publicatiegroepen scheiden met tags

Routes registreren

Migrations publiceren

Views publiceren

loadViewsFrom() — views registreren

Views publiceren

Blade-componenten registreren

Publieke assets distribueren

Vertaalbestanden publiceren

Commando’s registreren

Integratie met het optimize-commando

Informatie toevoegen aan het `about`-commando

Een facade maken

DeferrableProvider — lazy loading implementeren

Packages testen

Publiceren op Composer

Gerelateerde pagina’s