Zum Inhalt springen
Dokumentation · Integrationen

Laravel

Middleware für jede Methode, nicht nur für Routen. goaop/goaop-laravel-bridge 2.0 hängt Behaviors an Ihre Klassen, und Laravels Container, Config und Artisan erledigen den Rest.

Aus dem Englischen übersetzt. Maßgeblich ist die englische Seite. Original lesen

Middleware gehört zu den besten Ideen von Laravel. Eine Anfrage durchläuft einen Stapel kleiner Klassen, und jede fügt genau eine Sache hinzu (Authentifizierung, Throttling, eine Session), ohne Ihren Controller anzufassen. Die Bridge goaop/goaop-laravel-bridge 2.0 überträgt diese Idee auf jede Methode und jede Property Ihrer Anwendung, ob public, protected oder private. Sie schreiben ein Behavior (Verhalten) einmal, legen fest, wo es greift, und es läuft als dynamische Middleware um diese Aufrufe: in Services, Actions, Jobs und jeder anderen Klasse in app/.

app/Services/OrderService.php
use App\Attributes\Transactional;
final class OrderService
{
public function __construct(private readonly Inventory $inventory) {}
#[Transactional]
public function place(Cart $cart): Order
{
$order = Order::create(['customer_id' => $cart->customerId]);
$order->lines()->createMany($cart->lines());
$this->inventory->reserve($cart);
return $order;
}
}
app/Behaviors/TransactionalBehavior.php
namespace App\Behaviors;
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Around;
use Illuminate\Support\Facades\DB;
final class TransactionalBehavior implements Aspect
{
#[Around('@execution(App\Attributes\Transactional)')]
public function inTransaction(MethodInvocation $invocation): mixed
{
return DB::transaction(fn () => $invocation->proceed());
}
}

Das ist das ganze Muster. Wenn Sie schon einmal das handle($request, $next) einer Middleware geschrieben haben, kennen Sie es bereits: $invocation->proceed() ist Ihr $next($request). Jede mit #[Transactional] markierte Methode wird jetzt als Einheit committet oder zurückgerollt, und OrderService enthält weiterhin nur die Geschäftslogik. Sie brauchen weder eine Basisklasse noch ein Interface, einen Decorator oder einen Aufruf von app()->extend().

  • Installiert sich wie jedes andere Paket. composer require, und Package Discovery registriert den Service-Provider. Eine einzige veröffentlichbare Config-Datei, config/go_aop.php, mit Überschreibungen per GOAOP_*-Umgebungsvariablen.
  • Behavior-Klassen (Verhaltensklassen) sind Container-Services. Der Laravel-Container baut jede Behavior-Klasse, wenn eines ihrer Behaviors zum ersten Mal läuft. Constructor Injection funktioniert, ebenso Facades, config() und jeder Service, den Ihre Anwendung bindet.
  • Registrieren Sie sie dort, wo Sie alles andere registrieren. Tragen Sie eine Klasse in die Config ein, oder taggen Sie einen Service in einem Service-Provider mit goaop.aspect; so kann auch ein Paket seine eigenen Behaviors beisteuern.
  • Artisan erledigt die Arbeit für die Produktion. php artisan aop:warmup baut den Cache beim Deployment, auf Wunsch in parallelen Workern. Es passt in das Deployment, das Sie ohnehin fahren, nach composer install und php artisan optimize. php artisan about zeigt den Ort des Caches und den Debug-Modus.
  • Kein Build-Schritt in der Entwicklung. Mit eingeschaltetem debug wird eine geänderte Klasse bei der nächsten Anfrage neu kompiliert, und Breakpoints funktionieren in Ihren ursprünglichen Dateien.

Was ein Behavior erreicht, ein Decorator aber nicht

Abschnitt betitelt „Was ein Behavior erreicht, ein Decorator aber nicht“

