Aspect-Oriented Programming

Last updated: 2026-10-31

Canvas has no middleware pipeline. Where other frameworks handle cross-cutting concerns — authentication, caching, rate limiting — in a centralized middleware stack, Canvas uses Aspect-Oriented Programming instead: concerns are declared directly on the methods that need them, making the relationship between a route and what applies to it explicit rather than implicit.

explanation

How It Works

When a request arrives, Canvas matches it to a controller method via @Route, then reads its @InterceptWith annotations to build an execution pipeline. Each annotation adds an aspect: a class that handles a shared concern such as authentication, caching, or rate limiting before, after, or around the controller method. The controller itself contains only business logic; the surrounding pipeline is constructed from metadata by the framework.

Aspect Types

Each aspect type gives you different control over the execution flow:

Before Aspects

Execute before the target method. Return a Response to prevent method execution, or null to continue:

<?php
namespace App\Aspects;

use Quellabs\Contracts\AOP\BeforeAspectInterface;
use Quellabs\Contracts\AOP\MethodContextInterface;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\RedirectResponse;

class RequireAuthAspect implements BeforeAspectInterface {
    public function __construct(private AuthService $auth) {}

    public function before(MethodContextInterface $context): ?Response {
        if (!$this->auth->isAuthenticated()) {
            return new RedirectResponse('/login');
        }

        return null; // Proceed to method execution
    }
}

After Aspects

Execute after the target method completes. Receive both the method context and the response for logging or modification:

<?php
namespace App\Aspects;

use Quellabs\Contracts\AOP\AfterAspectInterface;
use Quellabs\Contracts\AOP\MethodContextInterface;
use Symfony\Component\HttpFoundation\Response;

class AuditLogAspect implements AfterAspectInterface {
    public function __construct(private LoggerInterface $logger) {}

    public function after(MethodContextInterface $context, Response $result): void {
        $this->logger->info('Method executed', [
            'controller' => $context->getClassName(),
            'method' => $context->getMethodName(),
            'status' => $result->getStatusCode()
        ]);
    }
}

Around Aspects

Wrap the entire method execution. Control when and if the method executes by calling the $proceed callable:

<?php
namespace App\Aspects;

use Quellabs\Contracts\AOP\AroundAspectInterface;
use Quellabs\Contracts\AOP\MethodContextInterface;
use Symfony\Component\HttpFoundation\Response;

class CacheAspect implements AroundAspectInterface {
    public function __construct(
        private CacheInterface $cache,
        private int $ttl = 300
    ) {}

    public function around(MethodContextInterface $context, callable $proceed): mixed {
        $key = $context->getClassName() . '::' . $context->getMethodName()
            . ':' . hash('sha256', serialize($context->getArguments()));

        $cached = $this->cache->get($key);
        if ($cached instanceof Response) {
            return $cached;
        }

        $result = $proceed(); // Execute the wrapped method
        $this->cache->set($key, $result, $this->ttl);

        return $result;
    }
}

Canvas runs these aspects around HTTP controller methods. The controller method or around chain must ultimately return a Symfony Response.

Basic Usage

Method-Level Application

Apply aspects to individual methods using @InterceptWith:

class UserController extends BaseController {

    /**
     * @Route("/users")
     * @InterceptWith(RequireAuthAspect::class)
     */
    public function index(): Response {
        $users = $this->em()->findBy(User::class, ['active' => true]);
        return $this->render('users/index.tpl', compact('users'));
    }
}

Class-Level Application

Apply aspects to all methods in a controller:

/**
 * @InterceptWith(RequireAuthAspect::class)
 */
class AdminController extends BaseController {

    /**
     * @Route("/admin/users")
     */
    public function users(): Response {
        return new Response('Admin users'); // Authentication required automatically
    }
}

Annotation Inheritance

Child controllers automatically inherit all class-level annotations from parent controllers. This enables controller hierarchies with shared cross-cutting concerns.

/**
 * @InterceptWith(RequireAuthAspect::class)
 * @InterceptWith(AuditLogAspect::class)
 */
abstract class AuthenticatedController extends BaseController {}

class UserController extends AuthenticatedController {

    /**
     * @Route("/users")
     * @InterceptWith(CacheAspect::class, ttl=300)
     */
    public function index() {
        // Execution order: RequireAuth → AuditLog (inherited from AuthenticatedController) → Cache (method-level)
    }
}

Preventing Aspects from Stacking

By default, a class-level and a method-level declaration of the same aspect both run, as in the example above. That suits layered concerns like caching, but not a security header policy or auth mode, where two configurations shouldn't both apply. Implement the marker interface NonStackableAspectInterface on an aspect class to make the most specific declaration replace an inherited one instead of joining it.

Aspect Parameters

Configure aspects through annotation parameters, which map to constructor parameters:

/**
 * @Route("/heavy-operation")
 * @InterceptWith(CacheAspect::class, ttl=3600)
 * @InterceptWith(RateLimitAspect::class, limit=10, window=60)
 */
public function heavyOperation() {
    // Cached for 1 hour, rate limited to 10 requests per minute
}

Parameters become constructor arguments alongside any dependencies resolved by the DI container. DI-resolved dependencies (like CacheInterface) come first; annotation parameters fill the remaining arguments by name:

