README

这是一个简单的PHP路由系统。
使用PHP属性特性。

目录

• 要求
• 安装
• 用法
  • 路由
  • 注册控制器
  • 解析请求
    • 自动解析
    • 手动解析
    • 前缀所有路由
  • 获取请求数据
  • 响应
  • 完整示例
• 测试
  • 使用Makefile
  • 手动
• 贡献
• 许可

要求

• PHP 8.2+
• Composer 2+（包管理器）
• PHPUnit 11+（自动化测试）

安装

composer require torugo/router

用法

路由

use Torugo\Router\Attributes\Request\Controller;
use Torugo\Router\Attributes\Request\Get;

#[Controller("/users")]
class UsersController {
    #[Get()] // endpoint: GET /users
    public function findAll(): array
    {
        return [/* list of users */];
    }

    #[Get("/{id}")] // endpoint: GET /users/<the user id>
    public function findOne(string $id): array
    {
        return [/* user data */];
    }
}

注册控制器

所有控制器必须使用Controller属性。

use Torugo\Router\Router;

$router = new Router;

$router->registerMany([
    UsersController::class,
    CostumersController::class,
    SuppliersController::class,
    StockController::class,
]);

try {
    $router->autoResolve();
} catch (\Throwable $th) {
    // Handle errors
}

此外，您可以单独注册控制器。

$router->register(UsersController::class);
$router->register(CostumersController::class);
$router->register(SuppliersController::class);
$router->register(StockController::class);

解析请求

自动解析

try {
    $router->autoResolve();
} catch (\Throwable $th) {
    // Handle errors
}

手动解析

$uri = Request::getUri();
$requestMethod = Request::getMethod();

// Here you can filter the uri
// The request method must be a member of RequestMethod Enum

try {
    $router->resolve($uri, $requestMethod);
} catch (\Throwable $th) {
    // Handle errors
}

前缀所有路由

如果您的API有一个前缀路由，如'/v1'，您可以配置路由器来处理它。

use Torugo\Router\Router;

$router = new Router;
$router->setPrefix("/v1");

/**
 * If you receive a GET request with the URI '/v1/users/12345', the router will execute '/users/12345'
 */

获取请求数据

您可以通过使用getData()方法从Torugo\Router\Request访问请求数据。

use Torugo\Router\Attributes\Request\Controller;
use Torugo\Router\Attributes\Request\Post;
use Torugo\Router\Request;

#[Controller("/users")]
class UsersController {
    #[Post()]
    public function add(): array
    {
        $userData = Request::getData();
        
        /* ADD NEW USER DATA ON DATABASE */
        
        return [/* new user data */];
    }
}

响应

当控制器方法返回数组时，它被转换为JSON字符串，其他类型不会被转换。

use Torugo\Router\Attributes\Request\Controller;
use Torugo\Router\Attributes\Request\Get;

#[Controller("users")]
class UsersController {
    #[Get()]
    public function findAll(): array
    {
        $users = [
            [
                "id" => "1",
                "name" => "User 1",
                "email" => "user1@host.com"
            ],
            [
                "id" => "2",
                "name" => "User 2",
                "email" => "user2@host.com"
            ],
            [
                "id" => "3",
                "name" => "User 3",
                "email" => "user3@host.com"
            ],
        ];

        return $users;
        // '[{"id":"1","name":"User 1","email":"user1@host.com"},{"id":"2","name":"User ... ]'
    }
}

完整示例

• 控制器类

  <?php declare(strict_types=1);
  
  namespace MyApi\Modules\Users;
  
  use Torugo\Router\Attributes\Request\Controller;
  use Torugo\Router\Attributes\Request\Delete;
  use Torugo\Router\Attributes\Request\Get;
  use Torugo\Router\Attributes\Request\Post;
  use Torugo\Router\Attributes\Request\Put;
  
  #[Controller("/users")]
  class UsersController {
      #[Get()] // endpoint: GET /users
      public function findAll(): array
      {
          return [/* list of users */];
      }
  
      #[Get("/{id}")] // endpoint: GET /users/<the user id>
      public function findOne(string $id): array
      {
          return [/* user data */];
      }
  
      #[Delete("/{id}")] // endpoint: DELETE /users/<the user id>
      public function deleteUser(string $id): string
      {
          return "Deleted user with $id";
      }
  
      #[Post()] // endpoint: POST /users
      public function addUser(): array
      {
          return [/* new user data */];
      }
  
      #[Put("/{id}")] // endpoint: PUT /users/<the user id>
      public function updateUser(string $id): array
      {
          return [/* updated user data */];
      }
  }

• 主应用文件 "index.php"

  <?php declare(strict_types=1);
  
  use MyApi\Modules\Users\UsersController;
  use Torugo\Router\Router;
  
  require "../vendor/autoload.php";
  
  $router = new Router;
  
  $router->register(UsersController::class);
  // OR $router->register('MyApi\Modules\Users\UsersController');
  
  try {
      $router->autoResolve();
  } catch (\Throwable $th) {
      http_response_code(400);
      echo $th->getMessage();
  }

测试

使用Makefile

要使用make运行测试，请使用

make test

或使用PHPUnit testdox

make testdox

手动

提示

• 您需要使用两个终端窗口来手动运行测试。
• 所有命令都必须从项目根目录执行。

1. 启动测试服务器

在第一个窗口终端中输入

php -S localhost\:8000 -t tests/ServerTests/Server/

2. 运行测试

在第二个窗口，从项目根目录中输入

./vendor/bin/phpunit

贡献

目前不接受贡献，我打算尽快使其可用。

许可

路由器根据MIT许可证授权 - 详细信息请参阅LICENSE文件。