README

Bitrix24 REST API的强大PHP库

构建状态

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

BITRIX24-PHP-SDK ✨特性✨

支持两种认证模式

与市场中的Bitrix24应用程序的认证令牌一起工作
与当前门户的简单集成项目的入站webhook一起工作

域核心事件

访问令牌过期
Bitrix24门户域名URL已更改

API级功能

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

性能改进 🚀

使用PHP生成器实现批量查询 - 持续低内存和低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: *

安装

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

示例

处理webhook

转到 /examples/webhook 文件夹
在控制台中安装依赖项

composer install

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

查看示例.php文件

declare(strict_types=1);

use Bitrix24\SDK\Services\ServiceBuilderFactory;
use Symfony\Component\EventDispatcher\EventDispatcher;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Monolog\Processor\MemoryUsageProcessor;

require_once 'vendor/autoload.php';

$webhookUrl = 'INSERT_HERE_YOUR_WEBHOOK_URL';

$log = new Logger('bitrix24-php-sdk');
$log->pushHandler(new StreamHandler('bitrix24-php-sdk.log'));
$log->pushProcessor(new MemoryUsageProcessor(true, true));

// create service builder factory
$b24ServiceFactory = new ServiceBuilderFactory(new EventDispatcher(), $log);
// init bitrix24-php-sdk service from webhook
$b24Service = $b24ServiceFactory->initFromWebhook($webhookUrl);

// work with interested scope
var_dump($b24Service->getMainScope()->main()->getCurrentUserProfile()->getUserProfile());
// get deals list and address to first element
var_dump($b24Service->getCRMScope()->lead()->list([], [], ['ID', 'TITLE'])->getLeads()[0]->TITLE);

在shell中调用PHP文件

php -f example.php

处理本地应用程序

转到 /examples/local-application 文件夹
在控制台中安装依赖项

composer install

启动本地开发服务器

sudo php -S 127.0.0.1:80

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

ngrok http 127.0.0.1

从ngrok检查公网URL并看到带有 200 状态码的 x-powered-by 标头。

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门户：开发资源 → 其他 → 本地应用程序并创建新的本地应用程序
- 类型: 服务器
- 处理器路径: https://****.ngrok-free.app/index.php
- 初始安装路径: https://****.ngrok-free.app/install.php
- 菜单项文本: 测试本地应用程序
- 作用域: 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\AuthToken;
use Bitrix24\SDK\Core\Credentials\ApplicationProfile;
use Bitrix24\SDK\Services\ServiceBuilderFactory;
use Monolog\Handler\StreamHandler;
use Monolog\Logger;
use Monolog\Processor\MemoryUsageProcessor;
use Symfony\Component\EventDispatcher\EventDispatcher;
use Symfony\Component\HttpFoundation\Request;

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

$log = new Logger('bitrix24-php-sdk');
$log->pushHandler(new StreamHandler('bitrix24-php-sdk.log'));
$log->pushProcessor(new MemoryUsageProcessor(true, true));

$b24ServiceBuilderFactory = new ServiceBuilderFactory(new EventDispatcher(), $log);
$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 = $b24ServiceBuilderFactory->initFromRequest($appProfile, AuthToken::initFromPlacementRequest($request), $request->get('DOMAIN'));

var_dump($b24Service->getMainScope()->main()->getCurrentUserProfile()->getUserProfile());
// get deals list and address to first element
var_dump($b24Service->getCRMScope()->lead()->list([], [], ['ID', 'TITLE'])->getLeads()[0]->TITLE);

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

为 Bitrix24 市场创建应用程序

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

Bitrix24Accounts — 存储身份验证令牌并提供处理 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 门户。
转到左侧菜单，点击“网站地图”。
找到菜单项“开发者资源”。
单击菜单项“其他”。
单击菜单项“入站 webhook”。
分配所有权限并单击“保存”按钮。
创建文件 /tests/.env.local，具有相同的设置，请参阅 /tests/.env 文件中的注释。

APP_ENV=dev
BITRIX24_WEBHOOK=https:// your portal 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 上跟踪

许可证

bitrix24-php-sdk 在 MIT 许可证下授权 - 有关详细信息，请参阅 MIT-LICENSE.txt 文件

作者

Maksim Mesilov - mesilov.maxim@gmail.com

还可以查看参与此项目的贡献者列表。

赞助商

boosty.to/bitrix24-php-sdk

需要定制的 Bitrix24 应用程序吗？

通过 mesilov.maxim@gmail.com 发送电子邮件以获取私人咨询或专用支持。

mesilov / bitrix24-php-sdk

维护者

详细信息