Route

XinAdmin implements controller attribute-based routing, defining routes, middleware, and permissions by adding PHP Attribute annotations to controllers.

How It Works

AnnoRouteService scans all controller classes with #[RequestAttribute] annotation, parses class-level and method-level annotations, and automatically registers corresponding routes.

Core Components

Component	Namespace	Description
RequestAttribute	Xin\AnnoRoute\RequestAttribute	Controller class-level annotation
GetRoute	Xin\AnnoRoute\Route\GetRoute	GET request route annotation
PostRoute	Xin\AnnoRoute\Route\PostRoute	POST request route annotation
PutRoute	Xin\AnnoRoute\Route\PutRoute	PUT request route annotation
DeleteRoute	Xin\AnnoRoute\Route\DeleteRoute	DELETE request route annotation
Query	Xin\AnnoRoute\Crud\Query	CRUD query list annotation
Find	Xin\AnnoRoute\Crud\Find	CRUD find single annotation
Create	Xin\AnnoRoute\Crud\Create	CRUD create annotation
Update	Xin\AnnoRoute\Crud\Update	CRUD update annotation
Delete	Xin\AnnoRoute\Crud\Delete	CRUD delete annotation

Controller Class Annotation

Use #[RequestAttribute] on controller class:

<?php

namespace App\Http\Controllers\Admin;

use Xin\AnnoRoute\RequestAttribute;

#[RequestAttribute(
    routePrefix: '/admin/user',
    abilitiesPrefix: 'admin',
    middleware: ['admin.auth'],
    authGuard: 'admin'
)]
class UserController extends Controller
{
    // Controller methods
}

Parameters:

Parameter	Type	Default	Description
routePrefix	string	''	Route prefix, full route address is composed of this prefix + method annotation route
abilitiesPrefix	string	''	Permission abilities prefix, final permission is composed of this prefix + authorize
middleware	string\|array	''	Controller middleware
authGuard	string\|null	null	Authentication guard provider

Method Route Annotations

Use route annotations on controller methods to define individual routes:

GetRoute - GET Request

use Xin\AnnoRoute\Route\GetRoute;

#[GetRoute(
    route: '/list',
    authorize: 'user.list',
    middleware: ['throttle:60,1'],
    where: ['id' => '[0-9]+']
)]
public function list(): JsonResponse
{
    // ...
}

PostRoute - POST Request

use Xin\AnnoRoute\Route\PostRoute;

#[PostRoute(
    route: '/create',
    authorize: 'user.create',
    middleware: [],
    where: []
)]
public function create(): JsonResponse
{
    // ...
}

PutRoute - PUT Request

use Xin\AnnoRoute\Route\PutRoute;

#[PutRoute(
    route: '/{id}',
    authorize: 'user.update',
    where: ['id' => '[0-9]+']
)]
public function update(int $id): JsonResponse
{
    // ...
}

DeleteRoute - DELETE Request

use Xin\AnnoRoute\Route\DeleteRoute;

#[DeleteRoute(
    route: '/{id}',
    authorize: 'user.delete',
    where: ['id' => '[0-9]+']
)]
public function delete(int $id): JsonResponse
{
    // ...
}

Route Annotation Parameters:

Parameter	Type	Default	Description
route	string	''	Route address, relative to class-level routePrefix
authorize	string\|bool	true	Permission ability string, true means no permission required, false means no login required
middleware	string\|array	''	Route middleware
where	array	[]	Route parameter regex constraints, e.g., `['id' => '[0-9]+']`

CRUD Annotations

CRUD annotations are class-level annotations. When used, they automatically look for $service property in the controller as the repository class and generate corresponding route handler closures.

Define Repository Service

Controller must define $service property:

<?php

namespace App\Http\Controllers\Admin;

use App\Repository\UserRepository;
use Xin\AnnoRoute\RequestAttribute;
use Xin\AnnoRoute\Crud\Query;
use Xin\AnnoRoute\Crud\Find;
use Xin\AnnoRoute\Crud\Create;
use Xin\AnnoRoute\Crud\Update;
use Xin\AnnoRoute\Crud\Delete;

#[RequestAttribute(routePrefix: '/admin/user', abilitiesPrefix: 'admin')]
#[Query, Find, Create, Update, Delete]
class UserController extends Controller
{
    protected string $service = UserRepository::class;
}

Query - Query List

#[Query(
    middleware: ['throttle:60,1'],
    where: []
)]

HTTP Method: GET
Route Address: /
Default Permission: query
Repository Method: query($request->query())

Find - Find Single

#[Find(
    middleware: [],
    where: ['id' => '[0-9]+']
)]

