動態路由

動態路由就是把 url 的請求優雅地對應到你想要執行的操作方法。 EasySwoole 的動態路由是基于 FastRoute 實現，與其路由規則保持一致。

示例代碼

新建文件 App\HttpController\Router.php，(從框架 3.4.x 版本開始，用戶可能不需要新建此文件。如果用戶在安裝時選擇了釋放 Router.php 則不必新建，如果沒有，請自行新建):

<?php
namespace App\HttpController;

use EasySwoole\Component\Context\ContextManager;
use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;

class Router extends AbstractRouter
{
    function initialize(RouteCollector $routeCollector)
    {
        $routeCollector->get('/user', '/user');

        $routeCollector->get('/user1', '/User/user1');

        $routeCollector->get('/rpc', '/Rpc/index');

        $routeCollector->get('/', function (Request $request, Response $response) {
            $response->write('this is router home');
            return false; // 不再往下請求,結束此次響應
        });
        // $routeCollector->get('/', '/index');

        $routeCollector->get('/test', function (Request $request, Response $response) {
            $response->write('this is router test.');
            return '/child';
        });
        $routeCollector->get('/child', function (Request $request, Response $response) {
            $response->write('this is router child.');
            return false; // 不再往下請求,結束此次響應
        });

        $routeCollector->get('/mtest1', '/a/b/c/d/index/index');
        $routeCollector->get('/mtest2', '/A/B/C/D/Index/index');

        // 從 `easyswoole/http 2.x 版本開始，綁定的參數將由框架內部進行組裝到框架的 `Context(上下文)` 數據之中，具體使用請看下文。
        $routeCollector->get('/user/{id:\d+}', function (Request $request, Response $response) {
            // 獲取 id 參數
            $context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
            $id = $context['id'];
            $response->write("this is router user, id is {$id}");
            return false; // 不再往下請求,結束此次響應
        });
    }
}

創建路由

EasySwoole 路由接受一個 URI 和一個 Handler（這個 Handler 可以是一個 閉包callback 或者一個 字符串string），提供了一個簡單優雅的方法來定義路由和行為，而不需要復雜的路由配置文件：

<?php
namespace App\HttpController;

use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;

class Router extends AbstractRouter
{
    function initialize(RouteCollector $routeCollector)
    {
        $routeCollector->get('/greeting', function (Request $request, Response $response) {
            $response->write('Hello World');
            return false;
        });
    }
}

從上面可以看到，創建匹配 HTTP 請求方法 GET 的路由的方法很簡單，如下：

$routeCollector->get($uri, $handler);

• $uri 為 字符串string 格式
• $handler 為 閉包callback 或者 字符串string 格式，當為 字符串 格式時則表示是與控制類的 action 相關聯。

針對上述方法的參數的含義說明如下：

• 當 $handler 為 /xxx 時，則對應關聯執行 App\HttpController\Index.php 類的 xxx() 方法。
• 當 $handler 為 /xxx/xxx/xxx/xxx 或者 /Xxx/Xxx/Xxx/xxx 時，二者其實等價，都對應關聯執行 App\HttpController\Xxx\Xxx\Xxx.php 類的 xxx() 方法。
• 當 $handler 為 /xxx/xxx/xxx/Xxx 或者 /Xxx/Xxx/Xxx/Xxx 時，二者也等價，都對應關聯執行 App\HttpController\Xxx\Xxx\Xxx.php 類的 Xxx() 方法。

綜上所述，其實 $handler 中最后一個 / 后的名稱一定為控制器類的 action 名稱 (且不會轉換大小寫)，前面的則為對應控制器所在命名空間及路徑，控制器名稱及文件夾名稱請務必以 大寫字母 開頭，否則路由將不能匹配到對應的執行方法。而對于 $uri 則沒有特殊要求。$handler 指定路由匹配成功后需要處理的方法，可以傳入一個閉包，當傳入閉包時一定要 注意處理完成之后要處理結束響應，否則請求會繼續 Dispatch 尋找對應的控制器來處理，當然如果利用這一點，也可以對某些請求進行處理后再交給控制器執行邏輯。

