README

Bitrix24 REST API的强大PHP库

构建状态

在GitHub Actions中使用真实Bitrix24门户运行集成测试

BITRIX24-PHP-SDK 文档

BITRIX24-PHP-SDK ✨特性✨

支持两种认证模式

处理市场中的Bitrix24应用程序的认证令牌
处理当前门户的简单集成项目的传入webhook

为开发者提供低级别工具

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

API级别特性

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

性能改进 🚀

使用 PHP 生成器实现批查询 – 持续低内存和低CPI使用
- 批量从Bitrix24读取数据
- 批量向Bitrix24写入数据
- 在一个批次中写入和读取
- 组合批查询到多个实体（进行中）
无计数标志读取

开发原则

良好的开发者体验
- 在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 文件夹中，我们有两种测试类型。在测试文件夹中创建文件 .env.local 并填写来自 .env 的环境变量。

单元测试

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

composer phpunit-run-unit-test

集成测试

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

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

要运行集成测试，您必须

创建新的Bitrix24门户用于开发测试
转到左侧菜单，点击「网站地图」
找到菜单项「开发者资源」
点击菜单项「其他」
点击菜单项「传入webhook」
将所有权限分配给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

PHP静态分析工具 - phpstan

在命令行中调用

 composer phpstan-analyse

提交错误和功能请求

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

许可证

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

作者

Maxim Mesilov - mesilov.maxim@gmail.com - https://twitter.com/mesilov
还可以查看参与此项目的贡献者列表。

需要定制的Bitrix24应用吗？

电子邮件：mesilov.maxim@gmail.com

文档

Bitrix24 API文档 - 俄语

Bitrix24 API文档 - 英语

注册新的Bitrix24账户

俄语

开发原则

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

赞助商

通过在boosty.to/bitrix24-php-sdk上注册来支持bitrix24-php-sdk的发展！

关键特性

SDK层

Service – 与特定实体交互的API接口

责任区域

实体API方法的合同

输入数据

特定API方法的调用签名

返回结果

Core\Response (待讨论)

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

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

如果返回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；
时间 — DTO c 通过比特瑞克斯24服务器请求的时序；
分页 — DTO 分页导航，包含字段 next 和 total；

如果发现错误，将抛出相应的类型化异常。

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

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

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

责任区域

通过网络传输数据
遵守与工作端点相关的合同
“签名”请求使用令牌 \ 如果使用 webhook 进行身份验证，将其传输到相应的输入地址

使用：Symfony HttpClient

输入数据

HTTP 请求类型
参数数组

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

网络数据传输格式

JSON 通过 HTTP/2 或 HTTP/1.1

赞助商

测试

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

单元测试

快速，执行时无需与比特瑞克斯24进行网络交互。

composer phpunit-run-unit-test

集成测试

缓慢的测试覆盖 CRUD 操作的完整生命周期，通过 webhook 连接到比特瑞克斯24。

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

要运行集成测试，您需要

创建一个新的比特瑞克斯24门户以运行测试。
转到左侧菜单并点击“网站地图”。
找到“开发者”菜单
点击菜单“其他”
点击菜单“输入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

演示扎罗夫 / 梅索洛夫比特里克斯24 PHP SDK

维护者

详细信息

README

构建状态

BITRIX24-PHP-SDK 文档

BITRIX24-PHP-SDK ✨特性✨

开发原则

赞助商

架构

抽象层

文件结构

要求

示例

安装

测试

单元测试

集成测试

PHP静态分析工具 - phpstan

提交错误和功能请求

许可证

作者

需要定制的Bitrix24应用吗？

文档

俄语

开发原则

赞助商

关键特性

SDK层

Service – 与特定实体交互的API接口

Core – 调用任意API方法

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

网络数据传输格式

赞助商

测试

单元测试

集成测试

代码库静态分析 - phpstan