README

该软件包是集成引擎的助手。集成文档可在此处找到：这里。

请求

Betalabs\Engine\Request 类负责初始化特定类型请求对象。如果您需要发起 GET 请求调用，您可以

$get = \Betalabs\Engine\Request::get();
$response = $get->send('path/to/api'); // ['data' => [...]]
$statusCode = $get->statusCode(); // 200

也可以注入 Betalabs\Engine\Request

class Object {

  protected $request;
  
  public __construct(\Betalabs\Engine\Request $request)
  {
    $this->request = $request;
  }
  
  public function get()
  {
    $get = $this->request->get();
    $response = $get->send('path/to/api'); // ['data' => [...]]
    $statusCode = $get->statusCode(); // 200
  }

}

可能有五种方法：GET、POST、PUT、PATCH 和 DELETE。在所有方法中，第一个参数是 API 路径。对于 POST、PUT、PATCH 和 DELETE，第二个参数是要发送到 API 的数据，必须以数组的形式发送。例如

$post = \Betalabs\Engine\Request::post();
$post->send(
  'path/to/api',
  [
    'parameter1' => 'value 1',
    'parameter2' => 'value 2',
    // ...
  ]
);

URL 构建器

默认情况下，该软件包始终将 api 前缀添加到所有 URL 中。在上面的示例中，URL 将是（假设 http://engine.url 是端点）：http://engine.url/api/path/to/api。

可以通过使用 setEndpointSuffix() 方法更改此行为，该方法接受一个 string 或 null

$get->setEndpointSuffix(null)->send('path/to/api'); // http://engine.url/path/to/api

配置文件

配置文件应存储在项目的根目录中，并命名为 engine-sdk.xml。

这是其基本格式

<?xml version="1.0" encoding="UTF-8"?>
<engine-sdk>
    <auth>
        <accessToken></accessToken>
    </auth>
    <environment>
        <env></env>
        <endpoint></endpoint>
    </environment>
    <routeProvider>
        <path></path>
        <class></class>
    </routeProvider>
    <permissionProvider>
        <path></path>
        <class></class>
    </permissionProvider>
    <migrationProvider>
        <path></path>
        <class></class>
    </migrationProvider>
    <genesisProvider>
        <path></path>
        <class></class>
    </genesisProvider>
</engine-sdk>

本文档的每个部分都将与其配置相关。

路由

所有路由必须在单个文件中声明，该文件实现 Betalabs\Engine\RouteProvider 接口。route 方法接收一个 Aura\Router\Map 参数，其用法可在此处检查：这里。

路由文件的位置在配置文件中声明

<routeProvider>
    <path></path>
    <class></class>
</routeProvider>

其中 path 是文件的相对路径（基于根目录），class 是类名（如果有命名空间，则包括命名空间）。当类可以自动加载时，不需要 path。

引擎请求

所有对应用的请求都由引擎分发，这些请求可能是由触发器或经过身份验证的用户发起的。然而，对于某些应用，可能需要拥有一些用于非直接由引擎分发的松散请求的端点。

假设我们正在构建一个名为 TagCreator 的为订单创建标签的应用程序；有两个主要启动器：(1) 一个引擎用户正在管理订单，点击“创建标签”；(2) 一个外部系统想要生成一个标签。

在第一种情况下，引擎拥有一个触发器来分发请求到应用程序。在此请求中，引擎将添加一些信息以标识用户想要为哪个订单生成标签（例如 ID），并且可以通过引擎请求收集所有信息以响应用户请求的标签。在第二种情况下，应用程序必须拥有一个准备好的路由以接收通过请求参数传递的所有信息，然后生成标签。

注意在第二种情况下，引擎不采取任何操作，也不用于生成任何数据。要直接向应用程序发出请求，请分发给：http://{app-company}-{app-repository}.engine.url/，其中 {app-company} 和 {app-repository} 是 GitHub 的公司名称和存储库名称（用于在引擎中注册应用程序）。

身份验证

