README


版本3.0发布候选版5

Restler是一个用PHP编写的简单而有效的多格式Web API服务器。

只需在PHP中处理您的业务逻辑，restler将负责REST！

如果您服务器上没有PHP >= 5.3.2且无法升级，您可以使用Restler 2代替

Restler 3 - 通过设计改进API

• 开发者主页
• 实时示例
• 在Facebook和Twitter上的更新
• 功能
• 安装
• 快速入门指南
• 变更日志

功能

• 无学习曲线
• 轻量级
• 灵活
• 高度可定制
• 许多示例，您可以在本地主机上尝试以开始
• 支持通过标题或请求参数（方法）进行HTTP请求方法HEAD、GET、POST、PUT、DELETE、OPTIONS和PATCH
• 支持RESTful和实用REST API设计
• 客户端可以使用X-HTTP-Method-Override标题，支持跨源资源共享和JSONP
• 双向格式（媒体类型）转换，包括发送和接收
  • 可插拔的内容格式化框架和API
  • 附带JSON、XML、Yaml、Amf和Plist（XML和二进制）格式支持
• 可插拔的认证方案
  • OAuth 2服务器
• 可插拔的过滤器，以有效地管理API使用
  • API速率限制过滤器
• 路由
  • 手动路由（注释）
    • 使用@url GET my/custom/url/{param} PHPDoc注释
  • 自动路由（反射）
    • URL到方法映射
    • URL部分到方法参数映射
    • 查询参数到方法参数映射
    • 请求体到方法参数映射
    • [计划中]标题到方法参数映射
• 内置缓存
  • 支持客户端缓存
  • 支持代理缓存
  • 服务器端缓存
    • [计划中]支持ETag、If-None-Match
    • [计划中]支持Last-Modified、If-Modified-Since
• API功能
  • 始终支持URL编码格式以简化输入（POST变量）
  • 自动参数验证和类型转换
  • 支持通过URL和/或供应商特定的MIME进行API版本控制
  • 使用Restler API资源管理器进行API文档和发现
  • 节流和性能调整
• 管理
  • [计划中] 使用 PHPUnit 进行单元测试
  • 使用 Behat 和 Guzzle 进行行为驱动 API 测试
  • 使用 Respect/Foundation 进行命令行项目管理
  • 使用 Composer 进行依赖管理
  • 源代码在 LGPL 协议下分发

Git 仓库和分支

1. 最稳定和最新的版本维护在 master 分支，之前的版本保存在 v1 和 v2 等分支中

2. 带有当前版本的版本分支，例如 v3，用于构建下一个版本。它的文档可能不会频繁更新，因此仅供勇敢的人使用。

3. 功能分支，如 features/html 和 features/router，纯粹用于实验目的，以尝试新功能

安装

请确保您的服务器上安装了 PHP 5.3.2 或更高版本（建议至少安装 5.3.4 以避免潜在的错误）

1. 安装 Composer

Restler 使用 Composer 来管理其依赖项。首先，下载一份 composer.phar 复件。它可以保存在您的项目文件夹中，或者最好保存在 usr/local/bin 以便全局使用。如果您使用的是 Windows，则可以使用 composer 的 Windows 安装程序。

2. 安装 Restler

选项 1：使用 composer create-project

您可以通过在终端中运行创建项目命令来安装 Restler。将 {projectName} 替换为您实际的项目名称。它将创建一个具有该名称的文件夹并安装 Restler。

php composer.phar create-project luracast/restler {projectName}

注意：-

1. 如果您不想包含额外的格式和行为驱动工具，可以在上述命令中包含 --no-dev 以强制排除开发包。

2. 如果您想尝试 bleeding edge v3 分支或任何功能分支，请在上述命令中包含 3.x-dev 或 dev-features/html。

选项 2：从 GitHub 下载

安装 Composer 后，下载 Restler 框架的最新版本，并将其内容提取到您的服务器上的一个目录中。然后，在 Restler 项目的根目录下，运行 php composer.phar install（或 composer install）命令以安装框架的所有依赖项。此过程需要在服务器上安装 Git 才能成功完成安装。

