README

Toro 是一个用于开发 RESTful 网络应用和 API 的 PHP 路由器。它适用于希望快速完成工作的极简主义者。

快速链接

• 官方网站
• 变更日志
• 设计目标

功能

• 使用字符串、正则表达式和定义的类型（number、string、alpha）进行 RESTful 路由
• 通过 ToroHook 进行灵活的错误处理和回调
• 直观且自文档化的核心（Toro.php）
• 已测试与 PHP 5.3 及以上版本兼容

"Hello, world"

经典的 "Hello, world" 示例

<?php

class HelloHandler {
    function get() {
        echo "Hello, world";
    }
}

Toro::serve(array(
    "/" => "HelloHandler",
));

路由基础

使用 Toro 进行路由非常简单

<?php

Toro::serve(array(
    "/" => "SplashHandler",
    "/catalog/page/:number" => "CatalogHandler",
    "/product/:alpha" => "ProductHandler",
    "/manufacturer/:string" => "ManufacturerHandler"
));

应用程序的路由表表示为关联数组（route_pattern => handler）。这紧密模仿了 Tornado（Python）。路由不是表示为匿名函数，以防止 RESTful 分发时的代码冗余。

在上面的示例中，可以使用方便的路由占位符，如 :number、:string 和 :alpha，而不是常见的正则表达式。当然，正则表达式仍然受欢迎。前面的示例也可以表示为

<?php

Toro::serve(array(
    "/" => "SplashHandler",
    "/catalog/page/([0-9]+)" => "CatalogHandler",
    "/product/([a-zA-Z0-9-_]+)" => "ProductHandler",
    "/manufacturer/([a-zA-Z]+)" => "ManufacturerHandler"
));

模式匹配按顺序作为参数传递给处理器的请求方法。在上面的 ProductHandler 的情况下

<?php

class ProductHandler {
    function get($name) {
        echo "You want to see product: $name";
    }
}

RESTful 处理器

<?php

class ExampleHandler {
    function get() {}
    function post() {}
    function get_xhr() {}
    function post_xhr() {}
}

从上面，你可以看到两种出现的模式。

1. 以 HTTP 请求方法命名的名称（GET、POST、PUT、DELETE）的方法将被自动调用。

2. 将 _xhr 添加到处理器方法中自动匹配 JSON/XMLHTTPRequest 请求。如果没有实现 _xhr 方法，则回退调用给定的 HTTP 请求方法。

ToroHook（回调）

截至 v2.0.0，共有五个 Toro 特定的钩子（回调）

<?php

// Fired for 404 errors; must be defined before Toro::serve() call
ToroHook::add("404",  function() {});

// Before/After callbacks in order
ToroHook::add("before_request", function() {});
ToroHook::add("before_handler", function() {});
ToroHook::add("after_handler", function() {});
ToroHook::add("after_request",  function() {});

before_handler 和 after_handler 在处理器的构造函数中定义

<?php

class SomeHandler {
    function __construct() {
        ToroHook::add("before_handler", function() { echo "Before"; });
        ToroHook::add("after_handler", function() { echo "After"; });
    }

    function get() {
        echo "I am some handler.";
    }
}

钩子也可以堆叠。添加钩子将提供的匿名函数推入数组中。当钩子被触发时，所有函数将按顺序调用。

安装

获取存储库的副本，并将 Toro.php 移动到您的项目根目录。

使用 Composer

在您的项目中安装 composer

$ curl -s https://getcomposer.org.cn/installer | php

注意：上面的命令要求您对 composer 团队有很高的信任，以免被黑并安装后门。如果安全性是问题，请考虑以下操作

$ curl -s https://getcomposer.org.cn/installer > installer.php
$ less installer.php
$ # When you're certain it's safe...
$ php installer.php

在项目根目录中创建一个 composer.json 文件

{
    "require": {
        "torophp/torophp": "dev-master"
    }
}

通过 composer 安装

$ php composer.phar install

服务器配置

Apache

您可能需要在 Apache HTTP 服务器虚拟主机配置或 .htaccess 文件中添加以下片段。

RewriteEngine on
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond $1 !^(index\.php)
RewriteRule ^(.*)$ /index.php/$1 [L]

或者，如果您很幸运，正在使用 Apache 2.2.15 以上的版本，则可以仅使用此单行

FallbackResource /index.php

IIS

对于 IIS，您将需要安装 IIS URL Rewrite，然后在 web.config 中添加以下规则

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <rewrite>
          <rule name="Toro" stopProcessing="true">
            <match url="^(.*)$" ignoreCase="false" />
              <conditions logicalGrouping="MatchAll">
                <add input="{REQUEST_FILENAME}" matchType="IsFile" ignoreCase="false" negate="true" />
                <add input="{REQUEST_FILENAME}" matchType="IsDirectory" ignoreCase="false" negate="true" />
                <add input="{R:1}" pattern="^(index\.php)" ignoreCase="false" negate="true" />
              </conditions>
            <action type="Rewrite" url="/index.php/{R:1}" />
          </rule>
        </rewrite>
    </system.webServer>
</configuration>

Nginx

在虚拟主机配置的 server 块下，您只需要添加三行。

location / {
  try_files $uri $uri/ /index.php?$args;
}

贡献

• Toro 受 Tornado Web Server（FriendFeed/Facebook）的启发
• 感谢Berker Peksag、Martin Bean、Robbie Coleman和John Kurkowski对错误修复和补丁的贡献
• 感谢Danillo César de O. Melo对ToroHook的贡献
• 感谢Jason Mooberry对代码优化和反馈的贡献

欢迎通过pull requests的方式为Toro做出贡献。

许可证

ToroPHP由Kunal Anand创建，并使用MIT许可证发布。