Configuration & CLI
Configure the kernel, choose feature flags, give behavior classes their dependencies from your application container and run the console.
Everything the framework needs to know about your application goes through one call: init() on your kernel. This page lists every option the kernel accepts, the feature flags, how behavior classes get their dependencies from your application container, and the vendor/bin/aspect console you use to build and inspect the cache.
The kernel
Section titled “The kernel”Your kernel extends Go\Core\AspectKernel and registers behavior classes (aspects, in the API; see the terms table) in configureAop():
use Aspect\MonitorAspect;use Go\Core\AspectContainer;use Go\Core\AspectKernel;
class ApplicationAspectKernel extends AspectKernel{ protected function configureAop(AspectContainer $container): void { // Deferred (recommended): constructed on first use $container->addLazyService(MonitorAspect::class, static fn() => new MonitorAspect());
// Eager alternative: $container->add(MonitorAspect::class, new MonitorAspect()); }}You initialize it once, usually in the front controller, right after the Composer autoloader:
include __DIR__ . '/../vendor/autoload.php';
ApplicationAspectKernel::getInstance()->init([ 'debug' => false, 'appDir' => __DIR__ . '/..', 'cacheDir' => __DIR__ . '/../var/cache/aop', 'includePaths' => [__DIR__ . '/../src'],]);Kernel options
Section titled “Kernel options”Only the options below are accepted. An unknown key, an unknown containerClass or an unknown feature bit throws Go\Aop\Exception\InvalidConfigurationException, so a typo fails at boot instead of being ignored.
| Option | Type | Default | Purpose |
|---|---|---|---|
cacheDir |
string |
none, required | Directory for compiled sources, proxies, advisor caches and the class map. |
appDir |
string |
the directory that contains vendor/ |
Application root. Cache paths mirror source paths relative to it, and only files below it are compiled. |
debug |
bool |
false |
Development mode: changes of the kernel file and of behavior class files invalidate the cache, and every class and include is loaded through the framework’s compiling stream filter. With false, compiled classes are loaded from the cache through Composer’s class map. Use false in production. |
includePaths |
string[] |
[] (everything below appDir) |
Directories that are compiled. Keep it narrow: compiling vendor code is slow and rarely needed. |
excludePaths |
string[] |
[] |
Directories that are never compiled. The cache directory, the framework itself and its runtime dependencies (goaop/dissect, goaop/parser-reflection, nikic/php-parser, psr/container, symfony/finder) are always excluded. |
features |
int |
0 |
Bitmask of Go\Aop\Features flags, see the next section. |
cacheFileMode |
int |
0770 minus the umask |
Permissions of cache files. Must be between 0600 and 0777 and give the owner read and write access; directories get matching search bits. |
containerClass |
class-string |
Go\Core\Container |
Implementation of the kernel’s container. Must implement Go\Core\AspectContainer (a PSR-11 ContainerInterface). |
parsedFilesLimit |
int |
100 |
Number of parsed source files (syntax trees, about 0.2 MB each) goaop/parser-reflection keeps in memory while compiling. Must be a positive integer: more re-parses less, fewer uses less memory. It replaces a limit set with ReflectionEngine::setMaximumCachedFiles() before init(), and it is the default of cache:warmup:aop --cached-files. |
Feature flags
Section titled “Feature flags”Feature flags are constants of the final class Go\Aop\Features. Combine them with |:
use Go\Aop\Features;
ApplicationAspectKernel::getInstance()->init([ 'debug' => false, 'appDir' => __DIR__ . '/..', 'cacheDir' => __DIR__ . '/../var/cache/aop', 'includePaths' => [__DIR__ . '/../src'], 'features' => Features::INTERCEPT_INCLUDES | Features::PREBUILT_CACHE,]);Features::ALL combines every flag. AspectKernel::hasFeature() tells you whether a flag is set and throws on an unknown one.
| Flag | Use it when |
|---|---|
INTERCEPT_INCLUDES |
Your application loads code with include/require instead of Composer. |
PREBUILT_CACHE |
You build the cache at deploy time and want requests to trust it completely. The production setting. |
PARTIAL_REFLECTION |
A class you want to compile extends or implements something the framework can not locate. |
INTERCEPT_INCLUDES
Section titled “INTERCEPT_INCLUDES”Routes include and require in compiled files through the compiler. Use it for legacy code that is not loaded by Composer.
PREBUILT_CACHE
Section titled “PREBUILT_CACHE”Trusts the cache built at deploy time completely. The kernel skips the cache directory and writability probes, source filemtime comparisons, tracked-resource checks and advisor cache freshness checks. A request never compiles and never writes to the cache directory, so it works on read-only file systems.
The flip side: the cache must be complete. Files the compiler never takes (outside the include paths, excluded, not .php, for example an included template) are loaded as they are. Everything else below the include paths must have a record in the cache.
cache:warmup:aop itself does not trust the cache it builds. Run over an existing directory, it compiles again every file whose source changed (size or modification time). Its loader file may load classes the cache does not know yet before the build starts: they are loaded uncompiled there and compiled by the build.
PARTIAL_REFLECTION
Section titled “PARTIAL_REFLECTION”Compiles a class whose parent class, interface or trait can not be located: one declared by code generated at runtime, by a class_alias() or in a file outside the Composer autoloader. The class is matched and compiled with its own methods and properties and those of its available ancestors. Members inherited from a missing ancestor are not intercepted.
Without the flag such a class fails to compile. Turn it on when you hit that failure.
Function and initialization rules need no flag
Section titled “Function and initialization rules need no flag”The framework enables the machinery for these matching rules from the registered behavior classes, lazily registered ones included. You don’t set anything in features:
- An
execution(Namespace\function(*))rule adds function proxies to the matching namespaces. - An
initialization(...)rule turns on the rewriting ofnew Foo(...)expressions in compiled files. While one is registered, every rewrittennewgoes through the interceptor, so keep such rules to the code that needs them.
The syntax of matching rules is on Behaviors & Matching Rules.
Behavior classes from the application container
Section titled “Behavior classes from the application container”The kernel’s container is a PSR-11 container (Go\Core\AspectContainer extends Psr\Container\ContainerInterface). It can delegate to the container of your application: Symfony, Laravel, PHP-DI or any other PSR-11 container. get(), getService() and has() fall back to the delegate for ids that are not registered in the kernel’s container.
The kernel is initialized before the application builds its container. So you register behavior classes as usual and let them resolve their dependencies lazily:
protected function configureAop(AspectContainer $container): void{ // Runs when one of its behaviors first runs, after the application container is attached $container->addLazyService( MonitorAspect::class, static fn(AspectContainer $container) => new MonitorAspect($container->getService(LoggerInterface::class)), ); // or take the whole behavior class from the application container, by the id it has there // $container->addLazyService(MonitorAspect::class, static fn(AspectContainer $c) => $c->get('app.monitor_aspect'));}Once the application container exists, for example right after your framework’s kernel has booted, attach it:
ApplicationAspectKernel::getInstance()->getContainer()->setDelegate($psrContainer);The compile step and the cache warm-up only need the behavior class itself. They run before setDelegate(), even in vendor/bin/aspect, and never create an instance of it. The factory runs when one of its behaviors first runs; a dependency that is still missing then throws ServiceNotFoundException.
The Symfony, Laravel and Yii 3 bridges are covered on Integrations.
Rules for behavior class factories
Section titled “Rules for behavior class factories”- A factory never asks the kernel’s container for its own id. That id resolves to the behavior class being built. Take the instance from the application container by the id it has there, or build it from its dependencies.
- Behavior classes are never discovered in the delegate. A PSR-11 container can not be introspected: there is no standard way to look services up by interface or by tag. Every behavior class is registered in
configureAop(). A bridge for a specific framework can collect services by tag or interface from its own container and register them withaddLazyService(). - The compile step never creates a behavior class instance. It reads the behavior class, and the generated code refers to each behavior by class and method name. Every behavior class, also one without instance properties (which PHP can not make lazy), is created by its factory when one of its behaviors first runs, once the application container is attached.
- Creating a behavior class must not run one of its own behaviors. If the behavior class depends on a service whose construction one of its behaviors intercepts (the service’s constructor, or a method the constructor calls), that behavior would run on an instance that does not exist yet. The interceptor reports this with an
AspectCircularReferenceExceptionnaming the behavior class, the intercepted call and the calls from the creation to the behavior. Inject the dependency lazily (a lazy service, a closure or a service locator), or narrow the matching rule so that the behavior class does not intercept the creation of its own dependencies.
Custom container class
Section titled “Custom container class”To replace the kernel’s container, pass your class as containerClass. It must implement Go\Core\AspectContainer, which means the PSR-11 get() and has(), plus setDelegate(). An unknown id throws ServiceNotFoundException, which implements Psr\Container\NotFoundExceptionInterface.
Development and production mode
Section titled “Development and production mode”The debug option switches between two modes. Your behavior classes and matching rules are the same in both.
'debug' => true |
'debug' => false |
|
|---|---|---|
| Class loading | Every class and include goes through the compiling stream filter. |
Compiled classes come from the cache through Composer’s class map. |
| Changed source, behavior class or kernel file | Compiled again on the next request. | The cache is served as it is. |
| Cache rebuild | Not needed. | On every deploy, with cache:warmup:aop. |
| Use for | Local development. | Production. Add Features::PREBUILT_CACHE. |
In development there is no build step: edit a class or a behavior, reload, and the framework recompiles what changed. Breakpoints work in your original code.
In production, the framework hands the class map of the cache to Composer, and the parser and transformers are not loaded on warm requests. With PREBUILT_CACHE on top, a request also skips every source file and cache freshness check. How to tune this further (OPcache, preloading, containers) is on Production & performance.
The cache directory
Section titled “The cache directory”cacheDir is the only required option. The directory holds:
- the compiled sources: each original class body as a
<Class>OriginalTraittrait, at the relative path of its source file; - the proxies, next to the compiled sources, under the original class name;
- the advisor caches of your behavior classes, as plain PHP files next to the compiled sources;
- the metadata, including
_include.cache, the class map handed to Composer; _preload.php, when you build the cache withcache:warmup:aop --preload.
Things to know:
- It mirrors
appDir. Cache paths are relative to the application root, and paths inside the metadata are stored relative to__DIR__, so the cache stays valid when the application directory moves. - It is never compiled. The cache directory is always excluded, whatever you put in
excludePaths. - Permissions come from
cacheFileMode. The default is0770minus the umask. Build the cache as, or for, the user that serves requests. - Delete it when you upgrade from 3.x. No 3.x cache file is reused, and with
PREBUILT_CACHEa cache built by another framework version is rejected.
The console
Section titled “The console”vendor/bin/aspect cache:warmup:aop public/index.phpvendor/bin/aspect needs symfony/console (^7.4 || ^8.0). Install it with Composer if your application does not have it yet.
Every command takes the path to the file that initializes your kernel, usually the front controller or a bootstrap file. That file is executed, so the command sees the kernel with the same options as your application. Inside an application that has initialized its kernel already (the console of a framework integration, where the commands are registered as services), you omit the argument: the commands use the kernel of the process.
Every command returns Command::SUCCESS or Command::FAILURE. Check the exit code in scripts.
| Command | Purpose |
|---|---|
cache:warmup:aop |
Compiles every file below the include paths into the cache. |
cache:warmup:opcache |
Primes opcache.file_cache with the framework’s cache and what a request loads. |
debug:aspect |
Lists the registered behavior classes and their behaviors. |
debug:advisor |
Lists the advisors (each behavior with its matching rule), or the intercepted calls one advisor matches. |
debug:weaving |
Warms up the cache twice and reports proxies that are generated differently. |
cache:warmup:aop
Section titled “cache:warmup:aop”rm -rf var/cache/aopvendor/bin/aspect cache:warmup:aop public/index.php --workers=8The command compiles every file below includePaths (minus excludePaths) and writes the compiled files, the proxies, the advisor caches and the metadata. It shows a progress bar. It reports every file that can not be compiled on stderr and exits with a non-zero code, so a deploy script or a docker build stops there instead of shipping an incomplete cache.
| Option | Default | Purpose |
|---|---|---|
--workers=N |
1 (compiles in the command process) |
Compiles in N parallel worker processes. Use the number of CPUs. |
--cached-files=N |
the parsedFilesLimit kernel option, 100 |
Number of parsed files each process keeps in memory. |
--fail-fast |
off | Stops at the first file that can not be compiled. |
--cache-dir=DIR |
the kernel’s cacheDir |
Builds the cache in another directory, from scratch, while the kernel and the workers keep using their own. |
--preload[=FILE] |
off | Also writes the opcache.preload script of the cache: _preload.php in the cache directory, or FILE. |
-v |
off | Prints every file instead of only the progress bar. |
Notes on the options:
--cache-diris how a deployment prepares the cache of the next release next to the running one, then switches it in atomically, for example with a symlink swap. A cache built this way is complete and location independent, also when a production kernel builds it while its own cache is warm: the compiler always reads the original sources, never the compiled files that Composer serves.--preloadin its bare form must come after the loader argument, otherwise it takes the loader as its value. The script links every compiled class and every untransformed class known to the cache when PHP starts; classes with a behavior on static initialization are left to the autoloader. It holds no absolute path and lists the classes of exactly this cache, so you rebuild it with the cache. Setting up preloading is covered on Production & performance.- Over an existing directory the command compiles again every file whose source changed (size or modification time) and keeps the others, also with
PREBUILT_CACHE. Start from an empty directory when you want the cache to contain exactly the current release.
cache:warmup:opcache
Section titled “cache:warmup:opcache”vendor/bin/aspect cache:warmup:opcache public/index.php --file-cache=/var/cache/opcache --entry=public/index.phpCompiles into opcache.file_cache what a production request loads: the framework’s cache, Composer’s class map and autoloaded files, the untransformed sources, the loader and the entry points. A new PHP-FPM master or CLI process then reads compiled scripts from disk instead of compiling them.
| Option | Purpose |
|---|---|
--file-cache=DIR |
The opcache.file_cache directory. It must match the configured one. |
--entry=FILE |
An entry point to compile. Repeat it for several files. |
Compiled scripts are written to disk only by a process started with -d opcache.enable_cli=1 -d opcache.file_cache_only=1 -d opcache.file_cache=DIR. If the command runs without them, it prints the exact command to run.
The file cache belongs to the PHP build and to the absolute paths of the files. Run the command in the final image, after cache:warmup:aop, with the PHP binary that serves requests. The framework’s cache, the loader and the entry points must compile, or the command fails; files of the Composer class map that do not compile are listed and skipped.
debug:aspect
Section titled “debug:aspect”vendor/bin/aspect debug:aspect public/index.phpLists the registered behavior classes and their behaviors. It also accepts an --aspect=... option.
debug:advisor
Section titled “debug:advisor”vendor/bin/aspect debug:advisor public/index.phpLists the advisors. With --advisor=... it shows the intercepted calls that advisor matches, which tells you whether your matching rule selects the methods you expect.
debug:weaving
Section titled “debug:weaving”vendor/bin/aspect debug:weaving public/index.phpWarms up the cache twice and reports proxies that are generated differently between the two runs. A difference points to a non-deterministic behavior class.
Deployment basics
Section titled “Deployment basics”rm -rf var/cache/aopvendor/bin/aspect cache:warmup:aop public/index.php --workers=8- Clear the cache directory.
- Warm up the cache with
cache:warmup:aop. The command fails when a file can not be compiled, so the deploy stops instead of shipping an incomplete cache. Large projects compile faster in parallel with--workers. - Run with
'debug' => falseandFeatures::PREBUILT_CACHE.
use Go\Aop\Features;
ApplicationAspectKernel::getInstance()->init([ 'debug' => false, 'appDir' => __DIR__ . '/..', 'cacheDir' => __DIR__ . '/../var/cache/aop', 'includePaths' => [__DIR__ . '/../src'], 'features' => Features::PREBUILT_CACHE,]);Rebuild the cache whenever the code, the behavior classes, the kernel options or composer.lock change. In practice, that means on every deployment. Development mode needs no rebuilds.
OPcache tuning, preloading, Composer autoloader flags and building the cache into a Docker image are on Production & performance. Upgrading from 3.x, including the cache format change, is on Limitations & upgrading.
© 2026 Alexander Lisachenko