HTTP Method: GET
Route Address: /{id}
Default Permission: find
Route Constraint: id must be numeric
Repository Method: find($id)

Create - Create New

#[Create(
    middleware: [],
    where: []
)]

HTTP Method: POST
Route Address: /
Default Permission: create
Repository Method: create($request->all())

Update - Update

#[Update(
    middleware: [],
    where: ['id' => '[0-9]+']
)]

HTTP Method: PUT
Route Address: /{id}
Default Permission: update
Route Constraint: id must be numeric
Repository Method: update($id, $request->all())

Delete - Delete

#[Delete(
    middleware: [],
    where: ['id' => '[0-9]+']
)]

HTTP Method: DELETE
Route Address: /{id}
Default Permission: delete
Route Constraint: id must be numeric
Repository Method: delete($id)

Complete Examples

Example 1: Using CRUD Annotations

<?php

namespace App\Http\Controllers\Admin;

use App\Repository\ArticleRepository;
use Xin\AnnoRoute\RequestAttribute;
use Xin\AnnoRoute\Crud\Query;
use Xin\AnnoRoute\Crud\Find;
use Xin\AnnoRoute\Crud\Create;
use Xin\AnnoRoute\Crud\Update;
use Xin\AnnoRoute\Crud\Delete;

#[RequestAttribute(
    routePrefix: '/admin/article',
    abilitiesPrefix: 'admin',
    middleware: ['admin.auth']
)]
#[Query, Find, Create, Update, Delete]
class ArticleController extends Controller
{
    public function __construct(
        protected ArticleService $service
    ) {}
}

Generated Routes:

Method	Route	Permission	Description
GET	/admin/article	admin.query	Query article list
GET	/admin/article/{id}	admin.find	Find single article
POST	/admin/article	admin.create	Create article
PUT	/admin/article/{id}	admin.update	Update article
DELETE	/admin/article/{id}	admin.delete	Delete article

Generated Routes:

Method	Route	Permission	Description
GET	/admin/user	admin.query	Query user list
GET	/admin/user/{id}	admin.find	Find single user
POST	/admin/user/import	user.import	Import users
GET	/admin/user/export	user.export	Export users
POST	/admin/user/toggle-status/{id}	user.toggle	Toggle user status

Example 2: Public Endpoints Without Permission Control

<?php

namespace App\Http\Controllers\Api;

use Xin\AnnoRoute\RequestAttribute;
use Xin\AnnoRoute\Route\GetRoute;
use Xin\AnnoRoute\Route\PostRoute;

#[RequestAttribute(routePrefix: '/api/public')]
class PublicController extends Controller
{
    #[GetRoute(route: '/banner')]
    public function banner(): JsonResponse
    {
        // Requires login...
    }

    #[PostRoute(route: '/feedback', authorize: false)]
    public function feedback(): JsonResponse
    {
        // No permission verification...
    }
}

authorize Parameter:

Value	Description
true	Requires login, uses default permission check
false	Requires login, but does not check specific permission ability
string	Requires login, and checks specified permission ability

Route Annotation Common Properties

All route annotations inherit from BaseAttribute with the following properties:

Property	Type	Description
route	string	Route address
middleware	string\|array	Middleware
httpMethod	string	HTTP request method
authorize	string\|bool	Permission ability
where	array	Route parameter regex constraints

Middleware Composition

Middleware can be set globally (class-level) and locally (method-level), and will be merged:

#[RequestAttribute(
    routePrefix: '/admin/user',
    middleware: ['admin.auth']  // Global middleware
)]
class UserController extends Controller
{
    #[PostRoute(
        route: '/create',
        middleware: ['throttle:60,1']  // Additional local middleware
    )]
    public function create(): JsonResponse
    {
        // Final middleware: ['admin.auth', 'throttle:60,1']
    }
}

Permission Ability Composition

Permission ability is composed of abilitiesPrefix and authorize:

#[RequestAttribute(
    routePrefix: '/admin/user',
    abilitiesPrefix: 'admin'  // Abilities prefix
)]
#[Create]
class UserController extends Controller
{
    // Create annotation's authorize defaults to 'create'
    // Final permission ability: 'admin.create'
}

#Route

#How It Works

#Core Components

#Controller Class Annotation

#Method Route Annotations

#GetRoute - GET Request

#PostRoute - POST Request

#PutRoute - PUT Request

#DeleteRoute - DELETE Request

#CRUD Annotations

#Define Repository Service

#Query - Query List

#Find - Find Single

#Create - Create New

#Update - Update

#Delete - Delete

#Complete Examples

#Example 1: Using CRUD Annotations

#Example 2: Public Endpoints Without Permission Control

#Route Annotation Common Properties

#Middleware Composition

#Permission Ability Composition