Zum Inhalt springen
Dokumentation · Integrationen

Symfony

Symfony-Integration mit goaop/goaop-symfony-bundle 4.0: automatisch konfigurierte Behavior-Klassen, ein Panel im Web-Profiler und Cache-Warm-up.

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

Das Bundle goaop/goaop-symfony-bundle 4.0 hängt Behaviors (Verhalten) an Ihre Services, während diese geladen werden. Basisklassen oder Decorators brauchen Sie nicht.

namespace App\Aspect;
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Around;
use Psr\Log\LoggerInterface;
final class TimingAspect implements Aspect
{
public function __construct(private readonly LoggerInterface $logger) {}
#[Around('execution(public App\Service\**->*(*))')]
public function measure(MethodInvocation $invocation): mixed
{
$start = hrtime(true);
try {
return $invocation->proceed();
} finally {
$this->logger->info('{method} took {ms} ms', [
'method' => (string) $invocation,
'ms' => (hrtime(true) - $start) / 1e6,
]);
}
}
}

Das ist die ganze Integration. Die Klasse implementiert Go\Aop\Aspect, daher registriert die Autoconfiguration sie als Behavior-Klasse (Verhaltensklasse), und Autowiring gibt ihr ihren Logger. Ab der nächsten Anfrage wird jede public-Methode jeder Klasse unterhalb von App\Service gemessen.

  • PHP 8.4 oder neuer
  • Symfony 7.4 oder 8.x
  • goaop/framework ^4.0 (Behaviors per Attribut deklariert)
Terminal-Fenster
composer require goaop/goaop-symfony-bundle

Registrieren Sie das Bundle als ersten Eintrag in config/bundles.php:

config/bundles.php
return [
Go\Symfony\GoAopBundle\GoAopBundle::class => ['all' => true],
Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
// ...
];

Der Compile-Step (Kompilierschritt) greift nur für Klassen, die nach der Initialisierung des Kernels geladen werden, und Bundles booten in der Reihenfolge ihrer Registrierung. Das Bundle erzwingt das: Steht es nicht an erster Stelle, schlägt der Container-Build mit einer klaren Meldung fehl.

Die Konfigurationsdatei ist optional. Mit den Standardwerten unten kompiliert das Bundle das Verzeichnis src/ im Modus des Kernels und aktiviert in Produktion den vorab gebauten Cache:

config/packages/go_aop.yaml
go_aop:
include_paths: ['%kernel.project_dir%/src']
when@prod:
go_aop:
features: [PREBUILT_CACHE]

bin/console config:dump-reference go_aop gibt die vollständige Referenz aus. Alle Optionen mit ihren Standardwerten:

config/packages/go_aop.yaml
go_aop:
# Development mode: changed sources and behavior classes are compiled again on the next request,
# breakpoints work in the original files. Keep it off in production.
debug: '%kernel.debug%'
# Application root: only files below it can be compiled, cache paths mirror source paths relative to it.
app_dir: '%kernel.project_dir%'
# Directory for generated sources, proxies and behavior caches. Anchor it on %kernel.cache_dir%
# or %kernel.build_dir% so that cache:clear and cache:warmup manage it.
cache_dir: '%kernel.cache_dir%/aop'
# Permissions of the cache files: an octal literal (0o770), an octal string ("0770") or an integer.
# Defaults to 0770 minus the umask.
cache_file_mode: ~
# Directories that are compiled. Keep the list narrow: compiling vendor code is slow and rarely needed.
include_paths: ['%kernel.project_dir%/src']
# Directories below the include paths that are never compiled (the cache directory and the
# framework itself are always excluded).
exclude_paths: []
# Number of parsed source files the compiler keeps in memory (about 0.2 MB each).
parsed_files_limit: 100
# Framework features, by the name of the Go\Aop\Features constant:
# PREBUILT_CACHE trust the deployed cache completely, never check or write it at runtime
# INTERCEPT_INCLUDES route include/require in compiled files through the compiler (legacy code)
# PARTIAL_REFLECTION compile classes whose parent class, interface or trait Composer can not
# locate, with their own members
features: []
# Kernel class; extend Go\Symfony\GoAopBundle\Kernel\AspectSymfonyKernel to customize
# the transformation pipeline.
kernel_class: Go\Symfony\GoAopBundle\Kernel\AspectSymfonyKernel
# Compile every file below the include paths during cache:warmup and cache:clear.
cache_warmer: true
# Doctrine ORM integration, enabled automatically when DoctrineBundle is registered.
doctrine: ~

Umgebungsvariablen funktionieren wie überall in Symfony, zum Beispiel debug: '%env(bool:GOAOP_DEBUG)%'. Funktions- und initialization()-Matching-Rules (Auswahlregeln) brauchen kein Feature-Flag: Sie schalten ihre Maschinerie selbst ein.

