README

APIx 是一个用于构建 RESTful Web 服务的（微）框架。它将与您的现有框架/应用程序并行运行，无需过多麻烦。

其一些特性

• 支持许多数据输入，例如 GET/POST 参数、XML、JSON、CSV 等
• 提供各种输出表示，如 XML、JSONP、HTML、PHP 等
• 提供按需资源文档，使用 GET /help 或 'OPTIONS'。
• 使用注解来文档化和设置服务行为。
• 处理大多数 HTTP 方法，包括 PUT、DELETE、HEAD、OPTIONS 和 PATCH（部分支持 TRACE）。
• 捆绑了许多插件和适配器，用于身份验证和 ACL、缓存等。
• 遵循标准，如 rfc2616、rfc2616、rfc2617、rfc2617、rfc2388、rfc2388、rfc2854、rfc2854、rfc4627、rfc4627、rfc4329、rfc4329、rfc2046、rfc2046、rfc3676、rfc3676、rfc3023、rfc3023 等...
• 使用 X-HTTP-Method-Override（谷歌推荐）和/或使用查询参数（可自定义）提供 方法覆盖。
• 支持 内容协商（也可以覆盖）。
• 利用网络缓存的优势——支持 HEAD 测试。
• 可作为独立 PHAR 文件，或通过 Composer 或作为 PEAR pear 软件包提供。
• 针对 PHP 5.x 和 7.x 进行持续集成。
• 阅读 文档！

待办事项

• 自生成 API 资源测试。
• 添加对 WSDL 2.0 / WADL 的支持。
• 最终实现 SOAP（和 XML_RPC）桥接。

请随时评论、发送拉取请求和补丁...

基本用法

<?php
    require 'apix.phar';

    // Instantiate the server (using the default config)
    $api = new Apix\Server;

    // Create a GET handler $name is required
    $api->onRead('/hello/:name', function($name) {
        return array('Hello ' . $name);
    });

    $api->run();

使用注解的另一个示例。

    // $type and $stuff are required parameters.
    // $optional is not mandatory.
    $api->onRead('/search/:type/with/:stuff/:optional',
        /**
         * Search for things by type that have stuff.
         *
         * @param     string  $type         A type of thing to search upon
         * @param     string  $stuff        One or many stuff to filter against
         * @param     string  $optional     An optional field
         * @return    array
         * @api_auth  groups=clients,employes,admins users=franck,jon
         * @api_cache ttl=12mins tags=searches,indexes
         */
        function($type, $stuff, $optional = null) {
            // some logic
            return $results;
        }
    );

    $api->run();

高级用法

路由

路由定义了资源路径，一旦匹配，将调用相应资源的控制器和专用处理程序。

从资源控制器返回的任何值，通常是关联数组，将成为响应的主体。

本质上，一个路由由以下组成

1. 一个与HTTP头部方法相对应的路由控制器

    onCreate()   ->   POST          |        onModify()   ->   PATCH
    onRead()     ->   GET           |        onHelp()     ->   OPTIONS
    onUpdate()   ->   PUT           |        onTest()     ->   HEAD
    onDelete()   ->   DELETE        |        onTrace()    ->   TRACE

1. 一个与Request-URI相对应的路由路径
   • 它可以代表一个特定且静态的资源实体，例如

     /search/france/paris

   • 它也可以是动态的，可能包括一个或多个由冒号:表示的变量，例如

     /search/:country/:city

控制器定义

资源控制器可以声明为以下两种方式之一

• 某个用户定义类中的公共方法
• 在运行时定义的闭包/lambda函数（类似Sinatra风格）

它将使用

• 变量名来继承路由路径的值，例如从/category/:name继承的$name。

• 类型提示来注入当前作用域中Apix的任何对象，例如Request、Response等...

  有关可用性的详细信息，请参阅Apix的[文档] apixdoc。

以下是一个展示这些内容的示例

    $api->onRead('/category/:name', function(Request $request, $name) {

        // retrieve a named param
        $page = (int) $request->getParam('page');

        // retrieve the body params, parsed from XML, JSON, ...
        $params = $request->getBodyParams();

        ...

        return $list_defs;
    });

配置

检查随分发版提供的config.dist.php文件中的内联注释。

引导

要引导一个Apix服务器，添加所需的文件并创建一个Apix\Server实例。

可以将专用配置文件注入到Apix服务器中

    <?php
        require 'apix.phar';

        $api = new Apix\Server(require 'my_config.php');

        $api->run();

PHAR控制台

Apix PHAR分发包含一个内置的控制台。尝试在命令行中调用api.phar文件，如下所示

$ php apix.phar --help

Web服务器配置

请使用分发版内提供的虚拟主机文件之一，并按照注释中提供的相关说明设置您的Web服务器环境。

TODO：将ngynx和lighttpd文件添加到分发版中。

注解

注解可以用来定义资源实体的许多方面。

以下是一个自解释的示例

    <?php
        $api->onRead('/download/:app/version/:version',
            /**
             * Retrieve the named sotfware
             * Anyone can use this resource entity to download apps. If no
             * version is specified the latest revision will be returned.
             *
             * @param     string    $app        The name of the app
             * @param     string    $version    The version number.
             * @return    array     A response array.
             *
             * @api_auth  groups=public
             * @api_cache ttl=1week tags=downloads
             */
            function($app, $version=null) {
                // ...
                return array(
                    $app => 'the version string of software.'
                );
            }
        );

        $api->onCreate('/upload/:software',
            /**
             * Upload a new software
             * Admin users use this resource entity to upload new software.
             *
             * @param      Request  $request   The Server Request object.
             * @param      string   $software
             * @return     array    A response array.
             *
             * @api_auth   groups=admin users=franck
             * @api_cache  purge=downloads
             */
            function(Request $request, $software) {
                // ...
            }
        );

        $api->run();

安装

Apix需要PHP 5.3或更高版本。

• [Phar文件] phar（推荐）

• 如果您正在创建一个依赖于Apix的本地组件

  • 请更新您的composer.json文件

    {
      "require": {
        "apix/apix": "0.3.*"
      }
    }

  • 或按以下方式更新您的package.xml文件

    <dependencies>
      <required>
        <package>
          <name>apix_server</name>
          <channel>pear.ouarz.net</channel>
          <min>1.0.0</min>
          <max>1.999.9999</max>
        </package>
      </required>
    </dependencies>

• 对于使用PEAR的系统级安装

    sudo pear channel-discover pear.ouarz.net
    sudo pear install --alldeps ouarz/apix

有关更多详细信息，请参阅pear.ouarz.net。

测试

要运行单元测试套件，只需在主目录中运行phpunit即可。

集成和功能测试也包含在src/tests中。

许可证

APIx采用新BSD许可证——有关完整许可证详情，请参阅LICENSE.txt。

  _|_|    _|_|    _|     _|      _|
_|    _| _|    _|         _|    _|
_|    _| _|    _| _|        _|_|
_|_|_|_| _|_|_|   _| _|_|   _|_|
_|    _| _|       _|      _|    _|
_|    _| _|       _|     _|      _|