默認路由文件

默認路由文件位于 App\HttpController 目錄的 Router.php 文件。在 Router.php 文件可以定義我們常用的路由。對于大多數應用程序，也都是在 Router.php 文件定義路由。例如，你可以在瀏覽器中輸入 http://example.com/user 來訪問以下路由：

<?php
namespace App\HttpController;

use EasySwoole\Http\AbstractInterface\AbstractRouter;
use FastRoute\RouteCollector;

class Router extends AbstractRouter
{
    function initialize(RouteCollector $routeCollector)
    {
        // 下面定義的路由將 /user URI 與 App\HttpController\User 類 的 index() action 相關聯
        $routeCollector->get('/user', '/User/index');
    }
}

添加額外的路由文件

上述已經提到 EasySwoole 框架默認的路由文件為 App\HttpController 目錄的 Router.php 文件。當我們想要添加額外的路由文件時，我們可以在 App 目錄新建一個目錄 Route 用來統一存放額外的路由，然后在 App\HttpController 目錄的 Router.php 文件中進行注冊。如下：

在 App\Route 目錄（前提：已自行創建好此目錄），新增 ApiRouter.php 文件，該文件內容如下：

<?php
namespace App\Route;

use FastRoute\RouteCollector;

class ApiRouter
{
    public function initialize(RouteCollector &$routeCollector)
    {
        $routeCollector->addGroup('/api/v1/user', function (RouteCollector $routeCollector) {
            $routeCollector->post('/create', '/Api/User/create');
            $routeCollector->post('/delete/{id:\d+}', '/Api/User/delete');
            $routeCollector->post('/update/{id:\d+}', '/Api/User/update');
            $routeCollector->post('/query', '/Api/User/query');
        });
    }
}

在 App\HttpController 目錄的 Router.php 文件中進行注冊額外的路由：

<?php
namespace App\HttpController;

use App\Route\ApiRouter;
use EasySwoole\Http\AbstractInterface\AbstractRouter;
use FastRoute\RouteCollector;

class Router extends AbstractRouter
{
    function initialize(RouteCollector $routeCollector)
    {
        // 注冊額外的路由
        (new ApiRouter())->initialize($routeCollector);
    }
}

依賴注入

在路由的回調方法中，框架會自動將當前的 HTTP 請求和 HTTP 響應注入依賴到你的路由回調中：

<?php
namespace App\HttpController;

use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;

class Router extends AbstractRouter
{
    function initialize(RouteCollector $routeCollector)
    {
        $routeCollector->get('/greeting', function (Request $request, Response $response) {
            $response->write('Hello World');
            return false;
        });
    }
}

注入的 HTTP 請求對象可用來讀取請求參數等，注入的 HTTP 響應對象可用來指定返回給客戶端的響應內容。

匹配 HTTP 方法

路由器允許你注冊能響應任何 HTTP 請求的路由

$routeCollector->get($uri, $handler);
// 等價于
$routeCollector->addRoute('GET', $uri, $handler);

$routeCollector->post($uri, $handler);
// 等價于
$routeCollector->addRoute('POST', $uri, $handler);

$routeCollector->put($uri, $handler);
// 等價于
$routeCollector->addRoute('PUT', $uri, $handler);

$routeCollector->patch($uri, $handler);
// 等價于
$routeCollector->addRoute('PATCH', $uri, $handler);

$routeCollector->delete($uri, $handler);
// 等價于
$routeCollector->addRoute('DELETE', $uri, $handler);

$routeCollector->head($uri, $handler);
// 等價于
$routeCollector->addRoute('HEAD', $uri, $handler);

$routeCollector->addRoute('OPTIONS', $uri, $handler);

有的時候你可能需要注冊一個可響應多種 HTTP 請求的路由，這時你可以使用 addRoute 方法注冊一個實現響應多種 HTTP 請求的路由：

$routeCollector->addRoute(['GET', 'POST'], $uri, $handler);

addRoute 方法說明

方法格式如下：

$routeCollector->addRoute($http, $uri, $handler);

• $httpMethd（HTTP 請求方法）參數必須是 大寫 的 HTTP 請求方法字符串或者字符串數組，如 GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS。

