README

Bitrix24 REST API的强大PHP库

构建状态

CI\CD 状态在 `master`

在GitHub actions中运行与真实Bitrix24门户的集成测试

BITRIX24-PHP-SDK 文档

BITRIX24-PHP-SDK ✨特性✨

支持两种认证模式

[x] 与Bitrix24应用市场中的认证令牌一起工作
[x] 与当前门户的简单集成项目的传入webhooks一起工作

为开发者提供低级别工具

核心事件域
- [x] 访问令牌过期
- [ ] Bitrix24门户域url更改
[ ] 速率限制策略
[ ] 安全方法的重试策略

API级别的功能

[x] 自动续订访问令牌
[ ] 支持start=-1的列表查询
[ ] 离线队列

性能改进 🚀

使用PHP生成器实现批量查询 – 常规的低内存和低CPI使用
- [x] 批量从Bitrix24读取数据
- [x] 批量向Bitrix24写入数据
- [ ] 一个批量包中写入和读取
- [ ] 复合批量查询到多个实体（进行中）
[ ] 不使用count标志的读取

开发原则

良好的开发者体验
- IDE中方法自动完成
- 类型化方法调用签名
- 方法调用结果的类型化
- 典型操作的辅助工具
良好的文档
- 包含指向官方文档链接的特定方法的操作文档
- SDK操作文档
性能优先
- 对客户端代码的影响最小
- 能够在恒定的内存消耗下处理大量数据的能力
- 使用批量请求高效操作API
现代技术堆栈
- 基于 Symfony HttpClient
- 实际的PHP版本语言特性
可靠的
- 测试覆盖率：单元、集成、合同
- 针对不同操作模式的典型示例，并且它们针对内存\性能进行了优化

赞助商

通过boosty.to/bitrix24-php-sdk帮助bitrix24-php-sdk的发展！

架构

抽象层

- http protocol
- json data
- symfony http client
- \Bitrix24\SDK\Core\ApiClient - work with b24 rest-api endpoints
    input: arrays \ strings
    output: Symfony\Contracts\HttpClient\ResponseInterface, operate with strings
    process: network operations 
- \Bitrix24\SDK\Services\Main - work with b24 rest-api entities
    input: arrays \ strings (?) or queries?
    output: b24 response dto
    process: b24 entities, operate with

文件结构

    /Core
        ApiClient.php - default api-client, work on http abstraction layer, return - Symfony\Contracts\HttpClient\ResponseInterface
    /Services
        /CRM
            /Deals
                /Client
                    Deals.php
                /Exceptions
        /Tasks
        … 
        Main.php - default bitrix24 rest api service provide basic funcions, work with data transfer objects

要求

php: >=7.4
ext-json: *
ext-curl: *

示例

安装

将 "mesilov/bitrix24-php-sdk": "2.x" 添加到您的应用程序的 composer.json。或者将仓库克隆到您的项目中。

测试

测试位于 tests 文件夹中，我们有两种测试类型。在tests文件夹中创建文件 .env.local 并从 .env 中填充环境变量。

单元测试

快速、内存中的测试，没有网络I/O。运行单元测试必须在命令行中调用

composer phpunit-run-unit-test

集成测试

慢速测试，与您的测试Bitrix24门户通过webhook进行完整生命周期。

❗️不要在生产门户上运行集成测试❗️

要运行集成测试，您必须

创建新的Bitrix24门户用于开发测试
转到左侧菜单，点击“网站地图”
找到菜单项“开发者资源”
点击菜单项“其他”
点击菜单项“入站Webhook”
将所有权限分配给Webhook并点击“保存”按钮
创建与/tests/.env文件中相同的设置，参见/tests/.env文件中的注释。

APP_ENV=dev
BITRIX24_WEBHOOK=https:// your portal webhook url
INTEGRATION_TEST_LOG_LEVEL=500

在命令行中调用

composer composer phpunit-run-integration-tests

PHP静态分析工具 – phpstan

在命令行中调用

 composer phpstan-analyse

提交错误报告和功能请求

错误报告和功能请求在GitHub上跟踪

许可证

bitrix24-php-sdk遵循MIT许可证 - 详细信息请参阅MIT-LICENSE.txt文件。

俄语

开发原则

良好的DX（开发者体验）
- 在IDE级别自动完成方法
- 方法调用的类型化签名
- 方法调用的类型化结果 - 使用原生类型：int、array、bool、string
- 帮助完成典型操作
良好的文档
- 具体方法的文档，包含对官方文档的链接
- SDK使用文档
性能
- 对客户端代码的最小影响
- 能够以常量内存消耗处理大量数据
- 使用批处理请求有效工作于API
现代技术栈
- 用于网络操作和异步工作的库
- PHP新版本的功能
可靠的
- 测试覆盖：单元测试、集成测试、契约测试
- 具有典型示例的文档，适用于不同工作模式，并针对内存和速度进行了优化

