README

关于WaxFramework Routing

WaxFramework Routing是一个功能强大的WordPress插件路由系统，类似于流行的PHP框架Laravel。此包利用了WordPress REST路由系统，并包含自己的自定义路由系统，称为Ajax路由。

WaxFramework Routing的一个关键特性是其对中间件的支持。中间件允许你在每个请求之前执行额外的操作。

通过在WordPress插件中使用WaxFramework Routing，你可以轻松创建自定义路由和中间件来处理各种请求，包括AJAX请求，而无需麻烦。这使得它成为开发需要高级路由功能和额外安全措施的现代化和动态WordPress插件的绝佳工具。

关于WaxFramework Routing

需求

WaxFramework路由需要依赖注入（DI）容器。我们不使用任何硬编码的库，因此你可以选择使用你喜欢的任何DI库。然而，遵循我们的DI结构是很重要的，这包括在你的DI容器中拥有set、get和call方法。

我们推荐使用PHP-DI，因为它已经实现了这3个方法。

方法结构

以下是你DI容器应该具有的方法结构，以便与WaxFramework路由一起工作

set方法

/**
 * Define an object or a value in the container.
 *
 * @param string $name Entry name
 * @param mixed $value Value, define objects
 */
public function set(string $name, $value) {}

get方法

/**
 * Returns an entry of the container by its name.
 *
 * @template T
 * @param string|class-string<T> $name Entry name or a class name.
 *
 * @return mixed|T
 */
public function get($name) {}

call方法

 /**
 * Call the given function using the given parameters.
 *
 * Missing parameters will be resolved from the container.
 *
 * @param callable $callable   Function to call.
 * 
 * @return mixed Result of the function.
 */
public function call($callable) {}

安装

composer require waxframework/routing

配置

你的插件必须包含一个routes文件夹。此文件夹将包含你插件的所有路由文件。
在routes文件夹中，创建两个子文件夹：ajax和rest。这些文件夹将分别包含你插件用于AJAX和REST请求的路由文件。
如果你需要支持你路由的不同版本，你可以在ajax和rest子文件夹中创建额外的文件。例如，你可能会在ajax文件夹中创建v1.php和v2.php文件，以支持不同版本的AJAX路由。

文件夹结构示例

routes:
    rest:
        api.php
        v1.php
        v2.php
    ajax:
       api.php
       v1.php

在您的 RouteServiceProvider 类中，设置您的路由系统所需的属性。这包括设置 rest 和 ajax 命名空间、路由的版本、您想使用的中间件以及您的路由文件所在的目录。以下是一个示例

<?php

namespace MyPlugin\Providers;

use MyPlugin\Container;
use WaxFramework\Routing\Providers\RouteServiceProvider as WaxRouteServiceProvider;

class RouteServiceProvider extends WaxRouteServiceProvider {

    public function boot() {

        /**
         * Set Di Container
         */
        parent::$container = new Container;

        /**
         * OR you use PHP-Container 
         * Uses https://php-di.org/doc/getting-started.html
         */
        // parent::$container = new DI\Container();


        /**
         * Set required properties
         */
        parent::$properties = [
            'rest'       => [
                'namespace' => 'myplugin',
                'versions'  => ['v1', 'v2']
            ],
            'ajax'       => [
                'namespace' => 'myplugin',
                'versions'  => []
            ],
            'middleware' => [],
            'routes-dir' => ABSPATH . 'wp-content/plugins/my-plugin/routes'
        ];

        parent::boot();
    }
}

最后，使用 init 动作钩子执行您的 RouteServiceProvider 类的 boot 方法，如下所示

add_action('init', function() {
	$route_service_provider = new \MyPlugin\Providers\RouteServiceProvider;
	$route_service_provider->boot();
});

就是这样！您的插件现在已配置了 WaxFramework 路由系统，您可以轻松地创建自己的路由并处理请求。

在路由文件中注册路由

Rest 路由

routes/rest/api.php

编写您的第一个路由

要创建您的第一个 WordPress RESTful 路由，您可以使用 WaxFramework\Routing 命名空间中的 Route 和 Response 类，如下所示

<?php

use WaxFramework\Routing\Route;
use WaxFramework\Routing\Response;
use WP_REST_Request;

defined('ABSPATH') || exit;

Route::get('user', function(WP_REST_Request $wp_rest_request) {
	return Response::send(['ID' => 1, 'name' => 'john']);
});

在此示例中，我们使用 Route 类的 get() 方法定义一个对 /user 端点的 GET 请求。传递给第二个参数的闭包使用 Response::send() 方法返回一个响应，该方法接受一个要返回的数组，以 JSON 格式 返回。

使用控制器

如果您更喜欢为路由逻辑使用控制器，您可以指定控制器和方法作为数组，如下所示

