README

关于WpMVC Routing

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

WpMVC Routing的一个关键特性是它对中间件的兼容性。中间件允许你在每个请求之前执行额外的操作。

通过在你的WordPress插件中使用WpMVC Routing，你可以轻松地创建自定义路由和中间件来处理各种请求，包括AJAX请求，从而使其成为开发需要高级路由功能和额外安全措施的现代和动态WordPress插件的一个优秀工具。

关于WpMVC Routing

要求

WpMVC路由需要一个依赖注入（DI）容器。我们不使用任何硬编码的库，因此你可以选择使用你偏好的任何DI库。然而，遵循我们的DI结构非常重要，这包括在你的DI容器中实现set、get和call方法。

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

方法结构

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

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 wpmvc/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 WpMVC\Routing\Providers\RouteServiceProvider as WpMVCRouteServiceProvider;

class RouteServiceProvider extends WpMVCRouteServiceProvider {

    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();
});

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

在路由文件中注册路由

REST路由

routes/rest/api.php

编写你的第一个路由

为了在WordPress中创建第一个RESTful路由，你可以使用来自WpMVC\Routing命名空间的Route和Response类，如下所示

<?php

use WpMVC\Routing\Route;
use WpMVC\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路由，如下表所示

资源控制器处理的行为

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

Ajax路由

routes/ajax/api.php

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

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

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

use WpMVC\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路由，WpMVC将加载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 WpMVC\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' );
    }
}

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

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

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

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

许可证

WpMVC路由是开源软件，根据MIT许可证授权。

wpmvc / routing

维护者

详细信息