Lebenszyklus-Design für Paket-Services

Damit ein Paket nicht nur in gewöhnlichen HTTP-Requests, sondern auch mit Octane und Queue-Workern funktioniert, müssen Sie festlegen, wie lange ein Service was halten darf. Wenn Sie requestspezifische Daten in einem Singleton speichern, kann eine andere Verarbeitung auf veraltete Daten zugreifen. Diese Seite untersucht die Implementierung des Containers, des Queue-Workers und von Octane in Laravel Framework v13.36.0 und verknüpft die grundlegenden Registrierungsmethoden des Service Containers mit der langfristigen Wartung von Paketen. Allein die Wahl von scoped() setzt weder Referenzen zwischen Objekten noch statischen Zustand vollständig zurück.

Die Registrierungsmethode nach der Haltedauer des Service wählen

Registrierung	Abruf über gewöhnliches `make()`	Geeignetes Design
`bind()`	Wird bei jeder Auflösung neu erzeugt	Services, die pro Operation erzeugt werden dürfen
`singleton()`	Im selben Container wird die bereits erzeugte Instanz wiederverwendet	Services, die keinen request- oder jobspezifischen Zustand halten
`scoped()`	Innerhalb desselben Lebenszyklus wiederverwendet, an der Grenze wird die gespeicherte Instanz entfernt	Zustand, der innerhalb eines Requests oder Jobs geteilt wird

Diese Tabelle vergleicht die gewöhnliche Auflösung. Sonderwege wie die Auflösung mit expliziten Parametern oder Contextual Binding sollten Sie gesondert prüfen. Auch bei bind() bleibt die Referenz bestehen, wenn Sie den abgerufenen Service in einer Eigenschaft eines anderen Singletons speichern. Die Registrierungsmethode ist eine Regel des Containers für Erzeugung und Wiederverwendung, keine Regel, die die vom Nutzer gehaltenen Objekte zwangsweise neu erstellt.

scoped kombiniert eine geteilte Registrierung mit der Erfassung der zu entfernenden Schlüssel

Das untersuchte Container::scoped() erledigt zwei Dinge:

Es erfasst den Registrierungsschlüssel in scopedInstances.
Es ruft singleton() auf und registriert damit ein geteiltes Binding.

Die Instanz selbst wird wie bei einem Singleton in instances gespeichert. forgetScopedInstances() entfernt für die erfassten Schlüssel die gespeicherten Instanzen per unset(). Die Erzeugungslogik des Bindings bleibt erhalten, sodass die nächste gewöhnliche Auflösung ein neues Objekt erstellen kann. Dieser Vorgang initialisiert weder die Eigenschaften des alten Objekts neu noch schreibt er Referenzen um, die andere Objekte halten. Ein altes Objekt, auf das noch eine Referenz besteht, kann weiterhin verwendet werden.

Die Grenze wird von der Ausführungsumgebung gesetzt

Der Container selbst überwacht nicht den Beginn von HTTP-Requests oder Jobs.

Queue-Worker: QueueServiceProvider übergibt dem Worker einen Callback, der den Scope zurücksetzt. Worker::daemon() ruft diesen in der Schleife vor dem Abrufen des nächsten Jobs auf. Im Callback werden unter anderem forgetScopedInstances() ausgeführt und die aufgelösten Instanzen der Facades geleert.
Octane: Die offizielle Standardkonfiguration registriert FlushTemporaryContainerInstances für OperationTerminated. Dieser Listener ruft forgetScopedInstances() auf.
Eigene dauerhaft laufende Befehle oder Schleifen: Das bloße Wiederholen von make() erzeugt keine Grenze. Der Lebenszyklus muss auf Seiten der Ausführungsplattform entworfen werden.

Rufen Sie forgetScopedInstances() nicht nach eigenem Ermessen aus gewöhnlicher Anwendungslogik oder aus boot() eines Pakets auf. Das betrifft alle scoped Services im gesamten Container. Außerdem durchlaufen nicht alle Job-Ausführungswege, einschließlich der synchronen Ausführung, denselben Reset-Weg wie ein dauerhaft laufender Worker.

Innerhalb einer Verarbeitung geteilten Zustand als scoped registrieren

Betrachten wir ein Versandpaket, das innerhalb eines Requests oder Jobs die ID eines Lieferziels teilen möchte. Es hält nicht direkt den HTTP-Request, sondern speichert nur den benötigten Wert.

<?php

namespace Acme\Courier;

final class DeliveryContext
{
    private ?string $destinationId = null;

    public function setDestinationId(string $destinationId): void
    {
        $this->destinationId = $destinationId;
    }

    public function destinationId(): ?string
    {
        return $this->destinationId;
    }
}

Im Service Provider des Pakets wird bei der Erzeugung kein Zustand der nutzenden Anwendung gelesen, sondern ein leerer Context registriert.

<?php

namespace Acme\Courier;

use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->scoped(DeliveryContext::class);
    }
}

