bitrix24 / b24phpsdk
An official PHP library for the Bitrix24 REST API
Installs: 3 812
Dependents: 1
Suggesters: 0
Security: 0
Stars: 39
Watchers: 8
Forks: 15
Open Issues: 33
Requires
- php: 8.2.* || 8.3.*
- ext-curl: *
- ext-intl: *
- ext-json: *
- darsyn/ip: ^4 || ^5
- fig/http-message-util: ^1
- giggsey/libphonenumber-for-php: ^8
- mesilov/moneyphp-percentage: ^0.2
- moneyphp/money: ^3 || ^4
- nesbot/carbon: ^3
- psr/log: ^2 || ^3
- symfony/console: ^6 || ^7
- symfony/dotenv: ^6 || ^7
- symfony/event-dispatcher: ^6 || ^7
- symfony/filesystem: ^6 || ^7
- symfony/finder: ^6 || ^7
- symfony/http-client: ^6 || ^7
- symfony/http-client-contracts: ^2 || ^3
- symfony/http-foundation: ^6 || ^7
- symfony/mime: ^6 || ^7
- symfony/uid: ^6 || ^7
Requires (Dev)
- ergebnis/composer-normalize: ^2
- fakerphp/faker: ^1
- friendsofphp/php-cs-fixer: ^3
- lendable/composer-license-checker: ^1.2
- monolog/monolog: ^3
- nyholm/psr7: ^1.8
- openai-php/client: 0.10.*
- phpstan/phpstan: 1.11.7
- phpunit/phpunit: ^10 || ^11
- rector/rector: ^1
- roave/security-advisories: dev-master
- symfony/debug-bundle: ^6 || ^7
- symfony/process: ^6 || ^7
- symfony/stopwatch: ^6 || ^7
- symfony/var-dumper: ^6 || ^7
- typhoon/reflection: ^0.4
- dev-main
- 1.2.0
- 1.1.0
- 1.0
- dev-dev
- dev-feature/130-add-article-how-to-contribute
- dev-feature/56-improve-dx-crm-robots
- dev-bugfix/123-add-flusher-implementation
- dev-feature/120-add-php-8-4-support
- dev-feature/115-add-userid-and-tokens
- dev-feature/111-add-token-validate-guard
- dev-bugfix/101-fix-elements-order
- dev-bugfix/53-batch-entity-item-get
- dev-bugfix/103-user-get-batch
- dev-20-finish-crm-scope
- dev-feature/97-add-deprecated-methods-list
This package is auto-updated.
Last update: 2025-03-30 20:59:11 UTC
README
An official PHP library for the Bitrix24 REST API
Build status
CI\CD status on master |
---|
Integration tests run in GitHub actions with real Bitrix24 portal
Installation
Install the latest version with
composer require bitrix24/b24phpsdk
If You work on Windows:
- please use WSL - Windows Subsystem for Linux
- if your filesystem is NTFS, You can disable flag
git config --global core.protectNTFS false
for checkout folders started with dot.
Or add "bitrix24/b24phpsdk": "1.2.*"
to composer.json
of your application.
B24PhpSdk ✨FEATURES✨
Support both auth modes:
- work with auth tokens for mass-market Bitrix24 applications
- work with incoming webhooks for simple integration projects for a single Bitrix24 account
Domain core events:
- Access Token expired
- Url of a Bitrix24 account domain changed
API - level features
- Auto renew access tokens
- List queries with «start=-1» support
- offline queues
Performance improvements 🚀
- Batch queries implemented with PHP Generators – constant low memory and low CPI usage:
- batch read data from bitrix24
- batch write data to bitrix24
- 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
- Internal documentation for B24PhpSdk
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
: serverhandler 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
see index.php file
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());
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 information about application installation, linked with Bitrix24 Account with auth tokens. Optional can store links to:- Client contact person: client person who responsible for application usage
- Bitrix24 Partner contact person: partner contact person who supports client and configure application
- Bitrix24 Partner: partner who supports client portal
ContactPersons
– Store information about person who installed application.Bitrix24Partners
– Store information about Bitrix24 Partner who supports client portal and install or configure application.
Steps:
- Create own entity of this bounded contexts.
- Implement all methods in contract interfaces.
- Test own implementation behavior with contract-tests
tests/Unit/Application/Contracts/*
– examples.
Tests
Tests locate in folder tests
and we have two test types.
In folder tests create file .env.local
and fill environment variables from .env
.
PHP Static Analysis Tool – phpstan
Call in command line
make lint-phpstan
PHP Static Analysis Tool – rector
Call in command line for validate
make lint-rector
Call in command line for fix codebase
make lint-rector-fix
Unit tests
Fast, in-memory tests without a network I\O For run unit tests you must call in command line
make test-unit
Integration tests
Slow tests with full lifecycle with your test Bitrix24 account via webhook.
❗️Do not run integration tests with production Bitrix24 accounts
For running integration test you must:
- Create new Bitrix24 account for development tests.
- Go to left menu, click «Sitemap».
- Find menu item «Developer resources».
- Click on menu item «Other».
- Click on menu item «Inbound webhook».
- Assign all permisions with webhook and click «save» button.
- Create file
/tests/.env.local
with same settings, see comments in/tests/.env
file.
APP_ENV=dev BITRIX24_WEBHOOK=https:// your Bitrix24 webhook url INTEGRATION_TEST_LOG_LEVEL=500
- call in command line
make test-integration-core make test-integration-scope-telephony make test-integration-scope-workflows make test-integration-scope-user
Submitting bugs and feature requests
Bugs and feature request are tracked on GitHub
License
B24PhpSdk is licensed under the MIT License - see the MIT-LICENSE.txt
file for details