• $uri 參數需要傳入一個 URI，格式如： /路徑名稱/{參數名稱:匹配規則}，占位符 : 用于限制約束路由參數。

• $handler 參數需要傳入一個字符串或閉包，上述已說明，就不做過多闡述。

示例如下：

$routeCollector->addRoute('GET', $uri, $handler);
$routeCollector->addRoute(['GET', 'POST'], $uri, $handler);

路由參數

必需參數

有時你將需要捕獲路由內的 URI 段。例如，你可能需要從 URL 中捕獲用戶的 ID。你可以通過定義路由參數來做到這一點：

<?php
namespace App\HttpController;

use EasySwoole\Component\Context\ContextManager;
use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;

class Router extends AbstractRouter
{
    function initialize(RouteCollector $routeCollector)
    {
        $routeCollector->get('/user/{id}', function (Request $request, Response $response) {
            $context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
            $id = $context['id'];
            $response->write("User {$id}");
            return false;
        });
    }
}

也可以根據你的需要在路由中定義多個參數：

<?php
namespace App\HttpController;

use EasySwoole\Component\Context\ContextManager;
use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;

class Router extends AbstractRouter
{
    function initialize(RouteCollector $routeCollector)
    {
        $routeCollector->get('/posts/{post}/comments/{comment}', function (Request $request, Response $response) {
            $context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
            $post = $context['post'];
            $comment = $context['comment'];
            $response->write("post: {$post}, comment: {$comment}");
            return false;
        });
    }
}

路由的參數通常都會被放在 {} ，并且參數名只能為字母。

可選參數

有時，你可能需要指定一個路由參數，但你希望這個參數是可選的。你可以在加上 [] 標記將 /{參數} 包含起來來實現：

<?php
namespace App\HttpController;

use EasySwoole\Component\Context\ContextManager;
use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;

class Router extends AbstractRouter
{
    function initialize(RouteCollector $routeCollector)
    {
        $routeCollector->get('/user[/{name}]', function (Request $request, Response $response) {
            $context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
            $name = $context['name'] ?? '';
            $response->write("name: {$name}");
            return false;
        });

        // 上述路由等價于下面2個路由
        $routeCollector->get('/user', function (Request $request, Response $response) {
            // your code
            return false;
        });
        $routeCollector->get('/user/{name}', function (Request $request, Response $response) {
            $context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
            $name = $context['name'];
            $response->write("name: {$name}");
            return false;
        });

        $routeCollector->get('/user[/{id}[/{name}]]', function (Request $request, Response $response) {
            $context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
            $name = $context['name'] ?? '';
            $response->write("name: {$name}");
            return false;
        });
    }
}

獲取路由參數

從 Context 中獲取路由參數（路由參數的默認獲取機制）

可以從 \EasySwoole\Component\Context\ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY) 上下文中獲取路由參數。此配置項是easyswoole/http 2.x 版本開始的默認配置。如需設置需在 App\HttpController\Router.php 添加如下代碼：

$this->parseParams(\EasySwoole\Http\AbstractInterface\AbstractRouter::PARSE_PARAMS_IN_CONTEXT);

具體使用示例：

<?php
namespace App\HttpController;

use EasySwoole\Component\Context\ContextManager;
use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;

class Router extends AbstractRouter
{
    function initialize(RouteCollector $routeCollector)
    {
        // /user/1
        $routeCollector->get('/user/{id}', function (Request $request, Response $response) {
            $context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
            $id = $context['id']; // 1
            $response->write("id: {$id}");
            return false;
        });
    }
}

從 Query Param 中獲取路由參數

如果想從 Query Param 中獲取路由參數，可使用這個 $this->request()->getQueryParams() 方法進行獲取，但是需要先在 App\HttpController\Router.php 中進行設置：

$this->parseParams(\EasySwoole\Http\AbstractInterface\AbstractRouter::PARSE_PARAMS_IN_GET);

具體設置如下：

<?php
namespace App\HttpController;

use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;