class CacheAspect implements AroundAspectInterface {
    public function __construct(
        private CacheInterface $cache,
        private int $ttl = 300,
        private array $tags = []
    ) {}
}

Aspect Priority

Control execution order when multiple aspects apply to the same inheritance level using the priority parameter. Higher priority values execute first (default is 0):

class UserController extends BaseController {
    /**
     * @Route("/profile/update")
     * @InterceptWith(AuthAspect::class, priority=100)         // Runs first
     * @InterceptWith(PermissionAspect::class, priority=90)    // Runs second
     * @InterceptWith(ValidationAspect::class, priority=50)    // Runs third
     */
    public function updateProfile() {
        // Order ensures authentication → permission checks → validation
    }
}

The priority parameter is not passed to the aspect constructor - it only affects execution order.

Execution Order

When multiple aspects are present, the dispatcher executes four lifecycle phases in sequence: Request → Before → Around → After. Aspects are collected from the full controller inheritance chain. Execution order is determined first by controller inheritance level, then by aspect priority within each level.

Inheritance Order

Aspects are collected from the controller hierarchy in this order:

  1. Grandparent class — aspects sorted by priority
  2. Parent class — aspects sorted by priority
  3. Current class — aspects sorted by priority
  4. Method — aspects sorted by priority

Lifecycle Execution Rules

Within each inheritance level, aspects are sorted by the priority parameter. Higher priority values execute first (default is 0).

  • Request aspects execute in collection order.
  • Before aspects execute in collection order (highest priority first). An aspect that runs first on the way in has the broadest scope — it wraps everything that follows.
  • Around aspects The highest-priority aspect wraps all lower-priority aspects, so its code runs first before the controller and last after it returns. Execution unwinds outward after the controller completes.
  • After aspects execute in reverse collection order. Because each aspect effectively wraps everything that runs after it, the outermost aspect (highest priority) must also be the last to finish — mirroring how a call stack unwinds. This guarantees that an aspect's after-logic runs within the scope it opened on the way in.

The MethodContext Object

Every aspect receives a MethodContextInterface object that provides access to the intercepted method call. This is the Canvas extension of the base interface used by the DI container — it adds request and controller access on top of the resolution context available to service providers.

The aspect contracts and their MethodContextInterface live in Quellabs\Contracts\AOP.

Available Methods

  • getClass(): object — Returns the controller instance
  • getClassName(): string — Returns the fully qualified class name
  • getMethodName(): string — Returns the method name being called
  • getArguments(): array — Returns method arguments (including route parameters)
  • getRequest(): Request — Returns the Symfony Request object
  • setRequest(Request $request): void — Replaces the request object

Common Usage in Aspects

Route parameters are accessed via getArguments():

// @Route("/users/{userId}/orders/{orderId}")
// public function showOrder($userId, $orderId) { ... }

public function before(MethodContextInterface $context): ?Response {
    [$userId, $orderId] = $context->getArguments();
    // ...
}

Request data is accessed via getRequest():

public function before(MethodContextInterface $context): ?Response {
    $request = $context->getRequest();
    $ip = $request->getClientIp();
    $apiKey = $request->headers->get('X-Api-Key');
    $data = $request->request->all();
    // ...
}

For injecting context into services and using it outside of aspects, see The MethodContext Object section on the Containers page.

Frequently Asked Questions

What's the difference between before, after, and around aspects?

A before aspect runs ahead of the method and can return a Response to stop it from executing at all. An after aspect runs once the method has already produced a response, useful for logging or modification. An around aspect wraps the entire call — it decides whether and when to invoke the method via a $proceed callable, so it can skip execution entirely, run code on both sides of it, or alter the result.

How do I control the order aspects run in when several apply to the same route?

With the priority parameter on @InterceptWith — higher values run first. Execution order is decided first by controller inheritance level (grandparent → parent → current class → method), then by priority within each level. The highest-priority around aspect wraps every lower-priority one, and after-aspects unwind in reverse, mirroring a call stack.

Can I apply the same aspect at both the class and method level without it running twice?

By default both declarations run — useful for layered concerns like caching, where that's the point. For aspects where two configurations shouldn't both apply (a security header policy, an auth mode), implement the marker interface NonStackableAspectInterface on the aspect class so the most specific declaration replaces the inherited one instead of joining it.

Do class-level aspects get inherited by child controllers?

Yes. Child controllers automatically inherit every class-level @InterceptWith annotation from their parent controllers, which is how a shared concern like authentication or audit logging gets applied once on a base controller rather than repeated on every subclass.

How do aspect parameters interact with constructor dependencies?

DI-resolved dependencies come first, and annotation parameters fill the remaining constructor arguments by name. So a CacheAspect constructor taking CacheInterface $cache, int $ttl = 300 gets $cache from the container and $ttl from whatever value the route's @InterceptWith(CacheAspect::class, ttl=3600) specifies.

How do I access the current request or route parameters from inside an aspect?

Through the MethodContextInterface object every aspect receives: getRequest() returns the Symfony Request, and getArguments() returns the method's arguments, including route parameters, in declaration order.