默认情况下，所有请求都使用存储的令牌进行身份验证。可以通过使用 mustNotAuthorize 方法禁用此操作

 $get = \Betalabs\Engine\Request::get();
 $response = $get
  ->mustNotAuthorize()
  ->send('path/to/api');

当然，也可以通过使用 mustAuthorize() 方法启用此操作。

权限

在应用程序启动过程中，引擎会请求权限。可以通过创建一个实现 Betalabs\Engine\PermissionProvider 的类来定义它们。这个类必须有一个添加所有权限的方法。

public function permissions(\Betalabs\Engine\Permissions\Register $register)
{

    $register->add(new \Betalabs\Engine\Permissions\Permission(
        'permission-0-name',
        'Permission #0 name',
        'Permission #0 description'
    ));

    $register->add(new \Betalabs\Engine\Permissions\Permission(
        'permission-1-name',
        'Permission #1 name',
        'Permission #1 description'
    ));

}

此文件的路径在配置文件中声明。

<permissionProvider>
    <path></path>
    <class></class>
</permissionProvider>

其中 path 是文件的相对路径（基于根目录），class 是类名（如果有命名空间，则包括命名空间）。当类可以自动加载时，不需要 path。

如果此节点不存在或未声明任何权限，则在请求权限时，引擎将返回 404 HTTP 状态码。

默认情况下，boot/permission 路由会自动定义并由 SDK 处理。

数据库迁移

在应用程序启动过程中，引擎启动迁移过程。您可以创建一个实现 Betalabs\Engine\MigrationProvider 的类。这个类必须有一个运行迁移的方法。

public function run()
{

    // Migration process

    return new \Betalabs\Engine\Requests\BootResponse(
        true,
        'Success!'
    );
    
}

必须返回一个 Betalabs\Engine\Requests\BootResponse 对象，这样引擎才能记录此过程中的事件。

此文件的路径在配置文件中声明。

<migrationProvider>
    <path></path>
    <class></class>
</migrationProvider>

其中 path 是文件的相对路径（基于根目录），class 是类名（如果有命名空间，则包括命名空间）。当类可以自动加载时，不需要 path。

如果此节点不存在，则 SDK 会通知引擎不需要迁移过程。

默认情况下，boot/database 路由会自动定义并由 SDK 处理。

创世启动

在将应用程序与租户关联的过程中，引擎启动创世过程。您可以创建一个实现 Betalabs\Engine\GenesisProvider 的类。这个类必须有一个运行迁移的方法。

public function run()
{

    // Genesis process

    return new \Betalabs\Engine\Requests\BootResponse(
        true,
        'Success!'
    );
    
}

必须返回一个 Betalabs\Engine\Requests\BootResponse 对象，这样引擎才能记录此过程中的事件。

此文件的路径在配置文件中声明。

<genesisProvider>
    <path></path>
    <class></class>
</genesisProvider>

其中 path 是文件的相对路径（基于根目录），class 是类名（如果有命名空间，则包括命名空间）。当类可以自动加载时，不需要 path。

如果此节点不存在，则 SDK 会通知引擎不需要创世过程。

默认情况下，boot/genesis 路由会自动定义并由 SDK 处理。

开发

在开发过程中，您可能需要手动定义令牌和端点。这可以通过配置文件实现。

端点

默认情况下，所有请求都是针对生产 URL 分派，但是您可以使用配置文件中的 environment 部分来更改此行为。

<environment>
    <env></env>
    <endpoint></endpoint>
</environment>

env 节点可以填充两个值：Sandbox 或 Production；这样，端点 URL 将自动定义。不过，如果您填充了 endpoint 节点，则该值将用作端点 URL，而忽略 env 节点的值。

environment、env 和 endpoint 节点不是必需的。

令牌

您可能想使用特定的令牌来访问引擎 API。这可以通过配置文件中的 auth 部分实现。

<auth>
    <accessToken></accessToken>
</auth>

• accessToken 是用于所有请求的访问令牌字符串。

auth 节点不是必需的，但若要使用 accessToken 子节点，则必须声明它。