Eine Behavior-Klasse ist ein gewöhnlicher Service mit Autowiring. Die Autoconfiguration registriert jeden Service, der Go\Aop\Aspect implementiert. Ohne Autoconfiguration taggen Sie den Service mit goaop.aspect:

services:
Acme\Audit\AuditAspect:
tags: [goaop.aspect]

Eine Behavior-Klasse ist ein Singleton: Sie als zwei Services zu registrieren, ist ein Fehler beim Kompilieren des Containers.

Der Compiler braucht nur die Behavior-Klassen. Der Symfony-Container erzeugt eine Behavior-Klasse, wenn eines ihrer Behaviors zum ersten Mal läuft, nie während des Compile-Steps oder des Cache-Warm-ups. Der Container des Kernels (AspectContainer) delegiert außerdem an den Symfony-Container, sodass $aspectContainer->get(LoggerInterface::class) funktioniert. Go\Core\AspectKernel und Go\Core\AspectContainer sind per Autowiring verfügbare Services, und goaop.aspect_kernel ist public.

Prüfen Sie, was eine Behavior-Klasse trifft, bevor Sie sich darauf verlassen:

Terminal-Fenster
bin/console debug:aspect # behavior classes with their rules and behaviors
bin/console debug:advisor --advisor='App\Aspect\TimingAspect->measure' # the methods one behavior matches

Im Debug-Modus werden Klassen unterhalb der Include-Pfade beim ersten Laden kompiliert und erneut kompiliert, wenn sich ihre Quelle oder eine Behavior-Klasse ändert.

Ist symfony/web-profiler-bundle installiert, zeigt die Toolbar die Anzahl der Behavior-Klassen. Das Panel Go! AOP listet:

  • die Behavior-Klassen mit ihren Advisors, Behavior-Attributen und Matching-Rules;
  • die während der Anfrage geladenen kompilierten Klassen mit ihren Proxy-Dateien;
  • die Klassen unterhalb der Include-Pfade, die vor der Initialisierung des Kernels geladen wurden (das Panel wird gelb);
  • die wirksame Konfiguration des Kernels.

Die dritte Liste ist die Diagnose für ein Bundle, das vor GoAopBundle bootet, und für die eine Anfrage, die den Container neu gebaut hat. Diese Anfrage muss die Service-Klassen laden, bevor das Bundle bootet, und führt sie daher einmal ohne ihre Behaviors aus. Die nächste Anfrage läuft vollständig kompiliert. Deployments sind nicht betroffen, weil cache:clear und cache:warmup den Container und den Cache des Frameworks gemeinsam bauen.

Das Bundle schaltet außerdem Symfonys .container.dumper.inline_class_loader ab, sofern Ihre Konfiguration diese Option nicht setzt. Sie bindet Service-Dateien direkt ein, umgeht damit den Class-Loader und folglich den Compile-Step.

Terminal-Fenster
composer install --no-dev --optimize-autoloader # runs cache:clear through the auto-scripts
# or explicitly
bin/console cache:clear
bin/console cache:warmup

cache:clear und cache:warmup kompilieren die gesamte Anwendung über einen Cache-Warmer. cache:clear baut den neuen Cache neben dem laufenden und benennt ihn anschließend um. Der Warmer baut den Cache des Frameworks von Grund auf in diesem neuen Verzeichnis, Ihre üblichen Deployment-Schritte bleiben also unverändert. Das Warm-up schlägt fehl, wenn sich eine Datei nicht kompilieren lässt, sodass ein Deployment abbricht, statt einen unvollständigen Cache auszuliefern. Mit cache:warmup:aop --fail-fast -vvv sehen Sie die Datei und den Fehler.

Die Befehle des Frameworks sind in der Konsole Ihrer Anwendung registriert. Sie arbeiten mit dem laufenden Kernel, daher lassen Sie das Loader-Argument von vendor/bin/aspect weg.

Befehl Zweck
cache:warmup:aop [--fail-fast] [--cache-dir=DIR] [--cached-files=N] [--preload[=FILE]] Kompiliert jede Datei unterhalb der Include-Pfade in den Cache. Schlägt fehl, wenn sich eine Datei nicht kompilieren lässt. --preload schreibt zusätzlich das opcache.preload-Skript des Caches.
cache:warmup:opcache [--file-cache=DIR] [--entry=FILE] Befüllt den OPcache-File-Cache (opcache.file_cache) mit dem Cache des Frameworks und der Anwendung vor. Führen Sie ihn im finalen Image aus.
debug:aspect [--aspect=FQCN] Listet die Behavior-Klassen mit ihren Matching-Rules und Advisors.
debug:advisor [--advisor=ID] Listet die Advisors; mit --advisor, was dieser Advisor trifft.
debug:weaving [-v] Kompiliert die Anwendung zweimal und meldet Proxys, die sich unterscheiden, was auf eine nicht deterministische Behavior-Klasse hinweist.