如果您想更新 Restler 框架，可以运行 php composer.phar update 命令。

注意： 如果您不允许在服务器上安装 composer 和 git，您可以在开发机上安装并运行它们。生成的文件和文件夹可以上传并在服务器上使用。

3. 配置

理想情况下，公共文件夹应该映射为您的网站根目录。这是可选的，但建议避免暴露不必要的文件和文件夹。

4. 尝试一下

在您的 localhost 中尝试实时示例

5. 运行一些测试

更新 behat.yml 中指定的 base_url，然后尝试以下命令

bin/behat

这将测试示例与预期的行为，例如

Feature: Testing CRUD Example
    Scenario: Creating new Author with JSON
        Given that I want to make a new "Author"
        And his "name" is "Chris"
        And his "email" is "chris@world.com"
        And the request is sent as JSON
        When I request "/examples/_007_crud/authors"
        Then the response status code should be 200
        And the response should be JSON
        And the response has a "id" property

一切就绪，快乐的 Restling！ :)

快速入门指南

一旦按照以上步骤安装了 Restler，您就可以按照以下步骤快速创建应用程序

1. 编写 API

创建您的 API 类，包含所有必要的公共和受保护方法

2. 打开网关

创建如下所示的 网关（index.php）

<?php
require_once '../../../vendor/restler.php';
use Luracast\Restler\Restler;

$r = new Restler();
$r->addAPIClass('YourApiClassNameHere'); // repeat for more
$r->handle(); //serve the response

3. 美化 URL

启用 URL 重写

确保所有请求都通过启用网站上的 URL 重写路由到 index.php

例如：

如果您使用的是 Apache，您可以使用以下 .htaccess 文件

DirectoryIndex index.php
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteRule ^$ index.php [QSA,L]
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^(.*)$ index.php [QSA,L]
</IfModule>
<IfModule mod_php5.c>
    php_flag display_errors On
</IfModule>

注意： 这需要在 httpd.conf 文件中将 AllowOverride 设置为 All 而不是 None，可能需要在某些服务器配置上进行一些调整。有关更多信息，请参阅 mod_rewrite 文档。

如果您正在使用 Nginx，请确保您设置了 server_name，并将 PHP 脚本传递给监听在 127.0.0.1:9000 的 fast cgi（PHP-FPM）。

server {
        listen        80;
        server_name   api.luracast.com; //change it to match your server name

        //... other stuff

        location ~ \.php$ {
            root           /var/www/html;
            fastcgi_pass   127.0.0.1:9000;
            fastcgi_index  index.php;
            fastcgi_param  SCRIPT_FILENAME  /var/www/html/$fastcgi_script_name;
            include        fastcgi_params;
        }

        //... other stuff

}

注意： 这需要正确安装和配置 PHP 和 PHP-FPM。有关更多信息，请参阅 PHP FastCGI 示例。

4. 自定义

调整以满足您的需求

<?php
require_once '../../../vendor/restler.php';
use Luracast\Restler\Restler;
use Luracast\Restler\Defaults;
//set the defaults to match your requirements
Defaults::$throttle = 20; //time in milliseconds for bandwidth throttling
//setup restler
$r = new Restler();
$r->addAPIClass('YourApiClassNameHere'); // repeat for more
$r->addAPIClass('Resources'); //from restler framework for API Explorer
$r->addFilterClass('RateLimit'); //Add Filters as needed
$r->handle(); //serve the response

如果您已成功完成安装步骤 2，您应该在 vendor/Luracast/explorer 文件夹中安装了 Restler API Explorer。创建 vendor/Luracast/explorer/dist 的符号链接或将文件夹复制并命名为 explorer

将 explorer 放在与 index.php 相同的文件夹中

通过在浏览器中打开网页根目录下的 explorer/index.html 来探索 API 并试用