Im Controller oder in handle() eines Jobs der nutzenden Anwendung wird die ID gesetzt, nachdem die Eingabe validiert und die Berechtigung geprüft wurde. Andere Services, die diesen Typ im selben Lebenszyklus auflösen, können auf denselben Context zugreifen.

$context = app(\Acme\Courier\DeliveryContext::class);
$context->setDestinationId($authorizedDestinationId);

Dieser Context ist keine Autorisierungsfunktion. Dass eine ID gesetzt werden kann, bedeutet nicht, dass der Zugriff auf dieses Lieferziel erlaubt ist. Außerdem ist scoped() keine Persistierung in einer Datenbank oder einem externen Cache. Werte für den nächsten Job übergeben Sie explizit als Daten des Jobs.

In Octane werden register() und boot() des Service Providers beim ersten Start des Workers ausgeführt. Entwerfen Sie es nicht so, dass der aktuelle Benutzer oder das aktuelle Lieferziel in boot() im Context gespeichert wird. Werte pro Verarbeitung setzen Sie erst, nachdem die Verarbeitung begonnen hat.

Referenzen von einem Singleton auf scoped Services werden nicht automatisch aktualisiert

Bei der folgenden Registrierung genügt es nicht, nur den Context als scoped zu registrieren:

$this->app->singleton(DeliveryService::class, function ($app) {
    return new DeliveryService($app->make(DeliveryContext::class));
});

Wenn DeliveryService den Context im Konstruktor in einer Eigenschaft speichert, behält er den zuerst erzeugten Context. Auch wenn der gespeicherte Context aus dem Container entfernt wird, ändert sich die Eigenschaft des bereits erzeugten DeliveryService nicht. Wählen Sie die Gegenmaßnahme passend zur Verantwortung des Service:

Die pro Verarbeitung benötigten Werte als Methodenargumente übergeben. Wenn kein Zustand geteilt werden muss, ist dies am einfachsten.
Auch die haltende Seite als scoped registrieren. Sowohl DeliveryService als auch der Context werden pro Verarbeitung neu erstellt.
Einen Resolver übergeben, der zum Zeitpunkt der Verwendung auflöst. Wenn der Singleton beibehalten werden muss, holen Sie den benötigten Service jedes Mal aus dem aktuellen Container.

Im dritten Beispiel wird nicht der alte Context in die Closure übernommen, sondern zum Zeitpunkt des Aufrufs aufgelöst.

use Illuminate\Container\Container;

$this->app->singleton(DeliveryService::class, function () {
    return new DeliveryService(
        fn () => Container::getInstance()->make(DeliveryContext::class),
    );
});

Der DeliveryService in diesem Beispiel muss so umgestellt werden, dass er im Konstruktor eine Closure entgegennimmt und eine API bietet, die sie bei jeder Operation aufruft. Ruft der Konstruktor den Resolver nur einmal auf und speichert das Ergebnis, ist das Problem nicht gelöst. Dies ist ein Designbeispiel, das den Container-Resolver aus der offiziellen Octane-Dokumentation auf einen paketspezifischen Context überträgt.

Auch Zustand prüfen, den scoped nicht entfernt

scoped() entfernt den folgenden Zustand nicht automatisch:

Werte, die zu paketeigenen statischen Eigenschaften hinzugefügt wurden
Referenzen auf den Context, die in einem anderen Singleton oder einer globalen Variable gespeichert sind
„Aktueller Benutzer“ oder „aktuelles Lieferziel“, die im Inneren eines Singletons gehalten werden
Referenzen, die von eigenen Facades oder Cache-Schichten gehalten werden

Unterscheiden Sie zwischen dem Reset durch die Standard-Ausführungsplattform und dem Reset paketeigenen Zustands. Die Zahl der Orte zu verringern, an denen Zustand pro Verarbeitung gehalten wird, ist einfacher, als in jeder Ausführungsumgebung eigene Aufräumlogik zu pflegen.

Tests schreiben, die im selben Container eine Grenze überschreiten

Wenn HTTP-Tests lediglich jedes Mal eine neue Anwendung erstellen, können Probleme übersehen werden, die entstehen, wenn ein dauerhaft laufender Prozess denselben Container weiterverwendet. Prüfen Sie zunächst mit dem Container allein, dass innerhalb einer Verarbeitung geteilt und nach der Grenze neu erzeugt wird. Die folgenden Tests sind im PHPUnit-Format. Der erste Test verwendet wie die offiziellen Container-Tests forgetScopedInstances() und prüft die Wirkung der Grenze, ohne den gesamten Worker zu starten.

<?php

namespace Acme\Courier\Tests;

use Acme\Courier\DeliveryContext;
use Illuminate\Container\Container;
use PHPUnit\Framework\TestCase;

class ServiceLifetimeTest extends TestCase
{
    public function test_context_is_shared_then_recreated(): void
    {
        $container = new Container;
        $container->scoped(DeliveryContext::class);

        $first = $container->make(DeliveryContext::class);
        $first->setDestinationId('destination-a');

        $this->assertSame($first, $container->make(DeliveryContext::class));
        $this->assertSame('destination-a', $first->destinationId());

        $container->forgetScopedInstances();

        $second = $container->make(DeliveryContext::class);
        $this->assertNotSame($first, $second);
        $this->assertNull($second->destinationId());
    }

