Restler 项目技术文档

2024-12-24 13:00:45作者：鲍丁臣Ursa

1. 安装指南

1.1 安装 Composer

Restler 使用 Composer 来管理依赖。首先，下载 composer.phar 文件。你可以将其放在项目文件夹中，或者理想情况下放在 usr/local/bin 中，以便全局使用。如果你使用的是 Windows 系统，可以使用 Composer 的 Windows 安装程序。

1.2 安装 Restler

选项 1：使用 Composer 创建项目

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

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

注意：

如果你不想安装额外的格式和 BDD 工具，可以在命令中添加 --no-dev 以排除开发包。
如果你想尝试最新的 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，可以在开发机器上安装并运行它们。然后将生成的文件和文件夹上传并在服务器上使用。

1.3 配置

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

1.4 测试

在本地主机上尝试实时示例。你可以使用 composer serve 命令启动 PHP 内置服务器。

1.5 运行测试

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

vendor/bin/behat

或者你可以运行 composer test。

2. 项目使用说明

2.1 快速开始指南

我们有两个选项来创建你自己的 Restler API 服务器：

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

注意： 我们使用 restler/framework 而不是 luracast/restler 来减少包所需的存储空间。它来自 Restler-Framework，只包含 src 文件夹的内容。

2.2 编写 API

创建你的 API 类，包含所有需要的公共和受保护方法。

2.3 打开网关

创建 网关（public/index.php），如下所示：

<?php
require_once __DIR__.'/../vendor/autoload.php';

use Luracast\Restler\Restler;

$r = new Restler();
$r->addAPIClass('YourApiClassNameHere'); // 可以重复添加更多
$r->handle(); // 提供响应

2.4 美化 URL

启用 URL 重写

确保所有请求都指向 index.php，通过启用网站的 URL 重写功能。

例如：

如果你使用的是 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>

注意： 这需要将 AllowOverride 设置为 All 而不是 None，并且可能需要在某些服务器配置上进行一些调整。

如果你使用的是 Nginx，请确保设置 server_name 并将 PHP 脚本传递给监听 127.0.0.1:9000 的 fastcgi（PHP-FPM）。

server {
    listen        80;
    server_name   api.luracast.com; // 根据你的服务器名称进行更改

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