Ein Decorator umhüllt ein Objekt, das Sie aus dem Container auflösen; er sieht also nur public-Methoden, und nur auf diesem Weg. Ein Behavior wird an die Klasse selbst gehängt, während sie geladen wird, daher gilt:

  • Jede Instanz bekommt es. Objekte aus dem Container und Objekte, die Sie mit new erzeugen, verhalten sich gleich. Type Hints, instanceof und der Klassenname bleiben unverändert, weil es kein umhüllendes Objekt gibt.
  • Jede Art von Methode kommt infrage. Private, protected, final und statische Methoden sowie Methoden von final- und readonly-Klassen (Intercept anything).
  • Auch Properties. Lese- und Schreibzugriffe auf public, protected und private Properties, per Constructor Promotion deklarierte eingeschlossen, über native Property-Hooks von PHP 8.4: access(private App\Domain\Order->status) oder @access(App\Attributes\Audited) (Behaviors an Properties).
  • Eine Regel kann einen ganzen Namespace abdecken. execution(public App\Services\**->*(*)) wählt jede public-Methode unterhalb von App\Services aus, auch die Klassen, die Sie nächsten Monat hinzufügen (Matching-Rules (Auswahlregeln)).
  • Die Kosten sind gering. Methoden und Properties ohne Behaviors kosten nichts zusätzlich. Eine Methode oder Property mit einem Behavior bezahlt weniger als 1 µs pro Aufruf (gemessene Kosten).
  • Es ist reines PHP. Keine PECL-Erweiterung und kein eval(). Die kompilierten Klassen sind gewöhnliche .php-Dateien in storage/framework/aop, Sie können sie also lesen (Pure PHP).
  • PHP 8.4 oder neuer
  • Laravel 12 oder 13
  • goaop/framework ^4.0 (Behaviors per Attribut deklariert), wird mit der Bridge installiert
Terminal-Fenster
composer require goaop/goaop-laravel-bridge

Package Discovery registriert den Service-Provider automatisch. Veröffentlichen Sie die Konfiguration, wenn Sie sie ändern möchten:

Terminal-Fenster
php artisan vendor:publish --tag=goaop-config

Eine Behavior-Klasse (in der API ein Aspect (Aspekt)) ist eine gewöhnliche Klasse, die Go\Aop\Aspect implementiert. Jede ihrer public-Methoden mit #[Before], #[After], #[Around] oder #[AfterThrowing] ist ein Behavior, und der String in diesem Attribut ist seine Matching-Rule (in der API ein Pointcut): Sie legt fest, wo das Behavior läuft.

  1. Legen Sie ein Attribut an, um die Methoden zu markieren, oder überspringen Sie diesen Schritt und wählen Sie Methoden nach Namen aus (siehe nächster Abschnitt).

    app/Attributes/Transactional.php
    namespace App\Attributes;
    use Attribute;
    #[Attribute(Attribute::TARGET_METHOD)]
    final class Transactional {}
  2. Schreiben Sie die Behavior-Klasse. TransactionalBehavior vom Anfang dieser Seite ist vollständig. #[Around] führt das Behavior anstelle der Methode aus, und @execution(App\Attributes\Transactional) wählt jede Methode aus, die das Attribut trägt.

  3. Registrieren Sie die Behavior-Klasse in config/go_aop.php:

    config/go_aop.php
    'aspects' => [
    App\Behaviors\TransactionalBehavior::class,
    ],
  4. Markieren Sie eine Methode mit #[Transactional], und rufen Sie sie auf. Die nächste Anfrage führt sie innerhalb einer Transaktion aus.

Ein Behavior braucht kein Attribut am Ziel. Eine Matching-Rule kann Methoden nach Name, Namespace oder Sichtbarkeit auswählen; so bekommt eine ganze Schicht der Anwendung das Behavior, ohne dass sich ihre Klassen ändern:

app/Behaviors/ServiceTimingBehavior.php
namespace App\Behaviors;
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Around;
use Go\Lang\Attribute\Before;
use Illuminate\Support\Facades\Log;
final class ServiceTimingBehavior implements Aspect
{
#[Before('execution(public App\Services\**->*(*))')]
public function logCall(MethodInvocation $invocation): void
{
Log::debug('Calling ' . $invocation->getMethod()->getName());
}
#[Around('execution(public App\Services\PaymentService->charge(*))')]
public function measureCharge(MethodInvocation $invocation): mixed
{
$start = hrtime(true);
try {
return $invocation->proceed();
} finally {
Log::info('charge() took ' . (hrtime(true) - $start) / 1e6 . ' ms');
}
}
}

