README

Virge::Api 允许简单创建 API 端点。

Virge::Api 允许定义 get/post/put/delete 方法，以及通过定义自定义验证器来链式调用 API 身份验证方法。

入门指南

要使用 Virge::Api，你应该从一个默认的 Virge::Project 开始。

composer create-project virge/project ./my-project

这将创建一个空的 Virge::Reactor，并创建设置 Api 所需的框架。

整个目录需要在您的 web 服务器上存在，但入口目录应该是 ./public 目录，这可以创建符号链接。

# assuming the project exists in /var/www/my-project 
ln -s /var/www/my-project/public /var/www/html

这也可以使用 docker 完成。

docker run -d -v $PWD:/var/www/my-project -p 3000:80 siosphere/php7

容器启动后，您需要运行上面提到的符号链接命令。

Virge::Project 还需要重写，对于 apache，您可以在 /etc/httpd/conf.d/ 中创建 myproject.conf 来设置。

<Directory "/var/www/html">
    Options FollowSymLinks
    AllowOverride All
</Directory>

重启 docker 容器或 apache 后，您可以在浏览器中访问 localhost:3000。您可能会得到 500 错误、空白白页或 404 页面，具体取决于配置。这是因为没有设置路由或路由。

Hello Api

我们需要将 Virge::Api 作为胶囊包含进来，并将包添加到我们的项目中。

composer require virge/api

要创建我们的第一个 API 路由，我们需要创建我们的第一个胶囊。胶囊与 Reactor 注册，并将自动为我们加载配置文件，加载服务、控制器和 API 定义文件。

在 src 目录下，我们可以创建一个 MyProject 目录。我们需要在这个目录下创建 MyProjectCapsule.php。

<?php
namespace MyProject;

class MyProjectCapsule extends \Virge\Core\Capsule
{
    public function registerCapsule()
    {
        
    }
}

现在我们需要将我们的胶囊添加到 app/Reactor.php 中，添加 MyProject\MyProjectCapsule() 以及 Virge\Api\Capsule()。

...
parent::registerCapsules(array(
    new MyProject\MyProjectCapsule(),

    new Virge\Api\Capsule(),
    new Virge\Cli\Capsule(),
    new Virge\Cron\Capsule(),
    new Virge\Database\Capsule(),
    new Virge\ORM\Capsule(),
    new Virge\Router\Capsule(),
));
...

在文件中，我们还可以定义哪些 API 版本有效。在我们的父类::registerCapsules 调用之后，让我们启用我们的 API 的版本 1。

Virge\Api::versions([1]);

我们还需要告诉 composer 自动加载我们的胶囊，更新 bootstrap.php 以添加我们的命名空间。

/**
 * Add namespaces one by one, this would be the start of your namespace, for
 * example, if I had src/Siosphere, my namespace would be Siosphere
 */
$namespaces = array(
    'MyProject',
);

现在我们可以注册我们的 API 方法，创建 src/MyProject/resources/config/api.php 文件。

<?php

use Virge\Api;

Api::get('hello')
    ->version('all', function() {
        return 'world';
    })
;

访问 https://:3000/api/v/1/hello 现在应该返回一个包含 "world" 的 JSON 响应。

API 也可以调用控制器函数，这些方法通过 Virge::Router 请求对象传递，允许您获取 JSON 请求体、GET 和 POST 字段以及 URL 参数。

API 验证

您可以定义自定义 API 验证器，这些验证器只是返回 true 或 false 的回调函数，以允许访问。例如，为了将我们的 hello API 端点更新为需要 API 密钥，我们可以在 config/api.php 中添加一个验证器：

Api::verifier('api_key', function($request) {
    return $request->get('apiKey') === '123';
});

Api::get('hello')
    ->verify('api_key')
    ->version('all', function() {
        return 'world';
    })
;

在浏览器中访问 https://:3000/api/v/1/hello 将返回一个不成功的响应，但添加 apiKey: https://:3000/api/v/1/hello?apiKey=123 将允许您访问该页面。

方法可以有任意多的验证器，并且所有验证器都必须返回 true，函数才能被调用，方法才能成功。

API 参数

API 方法名称也可以包含 URL 参数，这些参数通过请求对象访问。

Api::get('hello/{name}')
    ->version('all', function($request) {
        return sprintf("Hello: %s", $request->getUrlParam('name'));
    })
;

访问 https://:3000/api/v/1/hello/bob 现在将返回一个包含 "Hello: bob" 的 JSON 主体。