cache:warmup:aop --workers=N kompiliert hier in einem einzigen Prozess: Seine Worker-Prozesse würden den Kernel mit einer Loader-Datei booten, und die Konsole der Anwendung hat keine.

config/packages/go_aop.yaml
when@prod:
go_aop:
features: [PREBUILT_CACHE]

Mit PREBUILT_CACHE überspringt die Laufzeit jede Dateisystemprüfung rund um den Cache und kompiliert nie und schreibt nie in das Cache-Verzeichnis. Eine Klasse unterhalb der Include-Pfade, die der Cache nicht kennt, scheitert mit einer WeavingException („… is missing from the prebuilt AOP cache …“). Bauen Sie den Cache bei jedem Deployment neu. Das ist die empfohlene Einstellung für die Produktion; mit ihr funktionieren schreibgeschützte Dateisysteme und unveränderliche Images.

Wenn Ihr kernel.build_dir von kernel.cache_dir abweicht, verankern Sie den Cache des Frameworks im Verzeichnis, das Sie beim Deployment bauen: cache_dir: '%kernel.build_dir%/aop'.

Für OPcache-Preloading binden Sie das Preload-Skript des Framework-Caches vor der Preload-Datei des Containers ein:

config/preload.php
if (is_file($aop = dirname(__DIR__).'/var/cache/prod/aop/_preload.php')) {
require $aop;
}
if (is_file($container = dirname(__DIR__).'/var/cache/prod/App_KernelProdContainer.preload.php')) {
require $container;
}

Im Produktionsmodus schreibt der Cache-Warmer _preload.php in das Cache-Verzeichnis des Frameworks. Passen Sie den Pfad an, wenn cache_dir nicht %kernel.cache_dir%/aop ist. Booten Sie den Kernel nicht in config/preload.php: Das scheitert mit „Cannot redeclare class“. Mehr zu Produktions-Builds: Produktion & Performance.

Wenn DoctrineBundle registriert ist oder Sie doctrine: true setzen, tut das Bundle Folgendes:

  • Es ersetzt den Verzeichnis-Scan jedes ORM-Attribut-Treibers durch Go\Bridge\Doctrine\WovenEntityClassLocator, der Entities über den Class-Loader lädt, sodass sie ihre Behaviors behalten;
  • es registriert Go\Bridge\Doctrine\MetadataLoadInterceptor als loadClassMetadata-Listener, der beim Laden der Metadaten eine abgefangene Entity-Property meldet, wenn native Lazy Objects ausgeschaltet sind.

Entities müssen unterhalb eines Include-Pfads liegen, damit sie kompiliert werden. Ihre Behaviors greifen dann unabhängig davon, ob Ihr Code sie erzeugt oder das ORM sie hydriert. Die Seite Doctrine ORM erklärt beide Klassen.

  • Ein Behavior greift nicht. Führen Sie zuerst debug:advisor --advisor=... aus: Es listet, was eine Matching-Rule auswählt. Prüfen Sie dann, ob die Klasse unterhalb eines Include-Pfads liegt und nicht geladen wird, bevor das Bundle bootet (Profiler-Panel, classes loaded before weaving). Vendor-Code wird nur kompiliert, wenn sein Verzeichnis ein Include-Pfad ist.

  • „Class … is missing from the prebuilt AOP cache“. Das Deployment hat Code ausgeliefert, für den der Cache nicht gebaut wurde. Führen Sie bin/console cache:clear (oder cache:warmup) aus, nachdem der Code an Ort und Stelle ist.

  • „Circular reference detected for the aspect …“. Das Erzeugen einer Abhängigkeit der Behavior-Klasse führt ein Behavior genau dieser Klasse aus. Injizieren Sie die Abhängigkeit lazy, oder grenzen Sie die Matching-Rule ein:

    public function __construct(
    #[Autowire(lazy: true)] private readonly Wallet $wallet, // or #[AutowireServiceClosure(Wallet::class)], a service locator
    ) {}
  • „Class … was not found by locator“. Eine Klasse unterhalb der Include-Pfade erweitert Code, den Composer nicht finden kann, etwa eine generierte Basisklasse. Sorgen Sie dafür, dass Composer ihn findet, aktivieren Sie PARTIAL_REFLECTION, oder schließen Sie die abhängigen Klassen mit exclude_paths aus.

  • Exception-Handler. Schließen Sie Klassen, die geladen werden müssen, wenn alles andere fehlgeschlagen ist (Error-Handler, der Kernel), über exclude_paths aus.

© 2026 Alexander Lisachenko