logCall() läuft vor jeder public-Methode unterhalb von App\Services. measureCharge() umschließt eine einzelne Methode und misst ihre Dauer, auch wenn sie eine Exception wirft. Die vier Attribute, der Call-Context (Aufrufkontext, $invocation) und die vollständige Regelsyntax stehen in Behaviors & Matching-Rules. Vollständige Schritt-für-Schritt-Beispiele finden Sie beim Caching-Behavior und beim Logging-Behavior.

Sie übergeben Behavior-Klassen nie selbst an die Engine. In der Boot-Phase, nachdem sich alle Service-Provider registriert haben und bevor Ihr Anwendungscode läuft, sammelt die Bridge sie aus zwei Quellen.

Die Liste in der Config. Tragen Sie die Klasse wie in den Schritten oben in config/go_aop.php ein. Eine eingetragene Klasse wird registriert, sobald der Kernel startet, ohne dass die Klasse geladen wird. Der Laravel-Container löst sie beim ersten Aufruf eines ihrer Behaviors auf, daher darf eine Behavior-Klasse von Services abhängen, die erst existieren, wenn die Anwendung vollständig gebootet ist. Eine Anfrage, die keines ihrer Behaviors ausführt, erzeugt sie nie.

Das Tag goaop.aspect. Taggen Sie einen Service in einem Ihrer Service-Provider:

app/Providers/AppServiceProvider.php
use App\Behaviors\ServiceTimingBehavior;
use Psr\Log\LoggerInterface;
// in register()
$this->app->singleton(ServiceTimingBehavior::class, function ($app) {
return new ServiceTimingBehavior($app->make(LoggerInterface::class));
});
$this->app->tag([ServiceTimingBehavior::class], 'goaop.aspect');

Verwenden Sie das Tag, wenn eine Behavior-Klasse eine nicht triviale Konstruktion braucht oder wenn ein Paket Behavior-Klassen beisteuert, ohne Ihre Config anzufassen. Getaggte Services werden aufgelöst, wenn der Provider der Bridge bootet, weil sich ein Laravel-Tag nur aufzählen lässt, indem man seine Services auflöst. Bevorzugen Sie die Liste in der Config für Behavior-Klassen mit schweren oder vom Boot abhängigen Konstruktoren.

Sie können beide Quellen kombinieren; Duplikate werden einmal registriert. Eine gefundene Klasse, die Go\Aop\Aspect nicht implementiert, scheitert mit einer aussagekräftigen Exception. Der Laravel-Container ist als PSR-11-Delegate an den Container des Kernels angebunden, sodass Behaviors und die Factorys von Behavior-Klassen darüber Services der Anwendung abrufen können.

Die wichtigsten Optionen in config/go_aop.php. Jede lässt sich über die Umgebung überschreiben.

Option Standard Zweck
debug GOAOP_DEBUG → APP_DEBUG Bei Änderungen an den Quellen neu kompilieren, mit Breakpoints in den ursprünglichen Dateien; in Produktion ausgeschaltet lassen
appDir base_path() Wurzelverzeichnis, das der Compiler anfassen darf
cacheDir storage_path('framework/aop') (GOAOP_CACHE_DIR) Wo kompilierte Quellen und Proxys gecacht werden
cacheFileMode 0770 (GOAOP_CACHE_PERMISSIONS, Oktalziffern, z. B. "770") chmod für Cache-Dateien
parsedFilesLimit 100 (GOAOP_PARSED_FILES_LIMIT) Geparste Quelldateien (je etwa 0,2 MB), die beim Kompilieren im Speicher bleiben; der Standard von aop:warmup --cached-files
includePaths [app_path()] Nur diese Verzeichnisse werden kompiliert
excludePaths [] Diese nie kompilieren
features 0 (GOAOP_FEATURES) Bitmaske aus Go\Aop\Features-Flags: INTERCEPT_INCLUDES = 4, PREBUILT_CACHE = 64, PARTIAL_REFLECTION = 256
aspects [] Zu registrierende Behavior-Klassen