赞助商

通过在boosty.to/bitrix24-php-sdk上订阅来帮助bitrix24-php-sdk的发展！

关键特性

SDK层

服务 – 与特定实体工作的API接口

责任区域

实体API方法的合同

输入数据

特定API方法的调用签名

返回结果

Core\Response (待讨论) 讨论中

根据方法可能返回不同的结果

布尔类型的结果执行操作
创建实体的整型标识符
实体 + 带有前缀UF_的用户字段类型为数组
实体数组
空数组作为空过滤器的结果。

如果返回Core\Response，则在客户端代码中会出现问题

客户端代码中存在获取返回结果的冗长链

// добавили сделку в Б24
$dealId = $dealsService->add($newDeal)->getResponseData()->getResult()->getResultData()[0];
// получили массив сделок
$deals = $dealsService->list([], [], [], 0)->getResponseData()->getResult()->getResultData();

缺少与调用方法相关的类型化返回结果。

期望

 add(array $newDeal):int // идентификатор новой сделки
 list(array $order, array $filter, array $select, int $start):array //массив сделок + постраничка
 get(int $dealId):array // конкретная сделка

当前实现 – 返回统一的结果

add(array $newDeal):Core\Response
list(array $order, array $filter, array $select, int $start):Core\Response

Core – 调用任意API方法

责任区域

调用任意API方法
处理API级别的错误
如果收到错误expired_token，则请求新令牌并重新请求

输入数据

string $apiMethod – api方法名称
array $parameters = [] – 方法参数

返回结果：Core\Response – 统一的对象包装器，包含

Symfony\Contracts\HttpClient\ResponseInterface — 服务器响应对象，可能是异步的
Core\Commands\Command — 执行的命令\参数信息，用于解析批量请求。

使用 Response::getResponseData 方法来获取API请求的结果，该方法通过调用 Symfony\Contracts\HttpClient::toArray 方法解码响应体。返回的是API服务器标准化的DTO ResponseData，包含字段

Result - 包含请求执行结果的DTO；
Time — 包含请求通过Bitrix24服务器时间的DTO；
Pagination — 包含分页导航的DTO，包含字段 next 和 total；

在检测到领域级别错误的情况下，将抛出相应的类型化异常。

Result 对象包含一个 getResultData 方法，它返回一个包含API请求执行结果的数组。根据调用的方法，可能包含

布尔类型的结果执行操作
创建实体的整型标识符
实体 + 带有前缀UF_的用户字段类型为数组
实体数组
空数组作为空过滤器的结果。

ApiClient — 处理网络和API服务器端点的操作

责任区域

通过网络传输数据
遵守与操作端点签订的合同
使用令牌“签名”请求，如果使用Webhook进行身份验证，则将其传递到适当的接收地址

使用：Symfony HttpClient

输入数据

HTTP请求类型
参数数组

返回结果：— Symfony\Contracts\HttpClient\ResponseInterface

网络数据传输格式

JSON通过HTTP/2或HTTP/1.1

赞助商

测试

测试位于 tests 文件夹中，分为两种类型：单元测试和集成测试。在 tests 文件夹中创建 .env.local 文件并填写 .env 文件中的变量。

单元测试

快速，执行时无需与Bitrix 24进行网络交互。

composer phpunit-run-unit-test

集成测试

慢速，测试覆盖了CRUD操作的完整生命周期，连接到Bitrix 24是通过Webhook进行的。

❗️不要在生产门户上运行集成测试，它们会删除所有您的数据❗️

要运行集成测试，您需要

创建一个新的Bitrix24门户以运行测试。
转到左侧菜单并点击“网站地图”。
找到“开发者”菜单
点击菜单“其他”
点击菜单“入站Webhook”
选择所有需要的扩展并点击“保存”按钮。
创建 /tests/.env.local 文件并添加环境变量，这些变量需要从 /tests/.env 文件中复制。

APP_ENV=dev
BITRIX24_WEBHOOK=https:// your portal webhook url
INTEGRATION_TEST_LOG_LEVEL=500

从命令行启动。

composer composer phpunit-run-integration-tests

代码库静态分析 – phpstan

从命令行启动。

 composer phpstan-analyse

sw24 / bitrix24-php-sdk

维护者

详细信息

README

构建状态

BITRIX24-PHP-SDK 文档

BITRIX24-PHP-SDK ✨特性✨

开发原则

赞助商

架构

抽象层

文件结构

要求

示例

安装

测试

单元测试

集成测试

PHP静态分析工具 – phpstan

提交错误报告和功能请求

许可证

作者

需要定制的Bitrix24应用程序？

文档

俄语

开发原则

赞助商

关键特性

SDK层

服务 – 与特定实体工作的API接口

Core – 调用任意API方法

ApiClient — 处理网络和API服务器端点的操作

网络数据传输格式

赞助商

测试

单元测试

集成测试

代码库静态分析 – phpstan