README

此软件包为在PHP中编写RESTful API提供平台

简介

RESTful API是设计Web应用的现代方法，这种方法为UI设计师提供了完全的设计和改进自由度

RESTful API还提供了一种更优雅的方式来保护Web资源

此软件包为在PHP中创建此类RESTful API提供了平台

特性

注解API
可用于任何框架

用法

将 resources/.htaccess 和 resources/index.php 复制到composer包的根目录
启用Apache的 rewrite 模块
将 AllowOveride All 添加到Apache配置中的composer根目录
服务类必须实现 `PhpPlatform\RESTFul\RESTService`
使用 `@Path` 注解服务类和方法以指定特定类::方法提供服务的路径
按照下面的配置部分进行路由配置
所有服务方法必须返回 `PhpPlatform\RESTFul\HTTPResponse`

注解

@Path

可以应用于服务类或方法，表示到达该服务方法的URL路径

@GET @POST @PUT @PATCH @HEAD @DELETE

只能应用于服务方法，表示该方法能够处理哪些HTTP动词。如果一个服务方法有 `@Path 注解但没有HTTP方法，则默认应用 `@GET`

@Consumes

只能应用于服务方法，指定请求体的数据类型

反序列化器使用此注解将HTTP请求体反序列化为PHP数据。请参考反序列化部分以配置多个反序列化器

@ReCaptcha

使服务方法能够使用recaptcha进行认证。当 recaptcha.enable 配置设置为 true 时予以考虑

注意：服务请求应将recaptcha响应作为HTTP头 Php-Platform-Recaptcha-Response 发送

@CORS.force

可以应用于服务类或方法，强制请求中包含Origin头。此注解在服务上强制应用CORS，有关更多信息，请参阅本文件的 CORS 部分

配置

本节解释了此软件包的配置，可以使用config.xml进行配置

序列化器

根据请求中的Accept头，不同类型的数据需要以不同的格式进行序列化

因此，可以配置不同的序列化实现，如下所示

"serializers":{
        "array":{
            "application/json":"PhpPlatform\\RESTFul\\Serialization\\JsonToArraySerialization"
        },
        "SimpleXMLElement":{
            "application/xml":"PhpPlatform\\RESTFul\\Serialization\\XmlToSimpleXMLElementSerialization"
        }
    },

序列化器类必须实现 `PhpPlatform\RESTFul\Serialization\Serialize` 接口

反序列化器

需要将HTTP请求中的数据转换为PHP表示。可以配置不同的反序列化实现，如下所示

"deserializers":{
        "application/json":{
            "array":"PhpPlatform\\RESTFul\\Serialization\\JsonToArraySerialization"
        },
        "application/xml":{
            "SimpleXMLElement":"PhpPlatform\\RESTFul\\Serialization\\XmlToSimpleXMLElementSerialization"
        }
    },

反序列化器类必须实现 `PhpPlatform\RESTFul\Serialization\Deserialize` 接口

需要将数据转换为的PHP类型需要在服务注解中指定，如下所示


/**
 * @Consumes array
 * @Path my-service
 */
function myService(){}

路由

路由是URL模式到服务类和方法的静态映射。

路由可以通过运行手动更新或基于注解生成

$ ./vendor/bin/build-restful

路由组织为树状结构，其中每个节点包含可用于该URL路径的服务类和方法名称

对于这些URL模式，将按如下方式配置Web服务

`GET /user/all :- MyService\User::getAllUsers`
`POST /user/create :- MyService\User::createUser`
`GET /user/{id} :- MyService\User::getUser`

"routes" : {
    "children" : {
        "user" : {
            "children" : {
                "all" : {
                    "methods" : {
                        "GET" : {
                            "class" : "MyService\\User",
                            "method" : "getAllUsers"
                        }
                    }
                },
                "create" : {
                    "methods" : {
                        "POST" : {
                            "class" : "MyService\\User",
                            "method" : "createUser"
                        }
                    }
                },
                "*" : {
                    "methods" : {
                        "GET" : {
                            "class" : "MyService\\User",
                            "method" : "getUser"
                        }
                    }
                }
            }
        }
    }
}

`注意`

`路径中的参数在配置中表示为*，在上面的示例中 {id} 表示为*`

`参数的名称不映射到服务方法参数的名称，而是映射到位置`

recaptcha

recaptcha配置使服务能够要求reCaptcha身份验证

"recaptcha":{
    "enable":true,
    "secret":""
}

将enable设置为true以启用服务使用recaptcha

设置从Google reCaptcha提供的secret值

CORS

CORS配置启用CORS（跨源资源共享）身份验证

"CORS":{
    "AllowOrigins":[
    ],
    "AllowMethods":[
    ],
    "AllowHeaders":[
    ],
    "AllowCredentials":false,
    "MaxAge":1000
}

有关详细信息，请参阅https://mdn.org.cn/en-US/docs/Web/HTTP/Access_control_CORS

CORS配置可以使用注解针对特定服务进行设置。例如，允许https://specific.example.com访问特定服务

/**
 * ...
 * @CORS.AllowOrigins https://specific.example.com
 */
function mySpecificService(){}

Access-Control-*头部

Access-Control-Allow-Origin 如果该origin列在CORS.AllowOrigins配置中，则将此头部设置为请求中的origin头部
Access-Control-Allow-Methods 以逗号分隔配置在CORS.AllowMethods中的方法
Access-Control-Allow-Headers 以逗号分隔配置在CORS.AllowHeaders中的头部
Access-Control-Allow-Credentials 在CORS.AllowCredentials中配置为True/False
Access-Control-Max-Age 配置在CORS.MaxAge中的秒数
Access-Control-Exposed-Headers 从服务中的HTTPResponse对象显式设置的头部名称，以逗号分隔

php-platform / restful

维护者

详细信息