Skip to content
Documentation

Getting Started

Install the framework with Composer, create a kernel, write your first behavior and watch it run around your code.

You write a behavior such as logging, caching, a security check or a transaction once, and the framework attaches it as dynamic middleware to every method you select. In code, behaviors live in a behavior class (an aspect, in the API): each behavior is a method whose attribute says when it runs and holds a matching rule that says where. Your classes keep only their business logic. The terms table maps the API names to the words these docs use.

  • PHP 8.4 or newer. Works on all modern versions of PHP.
  • No PECL or PIE extension. It is pure PHP: no php-aop, runkit or uopz, and no eval(). It uses the tokenizer extension.
  • Composer. The framework and its dependencies install as regular Composer packages.

Getting started takes five steps:

  1. Install the framework with Composer.
  2. Create the application kernel.
  3. Initialize the kernel in the front controller.
  4. Write a behavior class.
  5. Register the behavior class in the kernel.
Terminal window
composer require goaop/framework

Composer installs the framework into vendor/goaop/framework.

The samples on this page use this layout. They assume that Composer autoloads the classes in app/ and src/, for example through the autoload section of your composer.json.

app/ApplicationAspectKernel.php the kernel
public/index.php the front controller
src/ your application code, compiled by the framework
src/Aspect/MonitorAspect.php your first behavior class
var/cache/aop/ the cache of generated code
app/ApplicationAspectKernel.php
<?php
use Go\Core\AspectContainer;
use Go\Core\AspectKernel;
/**
* The application kernel
*/
class ApplicationAspectKernel extends AspectKernel
{
/**
* Register the behavior classes in the container
*/
protected function configureAop(AspectContainer $container): void
{
}
}

The kernel manages all behavior classes of your application in one place. Extend the abstract class Go\Core\AspectKernel and implement configureAop(). It stays empty for now; you register your first behavior class in it below.

Initialize the kernel in the front controller

Section titled “Initialize the kernel in the front controller”
public/index.php
<?php
include __DIR__ . '/../vendor/autoload.php'; // use composer
// Initialize the kernel
$applicationAspectKernel = ApplicationAspectKernel::getInstance();
$applicationAspectKernel->init([
'debug' => true, // use 'false' for production mode
'appDir' => __DIR__ . '/..', // Application root directory
'cacheDir' => __DIR__ . '/../var/cache/aop', // Cache directory
// Directories whose classes get behaviors; empty means all source files
'includePaths' => [
__DIR__ . '/../src/'
]
]);
// Your application starts here

Call init() once, right after the Composer autoloader and before your application loads its own classes. These four options are enough to start:

Option Purpose
debug true turns on development mode. Use false in production.
appDir The application root. Only files below it are compiled. It defaults to the directory that contains vendor/.
cacheDir Where the generated code is written. This option is required.
includePaths The directories to compile. An empty array means everything below appDir.

Keep includePaths narrow. Compiling vendor code is slow and rarely needed. An unknown option key throws Go\Aop\Exception\InvalidConfigurationException, so a typo fails at once instead of being ignored. The full option list is on the Configuration page.

src/Aspect/MonitorAspect.php
<?php
namespace Aspect;
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Before;
/**
* A monitoring behavior class
*/
class MonitorAspect implements Aspect
{
/**
* Method that will be called before real method
*/
#[Before("execution(public Example->*(*))")]
public function beforeMethodExecution(MethodInvocation $invocation): void
{
echo 'Calling Before Interceptor for: ',
$invocation,
' with arguments: ',
json_encode($invocation->getArguments()),
"<br>\n";
}
}

A behavior class is a plain PHP class that implements Go\Aop\Aspect. Each behavior is a public method with one attribute from Go\Lang\Attribute that says when it runs.

  • A #[Before] behavior runs before the intercepted call. The other attributes are #[After], #[AfterThrowing] and #[Around].
  • The string in the attribute is the matching rule. execution(public Example->*(*)) selects the execution of every public, non-static method of the class Example.
  • The behavior receives a MethodInvocation. It gives you the intercepted call: getArguments() returns its arguments, and the invocation converts to a string that names the method.

Behavior methods must be public. The framework calls them directly on the behavior class instance, so a protected or private behavior method is rejected when the class loads. A method carries at most one behavior attribute.

app/ApplicationAspectKernel.php
<?php
use Aspect\MonitorAspect;
use Go\Core\AspectContainer;
use Go\Core\AspectKernel;
class ApplicationAspectKernel extends AspectKernel
{
/**
* Register the behavior classes in the container
*/
protected function configureAop(AspectContainer $container): void
{
// Deferred (recommended): constructed on first use
$container->addLazyService(MonitorAspect::class, static fn() => new MonitorAspect());
}
}

A behavior class is a service of the kernel’s container. addLazyService() registers a factory. The compile step only reads the behavior class, so the factory runs when one of its behaviors first runs, not before.

If you prefer to create the behavior class up front, register an instance instead:

$container->add(MonitorAspect::class, new MonitorAspect());

