README

Php-Rest-Service 是一个简单快速的 PHP 类，用于 RESTful JSON API。

特性

• 易于使用的语法
• 正则表达式支持
• 通过 PHP 异常处理错误
• 通过 PHP 函数签名进行参数验证
• 可以通过 OPTIONS 方法返回所有路由的摘要或一个路由，基于 PHPDoc（如果 OPTIONS 未重写）
• 支持 GET、POST、PUT、DELETE、PATCH、HEAD 和 OPTIONS
• 使用 ?_suppress_status_code=1 隐藏 HTTP 状态码（对于有问题的客户端）
• 支持 ?_method=httpMethod 作为实际 HTTP 方法之外的附加方法。
• 通过 PHP 的 reflection 自动生成

安装

• https://packagist.org.cn/packages/marcj/php-rest-service.
• 更多信息请访问 https://packagist.org.cn/。

创建一个 composer.json

{
    "require": {
        "marcj/php-rest-service": "*"
    }
}

并运行

$ wget https://getcomposer.org.cn/composer.phar
$ php composer.phar install

安装后，您需要在脚本中包含 vendor/autoload.php 以使类可用。

include 'vendor/autoload.php';

要求

• PHP 5.3 及以上版本。
• PHPUnit 以执行测试套件。
• 在 mod_rewrite (.htaccess) 或其他 Web 服务器配置中设置 PATH_INFO

示例配置：Apache Web 服务器

#.htaccess
RewriteEngine On

RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule (.+) index.php/$1 [L,QSA]

nginx Web 服务器

// edit virtualhost /etc/nginx/conf.d/name_virtualhost_file
server {
 .. something params ...
 location / {
  include fastcgi_params;
     
  fastcgi_pass unix:/var/run/php5-fpm.sock;
  fastcgi_param SCRIPT_FILENAME $document_root/index.php;
 }
}

// and add line to /etc/nginx/fastcgi_params
fastcgi_param PATH_INFO $fastcgi_script_name;

使用演示

方式 1. 污秽且快速

use RestService\Server;

Server::create('/')
    ->addGetRoute('test', function(){
        return 'Yay!';
    })
    ->addGetRoute('foo/(.*)', function($bar){
        return $bar;
    })
    ->addPostRoute('foo', function($field1, $field2) {
      // do stuff with $field1, $field2 etc
      // or you can directly get them with $_POST['field1']
    })
->run();

方式 2. 自动收集

index.php:

use RestService\Server;

Server::create('/admin', 'myRestApi\Admin')
    ->collectRoutes()
->run();

MyRestApi/Admin.php:

namespace MyRestApi;

class Admin {

    /**
    * Checks if a user is logged in.
    *
    * @return boolean
    */
    public function getLoggedIn(){
        return $this->getContainer('auth')->isLoggedIn();
    }

    /**
    * @param string $username
    * @param string $password
    * return boolean
    */
    public function postLogin($username, $password){
        return $this->getContainer('auth')->doLogin($username, $password);
    }

    /**
     * @param string $server
     * @url stats/([0-9]+)
     * @url stats
     * @return string
     */
    public function getStats($server = '1'){
        return $this->getServerStats($server);
    }

}

生成以下入口点

    + GET  /admin/logged-in
    + POST /admin/login?username=&password=
    + GET  /admin/stats/([0-9]+)
    + GET  /admin/stats

方式 3. 使用控制器自定义规则

index.php:

use RestService\Server;

Server::create('/admin', new MyRestApi\Admin) //base entry points `/admin`
    ->setDebugMode(true) //prints the debug trace, line number and file if a exception has been thrown.

    ->addGetRoute('login', 'doLogin') // => /admin/login
    ->addGetRoute('logout', 'doLogout') // => /admin/logout

    ->addGetRoute('page', 'getPages')
    ->addPutRoute('page', 'addPage')
    ->addGetRoute('page/([0-9]+)', 'getPage')
    ->addDeleteRoute('page/([0-9]+)', 'deletePage')
    ->addPostRoute('page/([0-9]+)', 'updatePage')

    ->addGetRoute('foo/bar/too', 'doFooBar')

    ->addSubController('tools', \RestApi\Tools) //adds a new sub entry point 'tools' => admin/tools
        ->addDeleteRoute('cache', 'clearCache')
        ->addGetRoute('rebuild-index', 'rebuildIndex')
    ->done()

->run();

MyRestApi/Admin.php:

namespace MyRestApi;

class Admin {
    public function login($username, $password){

        if (!$this->validLogin($username, $password))
            throw new InvalidLoginException('Login is invalid or no access.');

        return $this->getToken();

    }

    public function logout(){

        if (!$this->hasSession()){
            throw new NoCurrentSessionException('There is no current session.');
        }

        return $this->killSession();

    }

    public function getPage($id){
        //...
    }
}

namespace RestAPI;

class Tools {
    /**
    * Clears the cache of the app.
    *
    * @param boolean $withIndex If true, it clears the search index too.
    * @return boolean True if the cache has been cleared.
    */
    public function clearCache($withIndex = false){
        return true;
    }
}

响应

响应体始终是一个数组（默认为 JSON）包含状态码和实际数据。如果抛出了异常，它包含状态码 500、错误类名作为错误以及消息作为消息。

一些示例

+ GET admin/login?username=foo&password=bar
  =>
  {
     "status": "200",
     "data": true
  }

+ GET admin/login?username=foo&password=invalidPassword
  =>
  {
     "status": "500",
     "error": "InvalidLoginException",
     "message": "Login is invalid or no access"
  }

+ GET admin/login
  =>
  {
     "status: "400",
     "error": "MissingRequiredArgumentException",
     "message": "Argument 'username' is missing"
  }

+ GET admin/login?username=foo&password=invalidPassword
  With active debugMode we'll get:
  =>
  {
     "status": "500",
     "error": "InvalidLoginException",
     "message": "Login is invalid or no access",
     "line": 10,
     "file": "libs/RestAPI/Admin.class.php",
     "trace": <debugTrace>
  }

+ GET admin/tools/cache
  =>
  {
     "status": 200,
     "data": true
  }

许可

在 MIT 许可证下授权。有关更多详细信息，请参阅 LICENSE 文件。

查看代码，以获取有关可能性的更多信息。它有很好的文档。