PHP code example of hyperf-plus / route

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

hyperf-plus / route example snippets

use HPlus\Route\Annotation\ApiController;
use HPlus\Route\Annotation\GetApi;
use HPlus\Route\Annotation\PostApi;
use HPlus\Route\Annotation\PutApi;
use HPlus\Route\Annotation\DeleteApi;

#[ApiController]  // 自动生成 /api/users
class UserController
{
    #[GetApi]
    public function index() {}      // GET /api/users
    
    #[GetApi] 
    public function show($id) {}    // GET /api/users/{id}
    
    #[PostApi]
    public function create() {}     // POST /api/users
    
    #[PutApi]
    public function update($id) {}  // PUT /api/users/{id}
    
    #[DeleteApi]
    public function delete($id) {}  // DELETE /api/users/{id}
}

#[ApiController]
class UserController
{
    #[GetApi]
    public function state($id) {}       // GET /api/users/{id}/state
    
    #[PostApi]
    public function enable($id) {}      // POST /api/users/{id}/enable
    
    #[GetApi]
    public function permissions($id) {} // GET /api/users/{id}/permissions
}

#[ApiController(prefix: '/v2/members')]
class UserController
{
    #[GetApi(path: '/all')]
    public function index() {}  // GET /v2/members/all
    
    #[GetApi]
    public function show($id) {} // GET /v2/members/{id}
}

#[GetApi]
public function getUserProfile($id) {}  
// GET /api/users/{id}/get-user-profile

#[GetApi]
public function apiV2Users() {}  
// GET /api/users/api-v2-users

#[ApiController(
    prefix: '/api/v1/users',  // 路由前缀（可选，默认自动生成）
    tag: 'User Management',   // API 标签（Swagger 用）
    server: 'http',           // 服务名
)]

#[GetApi(
    path: '/{id}/detail',      // 自定义路径（可选）
    summary: '获取用户详情',    // 接口摘要
    description: '详细描述',    // 接口描述
    name: 'user.detail',       // 路由名称
    middleware: ['auth'],      // 中间件
    security: true,            // 需要认证
    deprecated: false,         // 是否废弃
)]

use HPlus\Route\Annotation\Query;
use HPlus\Route\Annotation\Path;
use HPlus\Route\Annotation\Body;
use HPlus\Route\Annotation\Header;

#[GetApi]
public function search(
    #[Query] string $keyword,
    #[Query] int $page = 1,
    #[Path] int $id,
    #[Header('X-Token')] string $token,
) {}

use HPlus\Route\RouteCollector;

$collector = RouteCollector::getInstance();

// 获取所有路由
$routes = $collector->collectRoutes();

// 按路径查找
$route = $collector->findRouteByPath('/api/users');

// 按控制器查找
$routes = $collector->findRoutesByController(UserController::class);

// 按标签查找
$routes = $collector->findRoutesByTag('User Management');

namespace App\Controller\Api\V2;

#[ApiController]  // 自动生成 /api/v2/users
class UserController {}

use HPlus\Validate\Annotations\RequestValidation;

#[PostApi]
#[RequestValidation(rules: [
    'name' => '

// 控制器类名
UserProfileController

// 3.x 生成的 URL
/api/user_profile
/api/user_profiles

// 4.0 生成的 URL
/api/user-profile
/api/user-profiles

// 3.x
public function getUserInfo() {}  // → /api/users/get_user_info
public function batchUpdate() {}  // → /api/users/batch_update

// 4.0
public function getUserInfo() {}  // → /api/users/get-user-info
public function batchUpdate() {}  // → /api/users/batch-update

// 3.x
#[GetApi(deprecated: true)]  // bool 类型

// 4.0
#[GetApi(deprecated: true)]  // 仍支持 bool，向后兼容

// 在注解中显式指定旧路径
#[ApiController(prefix: '/api/user_profile')]
class UserProfileController {}

#[GetApi(path: '/get_user_info')]
public function getUserInfo() {}

// 如果使用了被移除的映射方法名，需要手动指定路径
// 3.x 自动映射
#[GetApi]
public function all() {}  // → GET /api/users

// 4.0 需要显式指定
#[GetApi(path: '/')]
public function all() {}  // → GET /api/users

// 暂无自动兼容方案，需手动在注解中指定旧路径
// 或使用 Nginx 重写规则做兼容：

# nginx.conf
location /api/ {
    # 将下划线转为中划线
    if ($request_uri ~* "_") {
        rewrite ^(.*)_(.*)$ $1-$2 permanent;
    }
}

tests/
├── Unit/
│   ├── AnnotationTest.php           # 注解测试
│   ├── DispatcherFactoryTest.php    # 调度器测试
│   └── RouteCollectorTest.php       # 路由收集器测试
├── Feature/
│   └── RouteCollectionFeatureTest.php  # 功能测试
└── Fixtures/
    ├── RestfulController.php        # 测试控制器
    └── TestApiController.php

diff
- PHP >= 8.0
+ PHP >= 8.1

bash
# 导出当前所有路由
php bin/hyperf.php route:list > routes_backup.txt

javascript
// 修改前
fetch('/api/user_profile')
fetch('/api/get_user_info')

// 修改后
fetch('/api/user-profile')
fetch('/api/get-user-info')

bash
# 启动服务
php bin/hyperf.php start

# 检查路由是否正确
curl http://localhost:9501/api/users