Behaviors an Funktionsaufrufen und an der Objekterzeugung werden von ihren Matching-Rules gesteuert und brauchen kein Flag. php artisan about zeigt den aktuellen Ort des Framework-Caches und den Debug-Modus.

Terminal-Fenster
php artisan aop:warmup

Ohne Warm-up wird jede Klasse beim ersten Laden kompiliert. Führen Sie aop:warmup beim Deployment aus, um alle vorab zu kompilieren; bei ausgeschaltetem debug ist das empfohlen. Der Befehl endet mit einem Status ungleich null, wenn sich eine Datei nicht kompilieren lässt, sodass ein Deploy-Skript abbricht, statt einen unvollständigen Cache auszuliefern. Mit --fail-fast hält er beim ersten Fehler an.

Terminal-Fenster
php artisan aop:warmup --workers=8
php artisan aop:warmup --cache-dir=/srv/app/releases/next/storage/framework/aop
php artisan aop:warmup --preload
  • --workers=N kompiliert in parallelen Worker-Prozessen. Jeder Worker ist Ihr eigenes artisan und bootet daher mit derselben Umgebung, derselben Konfiguration und denselben Behavior-Klassen.
  • --cache-dir=DIR baut den Cache eines neuen Release neben dem laufenden. Ein so gebauter Cache ist vollständig und ortsunabhängig.
  • --preload schreibt ein opcache.preload-Skript: _preload.php im gerade gebauten Cache-Verzeichnis oder die mit --preload=FILE angegebene Datei.

Um kompilierte Skripte mit einem Container-Image auszuliefern, befüllen Sie opcache.file_cache nach dem Warm-up und nach php artisan optimize im finalen Image vor:

Terminal-Fenster
php artisan optimize
mkdir -p /var/cache/opcache && php -d opcache.enable_cli=1 -d opcache.file_cache_only=1 \
-d opcache.file_cache=/var/cache/opcache \
artisan aop:warmup-opcache --file-cache=/var/cache/opcache
Terminal-Fenster
composer install --no-dev --optimize-autoloader # runs package:discover, with an empty framework cache
php artisan optimize # the cached configuration carries GOAOP_FEATURES
php artisan aop:warmup

Mit GOAOP_FEATURES=64 (PREBUILT_CACHE) kompiliert eine Anfrage nie. Eine Klasse unterhalb der Include-Pfade, die im Cache fehlt, scheitert mit einer WeavingException; führen Sie aop:warmup daher bei jedem Deployment aus. Laravels Cache-Befehle (package:discover, optimize, optimize:clear sowie die Cache- und Clear-Befehle für config, event, route und view) bedienen keine Anfrage und laden Klassen daher aus ihrer ursprünglichen Quelle. Deshalb funktioniert die Reihenfolge oben.

Sobald die Konfiguration gecacht ist, wird env() nicht mehr gelesen. Führen Sie optimize (oder config:cache) mit der Produktionsumgebung aus, GOAOP_FEATURES eingeschlossen. Die vollständige Checkliste steht unter Produktion & Performance.

  • Der Compile-Step (Kompilierschritt) beginnt am Anfang der Boot-Phase. Klassen, die vorher geladen werden (sehr früher Bootstrap-Code, Interna aus register() anderer Pakete, Ihre eigenen Service-Provider), können keine Behaviors bekommen.
  • Berücksichtigt werden nur Klassen unter appDir und includePaths. Vendor-Code wird nicht kompiliert.
  • Schließen Sie Exception-Handler über excludePaths aus: Tritt ein fataler Fehler auf, lässt sich ein kompilierter Handler aus einem kalten Cache womöglich nicht laden.

© 2026 Alexander Lisachenko