祝您探索愉快！ :)

注意： 使用 eAccelerator 可能会使 Restler 失败，因为它会移除注释。更多信息可以在 这里 找到。

5. 注释

Restler 支持使用 PHPDoc 注释进行 API 微调的注释。

它们在 注释 部分有详细说明。

6. 授权

为了保护您的 API，需要进行身份验证并允许有效用户访问。

<?php
require_once '../../../vendor/restler.php';
use Luracast\Restler\Restler;
$r = new Restler();
$r->addAPIClass('YourApiClassNameHere'); // repeat for more
$r->addAuthenticationClass('CustomAuth'); //Add Authentication classes as needed
$r->handle(); //serve the response

7. 开始生产

默认情况下，Restler 以调试模式运行，更适合 API 开发者，它会显示详细的错误消息并将 API 结果格式化为人可读的格式。

通过开启生产模式，您将获得一些性能提升，因为它将缓存路由（注释解析仅在第一次 API 调用时发生），一些其他文件，并且避免提供调试信息。

<?php
require_once '../../../vendor/restler.php';
use Luracast\Restler\Restler;

//setup restler

$r = new Restler(true); //turn on production mode by passing true.
//If you are using file based cache (the default) make sure cache folder is
//writable. when you make changes to your code make sure you delete the
// routes.php inside the cache folder
//...

变更日志

Restler 3.0 RC5

• 添加了作用域（一个依赖注入容器）。它的 register 方法允许添加具有依赖关系的 API 类。
• 改进了 HtmlFormat 以支持 blade 模板，并使其易于扩展以添加您自己的模板。
• HtmlFormat::$format 已重命名为 HtmlFormat::$template 以提高清晰度。
• HtmlFormat 现在支持自动模板化，根据映射的 URL 加载相关模板。
• Tag，一个用于以面向对象方式生成 HTML 标签的实用类。
• Emmet 类扩展了 emmet 的一部分，用于创建模板引擎。
• Forms 类用于自动生成任何预建在 HTML5、Twitter Bootstrap 3、Zurb Foundation 格式的 API 方法的表单。
• Validator 改进后允许抑制验证错误立即抛出异常，这样 API 调用就可以到达 API 方法。
• Validator 改进为更友好地处理表单验证。
• Nav 类创建 HTML 导航界面。
• OAuth 示例已升级，以使用 OAuth2 库的 1.0 版本。
• 许多错误修复和改进。

Restler 3.0 RC4

• API 方法参数中的 $request_data 和 Restler 实例上的 getRequestData() 现在排除了 $_GET 参数。
• 从 API 方法返回 null 现在排除了响应体。此行为可以通过将 Defaults::$emptyBodyForNullResponse 设置为 false 来更改。
• 在测试文件夹下添加了许多 API 示例，以便通过 BDD（行为驱动开发）逐个功能进行测试。
• 支持自定义类参数和自定义类参数数组。
• 当它是唯一的参数时，可以直接将参数作为请求体传递。
• 修复了 composer.json 并作为 composer 包在 packagist 上发布稳定版本。
• 新路由类，改进了路由功能，包括通配符路由和基于参数类型的智能路由。
• 可以使用任何自动加载器，包括composer的自动加载器，以实现最大兼容性。
• 将CFPropertyList迁移到使用rodneyrehm/plist包。
• 删除了实际上并非“必需”的所需包，Restler可以开箱即用。
• 创建支持包作为require-dev，将通过composer install --dev安装。
• 添加了所有支持包的建议部分。
• 为包描述符添加了关键字。
• 添加了分支别名，以表明v3是v3.0.x-dev的快照。
• 将Restler作为包发布到packagist。

Restler 3.0 RC3

