Routing

Last updated: 2026-10-17

Canvas uses annotation-based routing. Routes are defined directly in controller methods using the @Route annotation, eliminating the need for separate route configuration files.

explanation

Request Lifecycle

When a request arrives, Canvas checks its own routes first. If a match is found, any @InterceptWith aspects run before and around the controller method. The controller executes and returns a response, after which After aspects run. If no Canvas route matches, the request falls through to the Legacy Bridge. If an exception is thrown at any point, the error handling system takes over.

Canvas request lifecycle diagram

Route Discovery

Canvas automatically discovers routes by scanning your src/Controllers directory for classes with @Route annotations. The discovered routes are compiled and cached for performance.

Controller Structure

Routes must be defined in controller classes:

<?php
namespace App\Controllers;

use Quellabs\Canvas\Annotations\Route;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

class UserController {

    /**
     * @Route("/api/users")
     */
    public function index(): Response {
        return new Response('User list');
    }
}

HTTP Methods

Routes default to GET requests when no methods parameter is specified. Use the methods parameter to support additional HTTP methods:

/**
 * @Route("/api/users")
 */
public function index(): Response {
    // Only accepts GET requests (default)
}

/**
 * @Route("/api/users", methods={"POST"})
 */
public function create(): Response {
    // Only accepts POST requests
}

/**
 * @Route("/api/users", methods={"GET", "POST"})
 */
public function manage(): Response {
    // Accepts both GET and POST
}

Requesting a path with a method it doesn't declare isn't the same as requesting a path that doesn't exist. If no route's path matches the request at all, Canvas returns a plain 404 Not Found. If a route's path matches but not for the request's method, Canvas returns 405 Method Not Allowed instead, with an Allow header listing the methods that path actually supports — so a POST to a GET-only /api/users gets a 405 with Allow: GET, not a misleading 404.

HEAD and OPTIONS ride along on top of this without needing their own route. A HEAD request is matched against the same route as the equivalent GET request; the controller runs exactly as it would for GET, and Canvas strips the response body afterward, so the handler never needs to know it was a HEAD request. An OPTIONS request to any matched path gets an automatic 200 response with an Allow header, unless the controller defines its own OPTIONS route.

When the Legacy Bridge is enabled, it stays in the loop here too. A 405 is treated the same as a 404: legacy gets first refusal, and Canvas only falls back to its own 405 (or synthesizes the automatic OPTIONS response) once legacy has no matching file either.

Route Parameters

Capture URL segments as method parameters. Parameters are injected by name - the parameter name in your method must match the placeholder name in the route:

/**
 * @Route("/users/{id}/posts/{postId}")
 */
public function userPost(string $id, string $postId): Response {
    // URL: /users/123/posts/456
    // $id = "123", $postId = "456"
    // Parameter names must match route placeholders
}

Route Parameter Validation

Validate route parameters with type constraints. Routes with parameters that fail validation will not match, allowing the router to continue searching for other matching routes:

/**
 * @Route("/users/{id:int}")
 */
public function show(int $id): Response {
    // Matches: /users/123
    // Doesn't match: /users/abc (fails int validation, router continues)
}

Available Validation Patterns

  • {x:int} - Integer values only (digits)
  • {x:alpha} - Alphabetic characters only (a-z, A-Z)
  • {x:alnum} - Alphanumeric characters only (a-z, A-Z, 0-9)
  • {x:slug} - URL-friendly slugs (letters, digits, hyphens)
  • {x:uuid} - UUID format (8-4-4-4-12 lowercase hex digits)
  • {x:email} - Valid email address format

Accessing Request Data

Inject Symfony's Request as a controller method parameter to read query strings, POST body, headers, cookies, and session data. See Request & Response for the full reference.