class Router extends AbstractRouter
{
    function initialize(RouteCollector $routeCollector)
    {
        $this->parseParams(Router::PARSE_PARAMS_IN_GET);

        // /user/1
        $routeCollector->get('/user/{id:\d+}', function (Request $request, Response $response) {
            $id = $request->getQueryParam('id'); // 1
            $response->write("id: {$id}");
            return false;
        });
    }
}

從 POST 請求參數中獲取路由參數

如果想從 POST 請求參數中獲取路由參數，可使用這個 $this->request()->getParsedBody() 方法進行獲取，但是需要先在 App\HttpController\Router.php 中進行設置：

$this->parseParams(\EasySwoole\Http\AbstractInterface\AbstractRouter::PARSE_PARAMS_IN_POST);

具體設置如下：

<?php
namespace App\HttpController;

use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;

class Router extends AbstractRouter
{
    function initialize(RouteCollector $routeCollector)
    {
        $this->parseParams(Router::PARSE_PARAMS_IN_POST);

        // /user/1
        $routeCollector->get('/user/{id:\d+}', function (Request $request, Response $response) {
            $id = $request->getParsedBody('id'); // 1
            $response->write("id: {$id}");
            return false;
        });
    }
}

NONE

不獲取路由參數時，可以在 App\HttpController\Router.php 中進行設置:

$this->parseParams(\EasySwoole\Http\AbstractInterface\AbstractRouter::PARSE_PARAMS_NONE);

注意：以上 4 種設置，用戶只能設置 1 種。Router 默認使用的設置是從請求上下文 Context 中獲取路由參數。

<?php
namespace App\HttpController;

use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;

class Router extends AbstractRouter
{
    function initialize(RouteCollector $routeCollector)
    {
        // /user/1
        $routeCollector->get('/user/{id:\d+}', function (Request $request, Response $response) {
            $id = $request->getQueryParam('id'); // 1
            $response->write("id: {$id}");
            return false;
        });
    }
}

參數約束驗證

你可以在路由參數后面添加正則表達式來限制路由參數的格式：

<?php
namespace App\HttpController;

use EasySwoole\Component\Context\ContextManager;
use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;

class Router extends AbstractRouter
{
    function initialize(RouteCollector $routeCollector)
    {
        $routeCollector->get('/user/{name:.+}', function (Request $request, Response $response) {
            $context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
            $name = $context['name'];
            $response->write("name: {$name}");
            return false;
        });
        $routeCollector->get('/user1/{name:[A-Za-z]+}', function (Request $request, Response $response) {
            $context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
            $name = $context['name'];
            $response->write("name: {$name}");
            return false;
        });

        // 將限制 `/users/` 后面的id參數，只能是數字 `[0-9]`
        $routeCollector->get('/user/{id:\d+}', function (Request $request, Response $response) {
            $context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
            $id = $context['id'];
            $response->write("id: {$id}");
            return false;
        });
        $routeCollector->get('/user1/{id:[0-9]+}', function (Request $request, Response $response) {
            $context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
            $id = $context['id'];
            $response->write("id: {$id}");
            return false;
        });

        $routeCollector->get('/user2/{id:[0-9]+}/{name:[a-z]+}', function (Request $request, Response $response) {
            $context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
            $id = $context['id'];
            $name = $context['name'];
            $response->write("id: {$id}, name: {$name}");
            return false;
        });
    }
}

路由參數中的斜杠字符

路由允許除 / 之外的所有字符出現在路由參數值中。 你必須使用正則表達式明確允許 / 成為占位符的一部分：

<?php
namespace App\HttpController;

use EasySwoole\Component\Context\ContextManager;
use EasySwoole\Http\AbstractInterface\AbstractRouter;
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;

class Router extends AbstractRouter
{
    function initialize(RouteCollector $routeCollector)
    {
        $routeCollector->get('/search/{search:.*}', function (Request $request, Response $response) {
            $context = ContextManager::getInstance()->get(Router::PARSE_PARAMS_CONTEXT_KEY);
            $search = $context['search'];
            $response->write("search: {$search}");
            return false;
        });
    }
}

路由分組