    public function test_singleton_keeps_a_captured_scoped_dependency(): void
    {
        $container = new Container;
        $container->scoped(DeliveryContext::class);
        $container->singleton('courier.holder', function ($app) {
            return (object) ['context' => $app->make(DeliveryContext::class)];
        });

        $holder = $container->make('courier.holder');
        $oldContext = $holder->context;

        $container->forgetScopedInstances();

        $this->assertSame($holder, $container->make('courier.holder'));
        $this->assertSame($oldContext, $holder->context);
        $this->assertNotSame($oldContext, $container->make(DeliveryContext::class));
    }
}

Der zweite Test dokumentiert das Verhalten, dass Referenzen bestehen bleiben. Fügen Sie dem tatsächlichen Paket außerdem Tests hinzu, die prüfen, dass mit der gewählten Gegenmaßnahme ein neuer Context bzw. neue Werte verwendet werden.

Prüfung bei Updates	Erwartetes Ergebnis
Context innerhalb derselben Verarbeitung mehrfach auflösen	Dieselbe Instanz und der gesetzte Wert werden geteilt
Im selben Container über eine Grenze hinweg auflösen	Neue Instanz ohne den vorherigen Wert
Singleton verwendet den Context	Speichert keinen alten Context, sondern verwendet den aktuellen Wert
Aufeinanderfolgende Octane-Requests in der nutzenden Anwendung ausführen	Der zweite Request übernimmt nicht das Lieferziel usw. des ersten
Aufeinanderfolgende Jobs in einem dauerhaft laufenden Queue-Worker ausführen	Die Einstellungen werden pro Job getrennt
Laravel und Octane aktualisieren	Aufrufweg des Resets und Konfiguration der nutzenden Anwendung erneut prüfen

Unit-Tests des Containers allein prüfen nicht den tatsächlichen Ausführungsweg der Octane-Sandbox oder des Queue-Workers. Für jede Ausführungsumgebung, deren Unterstützung Sie zusichern, benötigen Sie zusätzlich Integrationstests mit aufeinanderfolgenden Verarbeitungen. Bei Deployments, die Registrierungsmethoden oder Service-Implementierungen ändern, laden Sie dauerhaft laufende Prozesse neu, damit der neue Code angewendet wird.

Hooks nach der Service-Auflösung in Paketen

Erläutert afterResolving, den Abruf geteilter Instanzen und Unterschiede bei der Konfiguration nach erneuter Auflösung.

Laravel Octane

Erläutert das Halten von Request und Container sowie Hinweise für den Betrieb dauerhaft laufender Prozesse.

KI-Entwicklung

Design Patterns

Paketentwicklung

Anwendungsstruktur

Neue Funktionen in Laravel 13

Eloquent im Detail

Validierungserweiterungen

Erweiterung der Authentifizierung

Sicherheit

Warteschlangen

Tests

Echtzeit

Lebenszyklus-Design für Paket-Services

Die Registrierungsmethode nach der Haltedauer des Service wählen

scoped kombiniert eine geteilte Registrierung mit der Erfassung der zu entfernenden Schlüssel

Die Grenze wird von der Ausführungsumgebung gesetzt

Innerhalb einer Verarbeitung geteilten Zustand als scoped registrieren

Referenzen von einem Singleton auf scoped Services werden nicht automatisch aktualisiert

Auch Zustand prüfen, den scoped nicht entfernt

Tests schreiben, die im selben Container eine Grenze überschreiten

Verwandte Seiten

Hooks nach der Service-Auflösung in Paketen

Laravel Octane

Herangezogene Primärquellen

​Die Registrierungsmethode nach der Haltedauer des Service wählen

​scoped kombiniert eine geteilte Registrierung mit der Erfassung der zu entfernenden Schlüssel

​Die Grenze wird von der Ausführungsumgebung gesetzt

​Innerhalb einer Verarbeitung geteilten Zustand als scoped registrieren

​Referenzen von einem Singleton auf scoped Services werden nicht automatisch aktualisiert

​Auch Zustand prüfen, den scoped nicht entfernt

​Tests schreiben, die im selben Container eine Grenze überschreiten

​Verwandte Seiten

Hooks nach der Service-Auflösung in Paketen

Laravel Octane

​Herangezogene Primärquellen

Die Registrierungsmethode nach der Haltedauer des Service wählen

scoped kombiniert eine geteilte Registrierung mit der Erfassung der zu entfernenden Schlüssel

Die Grenze wird von der Ausführungsumgebung gesetzt

Innerhalb einer Verarbeitung geteilten Zustand als scoped registrieren

Referenzen von einem Singleton auf scoped Services werden nicht automatisch aktualisiert

Auch Zustand prüfen, den scoped nicht entfernt

Tests schreiben, die im selben Container eine Grenze überschreiten

Verwandte Seiten

Herangezogene Primärquellen