README

一个特性，帮助你设置Wordpress中的REST端点。

帮助你在Wordpress项目中注册和处理REST端点。

• 安装
• 使用
  • 获取定义的路由的完整URL
  • 更改路由基本路径
• 升级

安装

通过composer

> composer require gebruederheitz/wp-simple-rest

确保您有Composer自动加载或替代类加载器。

使用

use Gebruederheitz\Traits\withREST;
/* optional */
use Gebruederheitz\Wordpress\Rest\RestRoute;

class MyClass {
    // use the trait
    use withREST;
    
    public function __construct() {
        // initialize the REST functionality
        $this->initInstanceRestApi();
    }
    
    // Callbacks for your routes must be public
    public function myRestCallback() {}
    
    // Define your Routes by implementing the abstract method
    public function getInstanceRestRoutes()
    {
        return [
            // Using the RestRoute helper object
            RestRoute::create(
                'A description of what your route does.',
                '/rest-example'
            )
                ->setCallback([$this, 'myRestCallback'])
                ->setMethods('POST')
                ->allowAnyone()
                ->addArgument(
                    'parameter_one',
                    'A description of what the argument is for.',
                    'a default value',
                    'string',
                    [$this, 'sanitizeParameterOne'],
                    [$this, 'validateParameterOne']
                )
                ->addArgument(
                    'other_param',
                    'A parameter that is essential to this route.',
                )
            ,
            // Using the legacy array format
            [
                'name' => 'A description of what your route does',
                'route' => '/rest-example',
                'config' => [
                    'methods' => 'POST',
                    'callback' => [$this, 'myRestCallback'],
                    'permission_callback' => function () {
                        return current_user_can('edit_posts');
                    },
                    'args' => [
                        'parameter_one' => [
                            'description' => 'A description of what the argument is for',
                            'default' => '',
                            'type' => 'string',
                            'sanitize_callback' => 'esc_url_raw',
                        ]
                    ]
                ]
            ],
            // Restricting access
            RestRoute::create(
                'Do dangerous things with the database',
                '/danger-zone/database',
            )
                ->setCallback([$this, 'restDangerousDbOperation'])
                // only users with 'install_plugins' capabilities
                ->allowOnlyAdmins()
                // or only users with 'edit_posts' capabilities
                ->allowOnlyEditors()
                // or a custom callback allowing you to check for capabilities
                // ...with a closure
                ->setPermissionCallback(function() {
                    return current_user_can('read_private_pages');
                })
                // ...with a class method
                ->setPermissionCallback([$this, 'canUserAccessDbDangerZone'])
                // ...with a static class method
                ->setPermissionCallback([self::class, 'canUserAccessStatic'])
            ,
        ];
    }
    
    // Must have an implementation, in this case it's just a dummy
    protected static function getRestRoutes(): array 
    {
        return [];
    }
}

现在您可以使用以下请求执行您的回调

POST https://example.com/wp-json/ghwp/v1/rest-example

或者您可以使用静态版本，允许您只调用您类中的静态方法

use Gebruederheitz\Traits\withREST;

class MyClass {
    // use the trait
    use withREST;
    
    public static function init() {
        // initialize the REST functionality
        self::initRestApi();
    }
    
    public static function myRestCallback() {}
    
    // This is the dummy this time around
    public function getInstanceRestRoutes()
    {
        return [];
    }
    
    // Define your Routes by implementing the abstract method
    protected static function getRestRoutes(): array 
    {
        return [
            [
                'name' => 'A description of what your route does',
                'route' => '/rest-example',
                'config' => [
                    'methods' => 'POST',
                    'callback' => [self::class, 'myRestCallback'],
                    'permission_callback' => function () {
                        return current_user_can('edit_posts');
                    },
                    'args' => [
                        'parameter_one' => [
                            'description' => 'A description of what the argument is for',
                            'default' => '',
                            'type' => 'string',
                            'sanitize_callback' => 'esc_url_raw',
                        ]
                    ]
                ]
            ],
        ];
    }
}

设置路由的访问权限

您应该始终明确定义您路由的访问权限，否则Wordpress会向您的脸上指指。您可以选择RestRoute提供的便利方法之一，或提供自己的回调

RestRoute::create('Name', '/path')
    // public route
    ->allowAnyone()
    // or only users with 'install_plugins' capabilities
    ->allowOnlyAdmins()
    // or only users with 'edit_posts' capabilities
    ->allowOnlyEditors()
    // or a custom callback allowing you to check for capabilities
    // ...with a closure
    ->setPermissionCallback(function() {
        return current_user_can('read_private_pages');
    })
    // ...with a class method
    ->setPermissionCallback([$this, 'canUserAccessDbDangerZone'])
    // ...with a static class method
    ->setPermissionCallback([self::class, 'canUserAccessStatic'])

获取定义的路由的完整URL

// list only the static routes
MyClass::getRestEndpoints();
// Both static and instance routes
$myClassInstance->getAllRestEndpoints();

更改路由基本路径

class MyClass {
    use \Gebruederheitz\Traits\withREST;
    
    public static $restNamespaceBase = 'my-rest-routes';
}

您的路由现在可在/wp-json/my-rest-routes/v1/rest-example中访问。

升级

到2.x版本

从v1.x到v2.0，库中使用的命名空间已更改。您需要更新您的use语句以反映这些更改

/* BEFORE */
use Gebruederheitz\Traits\Rest\withREST
/* AFTER */
use Gebruederheitz\Wordpress\Rest\Traits\withREST

开发

依赖关系

• PHP >= 7.4
• Composer 2.x
• NVM和nodeJS LTS (v16.x)
• 推荐：GNU Make（或替代方案）