Mastering Annotation Routing in Webman: A Complete Guide

Annotation Routing

Since version v2.2.0, the Webman framework supports defining routes directly on controller methods using PHP attributes (annotations), eliminating the need to edit config/route.php.

Note: This feature requires webman-framework >= v2.2.0 .

Basic Usage

namespace app\controller;
use support\annotation\route\DisableDefaultRoute;
use support\annotation\route\Get;
use support\annotation\route\Post;
use support\annotation\route\Route;

#[DisableDefaultRoute]
class UserController {
    #[Get('/user/{id}')]
    public function show($id) {
        return "user $id";
    }

    #[Post('/user')]
    public function store() {
        return 'created';
    }

    #[Route('/user/form', ['GET', 'POST'], 'user.form')]
    public function form() {
        return 'form';
    }
}

Available route annotations include #[Get], #[Post], #[Put], #[Delete], #[Patch], #[Head], #[Options], and #[Any]. The path must start with /; an optional second parameter can specify a route name for URL generation via route(). #[DisableDefaultRoute] disables the default controller route, allowing only the annotated routes to be accessed.

Full #[Route] Syntax

#[Route(path, methods, name)]

where: path: route path starting with /; null limits methods without creating a new route. methods: HTTP method(s) as a string or array, e.g., 'GET' or ['GET','POST']. name: optional route name used by route('name') to generate URLs.

No‑Parameter Annotations: Limiting Default Routes

When the annotation omits a path, it only restricts the allowed HTTP methods while keeping the default route path.

#[Post]
public function create() { /* ... */ } // only POST allowed, path /user/create

#[Get]
public function index() { /* ... */ } // only GET allowed

Multiple annotations can be combined to allow several methods.

#[Get]
#[Post]
public function form() { /* ... */ } // allows GET and POST

Requests using methods not declared return 405. Multiple path annotations generate separate routes, e.g., #[Get('/a')] #[Post('/b')] creates GET /a and POST /b.

Route Group Prefix

Applying #[RouteGroup('/api/v1')] on a controller adds the prefix to all method routes.

use support\annotation\route\RouteGroup;
use support\annotation\route\Get;

#[RouteGroup('/api/v1')]
class UserController {
    #[Get('/user/{id}')] // actual path /api/v1/user/{id}
    public function show($id) { /* ... */ }
}

Custom Methods and Route Names

#[Route]

can define custom HTTP methods and a route name.

#[Route('/user', ['GET','POST'], 'user.form')]
public function form() { /* ... */ }

#[Route('/user/update', 'PUT')]
public function update() { /* ... */ }

Path Parameters and Regular Expressions

Annotation routes support the same parameter syntax as config/route.php, including regex constraints and optional parameters.

#[Get('/user/{id:\d+}')] // numeric id only
public function show($id) { /* ... */ }

#[Get('/user[/{name}]')] // optional name, matches /user or /user/xxx
public function list($name = null) { /* ... */ }

#[Any('/user/[{path:.+}]')] // catch‑all for any suffix
public function catchAll($path = null) { /* ... */ }

Middleware

#[Middleware]

placed on a controller or method applies the specified middleware to the annotated route, similar to using support\annotation\Middleware.

use support\annotation\Middleware;

#[Middleware(\app\middleware\AuthMiddleware::class)]
class UserController { /* ... */ }

#[Get('/user/{id}')]
#[Middleware(\app\middleware\RateLimitMiddleware::class)]
public function show($id) { /* ... */ }

Generating URLs with route()

When a route name is defined, you can generate URLs with route('name', $params). Example:

#[Get('/user/{id}', 'user.show')]
public function show($id) { /* ... */ }

// route('user.show', ['id' => 123]) => /user/123

For more details see the official Webman routing documentation at https://www.workerman.net/doc/webman/route.html.