README

在开发中使用此包，不要在生产环境中使用！

用于在 Bitrix CMS 上创建简单而强大的 API 的库。

功能

• 自动 API 根检测
• 路由来自 symfony
• 与 PSR-7 中间件调度器兼容的中间件
• 数据验证，请参阅列表
• Bitrix 集成（地图、结果、$APPLICATION）

使用示例

1. 将 API 入口点设置在 $PROJECT_ROOT。例如 %ROOT%/api/public/v1/index.php

use Bitrix\Main\Error;
use Fe3dback\Bapie\Common\ActionResult;
use Fe3dback\Bapie\Helpers\Routing;
use Fe3dback\Bapie\Middleware\RateLimit;
use Fe3dback\Bapie\Request;
use Fe3dback\Bapie\Scope;
use Respect\Validation\Validator;

$bsDir = dirname(__DIR__, 1) . '/.bootstrap';
require sprintf('%s/load.php', $bsDir);

$scope = new Scope(Routing::getPrefixFromDirectory(__DIR__));

// we can set any numbers of middleware, for example limit request rate
$scope->withMiddleware([
    new RateLimit(3, 1),
]);


// define API route (/api/public/v1/common/available-cities)
// our API can be described in external class AvailableCities::class. See examples for details..
$scope->on('common/available-cities', \ACME\APIHandlers\v1\Common\AvailableCities::class);

// define API route (/api/public/v1/lead)
$scope->on('lead', function (): ActionResult {

    // this data {"test":123} will be in Response of API call
    $result = new ActionResult();
    $result->setData([
        'test' => 123
    ]);
    
    // we can define any count of errors
    $result->addError(new Error('test'));
    $result->addError(new Error('123'));
    
    // every API route should return ActionResult object.
    return $result;
});

// define API route (/api/public/v1/lead/create)
$scope->on('lead/create', function (Request $request): ActionResult {

    $result = new ActionResult();

    // Request object is data helper for API
    // for example we can get validated whitelist of variables from $_REQUEST
    $validateResult = $request->map([
        'phone' => Validator::callback(function ($val) {
            // any custom handler
            return \Lean\Phone\Helper::getPhoneFromString($val);
        }),
        'name' => Validator::alpha()->startsWith('h')->length(1, 8)
    ]);

    // we should check validation result after each map/get
    if (!$validateResult->isSuccess()) {
        $result->setValidationErrors($validateResult);
        return $result;
    }

    // if validation is ok, in getData method we can get array of variables
    $params = $validateResult->getData();
    
    // set this variables to API output
    $result->setData([
        'lead' => [
            'phone' => $params['phone'],
            'name' => $params['name']
        ]
    ]);
    return $result;
});

$scope->run();

使用公共加载代码创建引导脚本

%ROOT%/api/.bootstrap/load.php

/** @var CMain $APPLICATION */

$_SERVER['DOCUMENT_ROOT'] = dirname(__DIR__, 2);
$DOCUMENT_ROOT = $_SERVER['DOCUMENT_ROOT'];

define('NO_KEEP_STATISTIC', true);
define('BX_NO_ACCELERATOR_RESET', true);

require $_SERVER['DOCUMENT_ROOT']. '/bitrix/modules/main/include/prolog_before.php';

header(vsprintf('Access-Control-Allow-Origin: %s', [
    '*'
]));

测试 API

https://my-project.loc/api/v1/public/lead 或 https://my-project.loc/api/v1/public/lead/create

包含错误的响应示例

{
    "validation": {
        "name": [
            "name must contain only letters (a-z)",
            "name must start with (\"h\")",
            "name must have a length between 1 and 8"
        ]
    },
    "error": true,
    "http_code": 503,
    "message": "name must contain only letters (a-z), name must start with (\"h\"), name must have a length between 1 and 8"
}

在 ActionClass 中处理 API

// ... in api scope file
$scope->on('common/available-cities', \ACME\APIHandlers\v1\Common\AvailableCities::class);
// ... in api scope file

namespace ACME\APIHandlers\v1\Common;

use Fe3dback\Bapie\Action;
use Fe3dback\Bapie\Common\ActionResult;
use Fe3dback\Bapie\Request;

class AvailableCities extends Action
{
    public function __invoke(Request $request): ActionResult
    {
        $result = new ActionResult();
        
        // get all data from some internal api. 
        // Example: getAllTitles - this method return array 
        // ('Moscow', 'Aksaj', 'New-Yourk', ..)
        $result->setData(\ACME\Regions\Cities::getAllTitles());
        
        return $result;
    }
}