路由分組允許你共享 URI 前綴，而無需在每個單獨的路由上定義這些 URI` 前綴。

嵌套組嘗試智能地將 URI 前綴與其父組 “合并”。URI 前綴中的斜杠會在適當的地方自動添加。

<?php
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;

$routeCollector->addGroup('/admin', function (RouteCollector $collector) {
    $collector->addRoute('GET', '/do-something', function (Request $request, Response $response) {
        $response->write('this is do-something');
        return false;
    });
    $collector->addRoute('GET', '/do-another-thing', function (Request $request, Response $response) {
        $response->write('this is do-another-thing');
        return false;
    });
    $collector->addRoute('GET', '/do-something-else', function (Request $request, Response $response) {
        $response->write('do-something-else');
        return false;
    });
});

// 和上述路由等價
$routeCollector->addRoute('GET', '/admin/do-something', function (Request $request, Response $response) {
    $response->write('this is do-something');
    return false;
});
$routeCollector->addRoute('GET', '/admin/do-another-thing', function (Request $request, Response $response) {
    $response->write('this is do-another-thing');
    return false;
});
$routeCollector->addRoute('GET', '/admin/do-something-else', function (Request $request, Response $response) {
     $response->write('do-something-else');
     return false;
});

特殊的路由

從路由調度到其他路由

如果要定一個調度到另一個 URI 的路由，可以使用 return 的方式，可快速實現類似重定向的功能，而不需要去定義完整的路由或者控制器：

$routeCollector->addRoute('GET', '/here', function (Request $request, Response $response) {
     return '/there';
});

use EasySwoole\Http\Request;
use EasySwoole\Http\Response;
use FastRoute\RouteCollector;

$routeCollector->addGroup('/admin', function (RouteCollector $collector) {
    // /admin/test?version=1
    // /admin/test?version=2
    // /admin/test?version=3
    $collector->addRoute('GET', '/test', function (Request $request, Response $response) {
        $version = $request->getQueryParam('version');

        if ($version == 1) {
            $path = '/V1' . $request->getUri()->getPath(); // "/V1/admin/test"
        } else {
            // /V2/admin/test
            $path = '/V2' . $request->getUri()->getPath(); // "/V2/admin/test"
        }

        // return "/V1/admin/test";
        // return "/V2/admin/test";
        return $path;
    });
});

// 注意：/admins/index?version=x 不能匹配到下面這個 action 路由配置參數
// 需要單獨配置路由，如下所示：即執行對應的 App\HttpController\V1\Admins.php 類的 index() 方法
// $routeCollector->addRoute('GET', '/admins/index', '/V1/Admin/index');
$routeCollector->addGroup('/admins', function (RouteCollector $collector) {
    // /admin/test?version=1
    // /admin/test?version=2
    // /admin/test?version=3
    $collector->addRoute('GET', '/{action}', function (Request $request, Response $response) {
        $version = $request->getQueryParam('version');

        if ($version == 1) {
            $path = '/V1' . $request->getUri()->getPath(); // "/V1/admins/test"
        } else {
            $path = '/V2' . $request->getUri()->getPath(); // "/V2/admins/test"
        }

        // return "/V1/admin/test";
        // return "/V2/admin/test";
        return $path;
    });
});

全局模式攔截

在 Router.php 加入以下代碼，即可開啟全局模式攔截

$this->setGlobalMode(true);

全局模式攔截下，路由將只匹配 Router.php 中指定的 $handler 的控制器方法進行響應，將不會執行框架的默認解析。

異常錯誤處理

通過以下 2 個方法，可設置 路由HTTP請求方法無法匹配 以及 路由無法匹配 的處理機制：

在 Router.php 加入以下代碼：

<?php
use EasySwoole\Http\Request;
use EasySwoole\Http\Response;

// 路由HTTP請求方法無法匹配
$this->setMethodNotAllowCallBack(function (Request $request, Response $response) {
    $response->withStatus(404);
    return false; // 結束此次響應
});

// 路由未知，無法匹配
$this->setRouterNotFoundCallBack(function (Request $request, Response $response){
    $response->withStatus(404);
    return 'index'; // 重定向到 index 路由
});