• 添加了Defaults::$cacheDirectory以在中央位置设置缓存目录。
• 通过扩展JsonFormat添加了JsFormat类以支持JSONP。
• 修复了当请求体中发送的JSON不是对象或数组时发生的致命错误。
• 在找到分隔符且标签不是@pattern时，通过数组转换改进了内联注释解析。
• 重新编写了RateLimit类以支持所有时间单位（second|minute|hour|day|week|month），以实现更细粒度的控制。
• 改进了Resources类，包括对正文参数的描述。
• 修复了当返回类型是自定义类的数组时，Resources不包括命名空间的问题。
• 修复了当前api名称以另一个类的API的部分开头时，资源不包括另一个类的API的问题。
• 添加了两种排除API的方法。
  • Resources::$excludedHttpMethods（数组）
  • Resources::$excludedPaths（数组）
• 修复了PHP < 5.4中未转义的Unicode错误。
• 修复了解析@choice内联注释的ValidationInfo错误。
• 添加了字符集支持。
• 添加了语言（基本）支持。
• 更新了BDD测试以包括新功能。
• 修复了Restler类中的一个错误，该错误会影响Defaults的$_GET覆盖。
• 修复了XmlFormat解析XML内容为数组的错误。
• 通过JsonFormat的jsFormat扩展添加了对JSONP的支持。
• 修复了PHP < 5.4中JsonFormat未转义Unicode的错误。
• 修复了顺序，以便在编码响应之前调用responseFormat->setCharset。
• 文档改进和小的错误修复。

Restler 3.0 RC2

• 过滤器类可以使用身份验证状态，并通过实现iUseAuthentication接口对已认证用户做出不同的响应。
• 添加了RateLimit类以限制API的使用。
• 修复了setCompatibilityMode的错误。
• 更新了Resources，使用路径而不是类名进行资源标识。
  • 启用了文档的访问控制。
• 修复了CommentParser以忽略重复的空白，以便正确解析注释。
• 修复了@status和@expires标签的注释解析。
• 添加了以下示例
  • 文档
  • 速率限制
  • 访问控制
• CRUD示例已更新，包括PATCH支持

Restler 3.0

Restler 3.0完全重写自Restler 2.0，考虑了以下最佳实践

• PHP编码
• RESTfulness和/或实用REST
• API设计

Restler 3.0

• 使用命名空间、延迟静态绑定和闭包，因此它仅适用于PHP 5.3+（如果需要PHP 5.0+支持，请使用Restler 2）
• 为Restler 1和2提供向后兼容性。使用$r->setCompatibilityMode($version);
• 支持混合API，为已认证用户提供扩展数据。使用@access hybrid PHPDoc注释
• 默认使用智能自动路由，其中API方法参数具有默认值不再映射到URL，而是映射到查询字符串，以减少URL中的歧义。
• 支持将查询字符串中的suppress_response_codes设置为true；当设置为true时，所有HTTP响应将以HTTP OK返回，错误信息包含在响应体中，以适应移动端和权限较低的客户端。
• 改进了CommentParser，增加了对多种格式嵌入数据的支持
  • 内联文档注释{@name value}
  • 查询字符串参数``` param1=value¶m2=value2```
  • JSON ``` {"param1": value, "param2": value2}``` 可以放在多行中
• 包含有Defaults类，具有静态属性，可以根据需要修改
• iAuthenticate现在使用__isAllowed方法而不是__isAuthenticated，以便相同的类可以用于身份验证或过滤
• 添加了iUseAuthentication接口，以帮助混合访问API方法和过滤器了解用户身份验证状态
• iFilter接口更新，以提供字符集支持
• ...(后续还有更多)

Restler 2.0

Restler 2.0是一个主要的重写，使用约定优于配置，并针对性能进行了优化。以下是其中一些主要的变化和改进

• 将方法映射到URI的PHPDoc注释现在是可选的。
• 所有不以下划线开头的公共方法都将自动映射到方法名（gateway\classname\methodname\param1\...）
• 如果我们没有指定$restler->addAPIClass的第二个参数，它将映射到类名，而不是映射到根
• Restler 2是为PHP 5.3及以上版本编写的，但它使用compat.php并在PHP 5.0及以上的任何版本上运行