README

版本 5

从版本3 RC6升级，以支持最新的PHP

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

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

Restler - 通过设计创造更好的API

功能

无学习曲线
轻量级
灵活
高度可定制
许多示例，可以在您的本地主机上尝试以开始
支持通过头部或请求参数（方法）发送和接收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部分到方法参数的映射
  - 查询参数到方法参数的映射
  - 请求体到方法参数的映射
内置缓存
- 支持客户端缓存
- 支持代理缓存
API功能
- 始终支持URLEncoded格式以简化输入（POST变量）
- 自动参数验证和类型转换
- 支持通过URL和/或供应商特定的MIME进行API版本控制
- 使用Restler API Explorer进行API文档和发现
- 节流和性能调整
管理
- 使用Behat和Guzzle进行行为驱动API测试
- 使用Respect/Foundation进行命令行项目管理
- 使用Composer进行依赖管理
- 源代码根据LGPL分发

Git仓库和分支

最稳定和最新版本位于master分支，之前的版本位于版本分支中，如v4、v3、v2和v1。
包含当前版本的版本分支（如v5）用于构建下一个版本。其文档可能不会频繁更新，因此仅供勇敢者使用。
特性分支，例如 features/html 和 features/router，纯粹用于实验目的，以尝试新功能。当准备好时可以合并。

测试驱动

安装此存储库以尝试示例。

请确保您的服务器上安装了 PHP 5.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}

注意：

如果您不希望包含额外的格式和 BDD 工具，可以在上述命令中包含 > --no-dev 以强制排除 dev 包。

如果您想尝试 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. 配置

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

4. 尝试一下

在您的 localhost 中尝试实时示例。

您可以使用 composer serve 命令启动 PHP 的内置服务器。

5. 运行一些测试

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

vendor/bin/behat

或者您也可以运行 composer test

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

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

一切准备就绪，快乐的 RESTing！ :)

快速入门指南

我们有两种方式来创建自己的 restler api 服务器

最方便的选项是使用应用程序模板，例如 Restler 应用程序，它具有与许多包的集成，可以帮助我们处理业务逻辑。如果您选择此选项，选择该存储库中的一个分支，并按照那里的说明进行操作。
从头创建一个项目，以便您可以完全控制应用程序的每个方面。如果您选择此选项，请按照以下步骤进行。
- 创建一个文件夹来保存您的项目，并在终端中打开它。
- 运行 composer init 并按照说明创建 composer.json
- 当它询问依赖项时，输入 restler/framework 和 ^5 作为版本约束。
- 或者，您也可以留空，首先创建 composer.json，然后运行 composer require restler/framework:^5

我们正在使用restler/framework而不是luracast/restler以减少包所需的空间。它来自https://github.com/Luracast/Restler-Framework，这里只包含src文件夹的内容。

即使是从零开始构建，检查应用程序模板也将有助于决定文件夹结构和找到其他有用的包。

1. 编写API

使用所有必需的公开和受保护方法创建你的API类

2. 打开网关

按照以下方式创建网关（public/index.php）

<?php
require_once __DIR__.'/../vendor/autoload.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 __DIR__.'/../vendor/autoload.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('Explorer'); //from restler framework for API Explorer
$r->addFilterClass('RateLimit'); //Add Filters as needed
$r->handle(); //serve the response

探索API，通过在浏览器中从网站根目录打开explorer/index.html来试用

祝探索愉快！：）

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

5. 注释

Restler支持API微调的PHPDoc注释形式的注释

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

6. 授权

为了保护你的API，进行身份验证并允许有效用户

<?php
require_once '../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 '../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
//...

注意：当生产模式设置为true时，它总是使用缓存，并且不会检测到任何更改和新路由。你的持续集成管道或你的git钩子应在部署过程中删除此文件。或者，你可以将第二个参数传递给restler构造函数，在需要应用更改时刷新缓存。

变更日志

Restler 5

语义版本化以向前推进
支持PHP 8
更正源路径以位于vendor目录之外
添加了php开发服务器支持，使用composer serve命令。
可以在另一个窗口使用composer serve运行服务器后，使用composer test命令运行测试。

Restler 3.0 RC6

新增功能

添加了PassThrough类，用于提供网站根目录外的文件，包括安全下载
添加了Explorer类（v1 swagger 1.2规范和v2 swagger 2.0规范），作为Resources类（swagger 1.1规范）的潜在替代品
- Explorer附带html、css和资产。因此，你不需要手动下载和配置它
- Explorer将请求体中预期的参数组合成一个独特的swagger模型
- 由于Restler Explorer附带，你可以将其映射到你选择的URL。例如，$restler->addAPIClass("Luracast/Restler/Explorer", 'swagger')将其映射到/swagger。
- 可以使用 ExplorerInfo 类轻松自定义资源管理器元数据

改进

Routes 类得到了改进，提供了 findAll 方法来列出特定 API 版本的全部路由，排除指定的路径和 HTTP 方法。
当 routes 找到时使用的魔法属性，忽略实际属性。这对于动态模型类，如 Eloquent，非常有用。
现在，当参数是对象时，Routes 允许 @required 和 @properties 是数组。这有助于我们为每个 API 方法选择不同的属性。例如 {@properties property1,property2,property3} 和 {@required property1,property2} 将使 API 只查找 3 个属性，其中 2 个是必需的。
优化了 Nav 类。现在它使用 Routes::findAll()，以及 Explorer 类。
Restler 类设置了 setBaseUrls 方法来设置可接受的基本 URL，可以使用 $_SERVER['HTTP_HOST'] 设置。阅读这篇文章了解原因。这在以下情况下非常有用：
- PHP 无法正确检测端口号
- 多个域名指向同一服务器
Restler 类现在允许通过设置 $this->restler->responseCode 从 API 方法中重写状态码。
改进了 Forms 类，使其能够将嵌入式属性发送到 emmet 模板。例如

/**
 * {@id form1}
 *
 * @param string $name
 * @param int $age
*/

生成以下表单

<form role="form" id="form1" method="POST" ...

因为 emmet 模板中有 id（见下文）

form[role=form id=$id# name=$name# method=$method# action=$action# enctype=$enctype#]

Forms 类使用带有 @param 注释的嵌入式属性来轻松设置 HTML 属性（例如 id、accept 等）
FormStyles 得到了改进。
Validator 现在通过作用域进行初始化，因此我们可以使用 @class 注释设置其属性。 示例： @class Validator {@holdException} 使验证器保留异常而不是抛出异常
改进了表单验证，为单个字段提供了错误消息。
更新了 Forms 示例，以显示基于 Bootstrap 主题的验证错误。
CommentParser 现在能够解析 @property、@property-read、@property-write，以支持记录动态属性。
CommentParser 支持短数组语法，如 string[]、DateTime[]
Scope 通过 Scope::$resolver 属性添加了对您选择的任何外部 DI 容器的支持。
将 String 类重命名为 Text 以支持 PHP 7（String 是 PHP 7 中的保留关键字）
Flash 现在实现了 ArrayAccess，因此我们可以像访问数组一样访问闪存变量
composer.json：从 require-dev 中删除了许多依赖项。当开发人员需要它们时，将提示他们单独安装。
添加了 newrelic 支持。
添加了 Memcache 支持。

luracast / restler

维护者

详细信息