Skip to content
Documentation · Integrations

Symfony

Symfony integration with goaop/goaop-symfony-bundle 4.0: autoconfigured behavior classes, a web profiler panel and cache warm-up.

The bundle goaop/goaop-symfony-bundle 4.0 attaches behaviors to your services as they are loaded. You don’t need base classes or decorators.

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

That is the whole integration. The class implements Go\Aop\Aspect, so autoconfiguration registers it as a behavior class, and autowiring gives it its logger. From the next request on, every public method of every class below App\Service is timed.

  • PHP 8.4 or newer
  • Symfony 7.4 or 8.x
  • goaop/framework ^4.0 (behaviors declared with attributes)
Terminal window
composer require goaop/goaop-symfony-bundle

Register the bundle as the first entry of config/bundles.php:

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

The compile step only applies to classes loaded after the kernel is initialized, and bundles boot in registration order. The bundle enforces this: if it is not first, the container build fails with a clear message.

The configuration file is optional. With the defaults below, the bundle compiles the src/ directory in the mode of the kernel and enables the prebuilt cache in production:

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 prints the full reference. All options, with their defaults:

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: ~

Environment variables work as everywhere in Symfony, for example debug: '%env(bool:GOAOP_DEBUG)%'. Function and initialization() matching rules need no feature flag: they enable their machinery themselves.

A behavior class is an ordinary autowired service. Autoconfiguration registers every service that implements Go\Aop\Aspect. Without autoconfiguration, tag the service with goaop.aspect:

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

A behavior class is a singleton: registering it as two services is a container compile error.

The compiler only needs the behavior classes. The Symfony container creates a behavior class when one of its behaviors runs for the first time, never during the compile step or cache warm-up. The kernel’s container (AspectContainer) also delegates to the Symfony container, so $aspectContainer->get(LoggerInterface::class) works. Go\Core\AspectKernel and Go\Core\AspectContainer are autowirable services, and goaop.aspect_kernel is public.

Check what a behavior class matches before you rely on it:

Terminal window
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

In debug mode, classes below the include paths are compiled on first load, and compiled again when their source or a behavior class changes.

With symfony/web-profiler-bundle installed, the toolbar shows the number of behavior classes. The Go! AOP panel lists:

  • the behavior classes with their advisors, behavior attributes and matching rules;
  • the compiled classes loaded during the request, with their proxy files;
  • the classes below the include paths that were loaded before the kernel was initialized (the panel turns yellow);
  • the effective configuration of the kernel.

The third list is the diagnostic for a bundle that boots before GoAopBundle, and for the one request that rebuilt the container. That request has to load the service classes before the bundle boots, so it runs them once without their behaviors. The next request runs fully compiled. Deployments are not affected, because cache:clear and cache:warmup build the container and the framework’s cache together.

The bundle also turns off Symfony’s .container.dumper.inline_class_loader unless your configuration sets it. That option includes service files directly, which bypasses the class loader and therefore the compile step.

Terminal window
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 and cache:warmup compile the whole application through a cache warmer. cache:clear builds the new cache next to the running one and renames it afterwards. The warmer builds the framework’s cache in that new directory, from scratch, so your usual deployment steps need no change. The warm-up fails when a file cannot be compiled, so a deployment stops instead of shipping an incomplete cache. Run cache:warmup:aop --fail-fast -vvv to see the file and the error.

The framework commands are registered in the console of your application. They work on the running kernel, so you leave out the loader argument of vendor/bin/aspect.

Command Purpose
cache:warmup:aop [--fail-fast] [--cache-dir=DIR] [--cached-files=N] [--preload[=FILE]] Compiles every file below the include paths into the cache. Fails when a file cannot be compiled. --preload also writes the opcache.preload script of the cache.
cache:warmup:opcache [--file-cache=DIR] [--entry=FILE] Primes the opcache file cache (opcache.file_cache) with the framework’s cache and the application. Run it in the final image.
debug:aspect [--aspect=FQCN] Lists the behavior classes with their matching rules and advisors.
debug:advisor [--advisor=ID] Lists the advisors; with --advisor, what that advisor matches.
debug:weaving [-v] Compiles the application twice and reports proxies that differ, which points to a non-deterministic behavior class.

cache:warmup:aop --workers=N compiles in one process here: its worker processes would boot the kernel with a loader file, and the console of the application has none.

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

With PREBUILT_CACHE, the runtime skips every cache-related file system check and never compiles or writes to the cache directory. A class below the include paths that the cache does not know fails with a WeavingException (“… is missing from the prebuilt AOP cache …”). Rebuild the cache on every deployment. This is the recommended production setting, and it makes read-only file systems and immutable images work.

If your kernel.build_dir differs from kernel.cache_dir, anchor the framework’s cache on the directory you build at deploy time: cache_dir: '%kernel.build_dir%/aop'.

For opcache preloading, require the preload script of the framework’s cache before the preload file of the container:

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

In production mode the cache warmer writes _preload.php into the framework’s cache directory. Adapt its path when cache_dir is not %kernel.cache_dir%/aop. Do not boot the kernel in config/preload.php: that fails with “Cannot redeclare class”. More on production builds: Production.

When DoctrineBundle is registered, or when you set doctrine: true, the bundle:

  • replaces the directory scan of every ORM attribute driver with Go\Bridge\Doctrine\WovenEntityClassLocator, which loads entities through the class loader, so they keep their behaviors;
  • registers Go\Bridge\Doctrine\MetadataLoadInterceptor as a loadClassMetadata listener, which reports an intercepted entity property when native lazy objects are off, at metadata load time.

Entities must lie below an include path to be compiled. Their behaviors then apply whether your code creates them or the ORM hydrates them. The Doctrine ORM page explains both classes.

  • A behavior does not apply. Run debug:advisor --advisor=... first: it lists what a matching rule selects. Then check that the class lies below an include path and is not loaded before the bundle boots (profiler panel, classes loaded before weaving). Vendor code is only compiled when its directory is an include path.

  • “Class … is missing from the prebuilt AOP cache”. The deployment shipped code that the cache was not built for. Run bin/console cache:clear (or cache:warmup) after the code is in place.

  • “Circular reference detected for the aspect …”. Creating one of the behavior class’s dependencies runs a behavior of that same class. Inject the dependency lazily, or narrow the matching rule:

    public function __construct(
    #[Autowire(lazy: true)] private readonly Wallet $wallet, // or #[AutowireServiceClosure(Wallet::class)], a service locator
    ) {}
  • “Class … was not found by locator”. A class below the include paths extends code that Composer can’t locate, such as a generated base class. Let Composer locate it, enable PARTIAL_REFLECTION, or exclude the dependent classes with exclude_paths.

  • Exception handlers. Exclude classes that must load when everything else has failed (error handlers, the kernel) through exclude_paths.

© 2026 Alexander Lisachenko