Route::get('user', [UserController::class, 'index']);

在此，我们使用 Route 类的 get() 方法定义一个对 /user 端点的 GET 请求。我们指定控制器类和方法作为数组，其中 UserController::class 指的是类名，而 index 是方法名。

动态路由

您可以使用动态路由来处理对具有动态参数的端点的请求。要定义具有必需参数的路由，请使用括号包围参数名称，如下所示

// Required id
Route::get('users/{id}', [UserController::class, 'index']);

要定义具有可选参数的路由，您可以在参数名称后添加一个问号，如下所示

// Optional id
Route::get('users/{id?}', [UserController::class, 'index']);

路由分组

您可以使用 group() 方法将相关路由组合在一起。这允许您一次性将中间件或其他属性应用于多个路由。您还可以创建 嵌套组，如下所示

Route::group('admin', function() {

    Route::get('/',  [UserController::class, 'index']);

    Route::group('user', function() {
        Route::get('/', [UserController::class, 'index']);
        Route::post('/', [UserController::class, 'store']);
        Route::get('/{id}', [UserController::class, 'show']);
        Route::patch('/{id}', [UserController::class, 'update']);
        Route::delete('/{id}', [UserController::class, 'delete']);
    } );
} );

资源控制器

资源路由是一个强大的功能，它允许您使用单行代码快速将 CRUD（创建、读取、更新、删除）路由分配给控制器。要创建资源路由，您可以使用 resource() 方法。以下是一个示例

Route::resource('user', UserController::class);

资源路由自动生成控制器典型的 CRUD 路由，如下表所示

由资源控制器处理的操作

动词	URI	操作
GET	/users	index
POST	/users	store
GET	/users/{user}	show
PATCH	/users/{user}	update
DELETE	/users/{user}	delete

使用资源路由，您不需要单独定义每个路由。相反，您可以在单个控制器类中处理所有 CRUD 操作，这使得组织代码并保持路由一致性变得更容易。

Ajax 路由

routes/ajax/api.php

有时在使用 WordPress rest 路由时，第三方插件不会加载。为了修复此问题，我们正在创建自己的路由系统（Ajax 路由）。

注册AJAX路由与注册REST路由类似。不需要使用Route类，而是需要使用Ajax类。

以下是一个注册AJAX路由以获取用户数据的示例

use WaxFramework\Routing\Ajax;
use WP_REST_Request;

Ajax::get('user', function(WP_REST_Request $wp_rest_request) {
	return Response::send(['ID' => 1, 'name' => 'john']);
});

要将路由到WordPress管理后台，您的路由必须使用名为admin的中件间。如果您将此中件间应用到您的AJAX路由上，WaxFramework将加载WP管理代码。请查看中件间文档以了解中件间的使用过程。

获取API端点

可以使用get_rest_url()函数获取当前站点的REST API端点。要使用此函数，您需要提供当前站点ID和您插件的命名空间。

$site_id   = get_current_blog_id();
$namespace = 'myplugin';

$rest_route_path = get_rest_url($site_id, $namespace);

$user_rest_route = $rest_route_path . '/user';

类似地，您可以使用get_site_url()函数获取当前站点的URL，然后将您的命名空间追加到其中以创建AJAX API端点URL。

$ajax_route_path = get_site_url($site_id) . '/' . $namespace;

$user_ajax_route = $ajax_route_path . '/user';

中件间

要创建中件间，您需要实现Middleware接口。中件间的handle方法必须返回一个布尔值。如果handle方法返回false，则请求将立即停止。

以下是一个创建名为EnsureIsUserAdmin的中件间类的示例

<?php

namespace MyPlugin\App\Http\Middleware;

use WaxFramework\Routing\Contracts\Middleware;
use WP_REST_Request;

class EnsureIsUserAdmin implements Middleware
{
    /**
    * Handle an incoming request.
    *
    * @param  WP_REST_Request  $wp_rest_request
    * @return bool
    */
    public function handle( WP_REST_Request $wp_rest_request ): bool
    {
        return current_user_can( 'manage_options' );
    }
}

创建中件间后，您需要在RouteServiceProvider 配置中注册它。您可以通过将中件间类添加到RouteServiceProvider类的$properties数组中的middleware数组中来实现。

parent::$properties = [
	...
	'middleware' => [
		'admin' => \MyPlugin\App\Http\Middleware\EnsureIsUserAdmin::class
	]
];

要在路由中使用中件间，您可以将中件间名称作为路由定义的最后一个参数添加，如下所示

Route::get('/admin',  [AdminController::class, 'index'], ['admin']);

许可证

WaxFramework路由是开源软件，采用MIT许可证。

waxframework / routing

维护者

详细信息