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.

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.

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

Migrations publiceren

Met publishesMigrations() kun je migrationbestanden publiceren. Laravel werkt de timestamps bij publicatie automatisch bij.

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

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.

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

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

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

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

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

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

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

​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

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