Bitrix24 REST API PHP SDK

An official PHP library for the Bitrix24 REST API

SDK Versions

This library ships two major versions that coexist on separate branches:

| | v1 (main branch) | v3 (v3 branch) | |---|---|---| | PHP | 8.2, 8.3, 8.4 | 8.4, 8.5 | | API endpoints | {portal}/rest/{user_id}/{token}/{method} | {portal}/rest/api/{user_id}/{token}/{method} | | New REST methods | — | ✅ | | Breaking changes | No | ✅ | | Semver | 1.* | 3.* | | Status | Stable / production-ready | Active development |

Which version should I use?

v1 — choose this for PHP 8.2–8.4 projects, production deployments, or when you don't need the newest Bitrix24 API methods.
v3 — choose this for PHP 8.4+ projects that need access to new REST API methods and are comfortable adopting breaking changes.

Build status

| CI\CD check | main | v3 | |---|---|---| | allowed licenses | | | | php-cs-fixer | | | | phpstan | | | | rector | | | | deptrac | — | | | unit tests | | |

Integration tests run in GitHub actions with real Bitrix24 portal

Installation

Install the stable v1 version (PHP 8.2+):

composer require bitrix24/b24phpsdk:"^1.0"

Install the new v3 version (PHP 8.4+, breaking changes):

composer require bitrix24/b24phpsdk:"^3.0"

If you work on Windows:

please use WSL - Windows Subsystem for Linux
if your filesystem is NTFS, you can disable the flag git config --global core.protectNTFS false for checkout folders starting with a dot.

Branch status

| Branch | Purpose | |---|---| | main | Stable v1.x production releases | | dev | v1.x integration and pre-release testing | | v3 | Stable v3.x production releases | | v3-dev | Active v3 development with breaking changes |

Each major version has its own dev branch. Cross-version changes are applied via cherry-pick — branches are never merged across major versions.

B24PhpSdk ✨FEATURES✨

Support both auth modes:

[x] work with auth tokens for mass-market Bitrix24 applications
[x] work with incoming webhooks for simple integration projects for a single Bitrix24 account

Domain core events:

[x] Access Token expired
[x] Url of a Bitrix24 account domain changed

API - level features

[x] Auto renew access tokens
[x] List queries with «start=-1» support
[ ] offline queues

Performance improvements 🚀

[x] Batch queries implemented with PHP Generators – constant low memory and low CPI usage:
[x] batch read data from bitrix24
[x] batch write data to bitrix24
[x] read without count flag

Development principles

Good developer experience
- auto-completion of methods at the IDE
- typed method call signatures
- typed results of method calls
- helpers for typical operations
Good documentation
- documentation on the operation of a specific method containing a link to the official documentation
- documentation for working with the SDK
Performance first:
- minimal impact on client code
- ability to work with large amounts of data with constant memory consumption
- efficient operation of the API using batch requests
Modern technology stack
- based on Symfony HttpClient
- actual PHP versions language features
Reliable:
- test coverage: unit, integration, contract
- typical examples typical for different modes of operation and they are optimized for memory \ performance

Architecture

Abstraction layers

- 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

Documentation

Bitrix24 API documentation - English

Requirements

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

Examples

Work with webhook

Go to /examples/webhook folder
Open console and install dependencies

composer install

Open Bitrix24 account: Developer resources → Other → Inbound webhook
Open example file and insert webhook url into $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'));

Call php file in shell

php -f example.php

Work with local application

Go to /examples/local-app folder
Open console and install dependencies

composer install

Start local development server

sudo php -S 127.0.0.1:80

Expose local server to public via ngrok and remember temporally public url – https://****.ngrok-free.app

ngrok http 127.0.0.1

Check public url from ngrok and see x-powered-by header with 200 status-code.

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

Open Bitrix24 account: Developer resources → Other → Local application and create new local application:
- type: server
- handler path: https://****.ngrok-free.app/index.php
- Initial installation path: https://****.ngrok-free.app/install.php
- Menu item text: Test local app
- scope: crm
Save application parameters in index.php file:
- Application ID (client_id) — BITRIX24_PHP_SDK_APPLICATION_CLIENT_ID
- Application key (client_secret) — BITRIX24_PHP_SDK_APPLICATION_CLIENT_SECRET
- Assing permitions (scope) — BITRIX24_PHP_SDK_APPLICATION_SCOPE

<details> <summary>see index.php file</summary>

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());

</details> 8. Save local application in Bitrix24 tab and press «OPEN APPLICATION» button.

Create application for Bitrix24 marketplace

if you want to create application you can use production-ready contracts in namespace Bitrix24\SDK\Application\Contracts:

Bitrix24Accounts — Store auth tokens and provides methods for work with Bitrix24 account.
ApplicationInstallations — Store informa

B24phpsdk

Install / Use

README