Behavior classes can also take their dependencies from your application’s PSR-11 container, which you attach to the kernel’s container with setDelegate(). The Configuration page shows how.

Add a class for the matching rule to select:

src/Example.php
<?php
class Example
{
public function greet(string $name): string
{
return "Hello, {$name}";
}
}

Then use it in the front controller, after init():

public/index.php
<?php
include __DIR__ . '/../vendor/autoload.php';
ApplicationAspectKernel::getInstance()->init([/* … as above … */]);
$example = new Example();
echo $example->greet('World');

Open the page in your browser, or run php public/index.php. Before Hello, World you see the line from the behavior, with the method name and its arguments ["World"]. Example has no reference to the behavior class. The behavior was attached to the class when the autoloader loaded and compiled it.

You never call the behavior yourself. To change which methods it runs for, you change the matching rule, not the classes. The Behaviors & Matching Rules page explains when each behavior runs and the full syntax of matching rules.

The bin/aspect console needs symfony/console:

Terminal window
composer require symfony/console
vendor/bin/aspect debug:aspect public/index.php

debug:aspect lists the registered behavior classes and their behaviors. Every bin/aspect command takes the path to the file that initializes your kernel, here the front controller, and executes that file. debug:advisor --advisor=... shows the intercepted calls one advisor (a behavior with its matching rule) matches. Use these commands when a behavior does not run.

Your classes are compiled when PHP loads them. Nothing wraps your objects at runtime, and no code is generated with eval(). Every compiled class is a plain PHP file in the cache directory, and that file is what PHP executes.

For a compiled class, the original class body moves into a trait. A generated class with the original class name uses that trait, so the class name, its parents and self:: stay as they were. Every intercepted method gets a call context with its behaviors:

static $__joinPoint = InterceptorInjector::forMethod(
self::class,
'doSomething',
[
Interceptor::before(The::aspect(MonitorAspect::class)->beforeMethodExecution(...)),
],
$this->doSomethingOriginalAlias(...),
);

The::aspect() fetches the behavior class instance from the kernel’s container. ->beforeMethodExecution(...) is the behavior method you wrote, referenced with first-class callable syntax. You can Ctrl-click it in your IDE, set a breakpoint inside it and step through the generated code. The last argument points to the original method body.

Line numbers are kept, so Xdebug breakpoints in your original code still work. Attributes of the class, its methods, parameters, constants and properties are copied to the generated code, so reading them with reflection works as before. Methods that no matching rule selects run without any interception code.

cacheDir holds the compiled sources, the proxies, the advisor caches and the class map. Cache paths mirror the source paths relative to appDir. The files are plain PHP, so you can open them, diff them and scan them with your security tools.

Don’t commit the cache directory. In development, the framework fills it as classes are loaded. In production, you build it at deploy time.

With 'debug' => true, every class and every include is loaded through the framework’s stream filter, which compiles it. Changes to the kernel file and to behavior class files invalidate the cache, and changed files are compiled again on the next request. There is no build step: edit a class or a behavior and reload the page.

Development mode is noticeably slower than production mode on hot requests. Don’t use it in production.

With 'debug' => false, compiled classes are loaded from the cache through Composer’s class map. The parser and the transformers are not loaded on warm requests.

For deployment, build the cache once and tell the kernel to trust it:

  1. Clear the cache directory.

  2. Warm up the cache:

    Terminal window
    vendor/bin/aspect cache:warmup:aop public/index.php

    The command fails when a file cannot be compiled, so a deploy script stops instead of shipping an incomplete cache. Large projects compile faster in parallel, for example with --workers=8.

  3. Run with 'debug' => false and the PREBUILT_CACHE feature:

    public/index.php
    use Go\Aop\Features;
    ApplicationAspectKernel::getInstance()->init([
    'debug' => false,
    'appDir' => __DIR__ . '/..',
    'cacheDir' => __DIR__ . '/../var/cache/aop',
    'includePaths' => [__DIR__ . '/../src'],
    'features' => Features::PREBUILT_CACHE,
    ]);

With PREBUILT_CACHE, a request never compiles and never writes to the cache directory, so it also works on a read-only file system. The cache must be complete: a class below the include paths that the cache has no record of fails the request with a WeavingException. Rebuild the cache whenever the code or the behavior classes change.

The Production page covers OPcache, preloading, Docker and Kubernetes.

If your application runs on Symfony, Laravel or Yii3, install the bridge for it instead of writing the front controller code yourself. The bridge boots the framework early in the application lifecycle and lets you register behavior classes as services of your framework’s container. See the Integrations page, or the repositories goaop/goaop-symfony-bundle, goaop/goaop-laravel-bridge and goaop/goaop-yii3-bridge.

Upgrading an application from version 3.x? Read the Limitations and Upgrading page first. It lists every change.

The framework repository is a plugin marketplace for coding agents. Its goaop plugin holds an Agent Skill that teaches an agent to write behavior classes, behaviors and matching rules, to integrate the framework, to deploy the cache and to find out why a behavior does not run. In Claude Code:

/plugin marketplace add goaop/framework
/plugin install goaop@goaop

© 2026 Alexander Lisachenko