README

Bitrix24 REST API的官方PHP库

构建状态

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

安装

使用以下命令安装最新版本：

composer require bitrix24/b24phpsdk

或将"bitrix24/b24phpsdk": "1.1.*"添加到您的应用composer.json文件中。

B24PhpSdk ✨特性✨

支持两种认证模式

与为大众市场Bitrix24应用程序的认证令牌一起工作
与单个Bitrix24账户的简单集成项目一起使用传入的webhook

核心事件域

访问令牌过期
Bitrix24账户域的URL已更改

API级功能

自动续期访问令牌
支持“start=-1”的列表查询
离线队列

性能提升 🚀

使用PHP Generators实现批量查询 – 持续低内存和低CPI使用
批量从Bitrix24读取数据
批量将数据写入Bitrix24
读取时不带计数标志

开发原则

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

架构

抽象层

- http2 protocol via json data structures
- 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\* - work with b24 rest-api entities
    input: arrays \ strings
    output: b24 response dto
    process: b24 entities, operate with immutable objects

文档

要求

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

示例

处理webhook

转到/examples/webhook文件夹
打开控制台并安装依赖项

composer install

打开Bitrix24账户：开发者资源 → 其他 → 入站webhook
打开示例文件并将webhook URL插入到$webhookUrl

declare(strict_types=1);

use Bitrix24\SDK\Services\ServiceBuilderFactory;

require_once 'vendor/autoload.php';

// init bitrix24-php-sdk service from webhook
$b24Service = ServiceBuilderFactory::createServiceBuilderFromWebhook('INSERT_HERE_YOUR_WEBHOOK_URL');

// call some method
var_dump($b24Service->getMainScope()->main()->getApplicationInfo()->applicationInfo());
// call core for method in not implemented service
var_dump($b24Service->core->call('user.current'));

在shell中调用PHP文件

php -f example.php

处理本地应用程序

转到/examples/local-app文件夹
打开控制台并安装依赖项

composer install

启动本地开发服务器

sudo php -S 127.0.0.1:80

通过ngrok将本地服务器公开给公众，并记住临时的公开URL – https://****.ngrok-free.app

ngrok http 127.0.0.1

从ngrok检查公开URL并看到带有x-powered-by头和200状态码的响应。

curl https://****.ngrok-free.app -I
HTTP/2 200 
content-type: text/html; charset=UTF-8
date: Mon, 26 Aug 2024 19:09:24 GMT
host: ****.ngrok-free.app
x-powered-by: PHP/8.3.8

打开Bitrix24账户：开发者资源 → 其他 → 本地应用程序并创建新的本地应用程序
- type: 服务器
- handler path: https://****.ngrok-free.app/index.php
- 初始安装路径: https://****.ngrok-free.app/install.php
- 菜单项文本: 测试本地应用
- scope: crm
在index.php文件中保存应用程序参数
- 应用程序ID (client_id) — BITRIX24_PHP_SDK_APPLICATION_CLIENT_ID
- 应用程序密钥 (client_secret) — BITRIX24_PHP_SDK_APPLICATION_CLIENT_SECRET
- 分配权限 (scope) — BITRIX24_PHP_SDK_APPLICATION_SCOPE

见index.php文件

declare(strict_types=1);

use Bitrix24\SDK\Core\Credentials\ApplicationProfile;
use Bitrix24\SDK\Services\ServiceBuilderFactory;
use Symfony\Component\HttpFoundation\Request;

require_once 'vendor/autoload.php';
?>
    <pre>
    Application is worked, auth tokens from bitrix24:
    <?= print_r($_REQUEST, true) ?>
</pre>
<?php

$appProfile = ApplicationProfile::initFromArray([
    'BITRIX24_PHP_SDK_APPLICATION_CLIENT_ID' => 'INSERT_HERE_YOUR_DATA',
    'BITRIX24_PHP_SDK_APPLICATION_CLIENT_SECRET' => 'INSERT_HERE_YOUR_DATA',
    'BITRIX24_PHP_SDK_APPLICATION_SCOPE' => 'INSERT_HERE_YOUR_DATA'
]);

$b24Service = ServiceBuilderFactory::createServiceBuilderFromPlacementRequest(Request::createFromGlobals(), $appProfile);

var_dump($b24Service->getMainScope()->main()->getCurrentUserProfile()->getUserProfile());

8. 在Bitrix24标签页中保存本地应用程序并点击“打开应用程序”按钮。

为Bitrix24市场创建应用程序

如果您想创建应用程序，可以使用在命名空间 Bitrix24\SDK\Application\Contracts 中的生产就绪合同

Bitrix24Accounts — 存储认证令牌并为与Bitrix24账户关联的认证令牌提供方法以操作Bitrix24账户。
ApplicationInstallations — 存储有关应用程序安装的信息，与具有认证令牌的Bitrix24账户相关联。可选可存储到
- 客户联系人：负责应用程序使用的客户人员
- Bitrix24合作伙伴联系人：支持客户并配置应用程序的合作伙伴联系人
- Bitrix24合作伙伴：支持客户门户的合作伙伴
ContactPersons – 存储有关安装应用程序的人员的信息。
Bitrix24Partners – 存储有关Bitrix24合作伙伴的信息，该合作伙伴支持客户门户并安装或配置应用程序。

步骤

为这个有界上下文创建自己的实体。
在合同接口中实现所有方法。
使用合同测试 tests/Unit/Application/Contracts/* – 示例来测试自己的实现行为。

测试

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

PHP静态分析工具 – phpstan

在命令行中调用

make lint-phpstan

PHP静态分析工具 – rector

在命令行中调用以验证

make lint-rector

在命令行中调用以修复代码库

make lint-rector-fix

单元测试

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

make test-unit

集成测试

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

❗️不要使用生产Bitrix24账户运行集成测试

为了运行集成测试，您必须

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

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

在命令行中调用

make test-integration-core
make test-integration-scope-telephony
make test-integration-scope-workflows
make test-integration-scope-user

提交错误和功能请求

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

许可证

B24PhpSdk采用MIT许可证授权 - 有关详细信息，请参阅 MIT-LICENSE.txt 文件

bitrix24 / b24phpsdk

维护者

详细信息