2017 © Pedro PelĆ”ez
 

library bitrix24-php-sdk

A powerfull PHP library for the Bitrix24 REST API

image

mesilov/bitrix24-php-sdk

A powerfull PHP library for the Bitrix24 REST API

  • Wednesday, June 20, 2018
  • by mesilov
  • Repository
  • 37 Watchers
  • 153 Stars
  • 19,988 Installations
  • PHP
  • 3 Dependents
  • 0 Suggesters
  • 71 Forks
  • 29 Open issues
  • 13 Versions
  • 13 % Grown

The README.md

Bitrix24 REST API PHP SDK

License Total Downloads Latest Stable Version, (*1)

A powerful PHP library for the Bitrix24 REST API, (*2)

Build status

CI\CD status on master
phpstan check
unit-tests status
integration-tests status

Integration tests run in GitHub actions with real Bitrix24 portal, (*3)

BITRIX24-PHP-SDK āœØFEATURESāœØ

Support both auth modes:, (*4)

  • [x] work with auth tokens for Bitrix24 applications in marketplace
  • [x] work with incoming webhooks for simple integration projects for current portal

Domain core events:, (*5)

  • [x] Access Token expired
  • [x] Bitrix24 portal domain url changed

API - level features, (*6)

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

Performance improvements šŸš€, (*7)

  • [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
  • 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

Requirements

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

Installation

Add "mesilov/bitrix24-php-sdk": "2.x" to composer.json of your application. Or clone repo to your project., (*8)

Examples

Work with webhook

  1. Go to /examples/webhook folder
  2. Open console and install dependencies
composer install
  1. Open Bitrix24 portal: Developer resources ā†’ Other ā†’ Inbound webhook
  2. Open example file and insert webhook url into $webhookUrl

see example.php file
, (*9)

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

, (*10)

  1. Call php file in shell
php -f example.php

Work with local application

  1. Go to /examples/local-application folder
  2. Open console and install dependencies
composer install
  1. Start local development server
sudo php -S 127.0.0.1:80
  1. Expose local server to public via ngrok and remember temporally public url ā€“ https://****.ngrok-free.app 
ngrok http 127.0.0.1
  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
  1. Open Bitrix24 portal: 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
  2. 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\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';
?>



    Application is worked, auth tokens from bitrix24:
    = print_r($_REQUEST, true) ?>




<?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. Save local application in Bitrix24 tab and press Ā«OPEN APPLICATIONĀ» button., (*11)

Create application for Bitrix24 marketplace

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

  • 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:, (*13)

  1. Create own entity of this bounded contexts.
  2. Implement all methods in contract interfaces.
  3. 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., (*14)

PHP Static Analysis Tool ā€“ phpstan

Call in command line, (*15)

make lint-phpstan

PHP Static Analysis Tool ā€“ rector

Call in command line for validate, (*16)

make lint-rector

Call in command line for fix codebase, (*17)

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, (*18)

make test-unit

Integration tests

Slow tests with full lifecycle with your test Bitrix24 portal via webhook., (*19)

ā—ļøDo not run integration tests with production portals, (*20)

For run integration test you must:, (*21)

  1. Create new Bitrix24 portal for development tests.
  2. Go to left menu, click Ā«SitemapĀ».
  3. Find menu item Ā«Developer resourcesĀ».
  4. Click on menu item Ā«OtherĀ».
  5. Click on menu item Ā«Inbound webhookĀ».
  6. Assign all permisions with webhook and click Ā«saveĀ» button.
  7. Create file /tests/.env.local with same settings, see comments in /tests/.env file.
APP_ENV=dev
BITRIX24_WEBHOOK=https:// your portal webhook url
INTEGRATION_TEST_LOG_LEVEL=500
  1. 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, (*22)

License

bitrix24-php-sdk is licensed under the MIT License - see the MIT-LICENSE.txt file for details, (*23)

Authors

Maksim Mesilov - mesilov.maxim@gmail.com, (*24)

See also the list of contributors which participated in this project., (*25)

Sponsors

boosty.to/bitrix24-php-sdk, (*26)

Need custom Bitrix24 application?

Email to mesilov.maxim@gmail.com for private consultations or dedicated support., (*27)

The Versions

20/06 2018

dev-master

9999999-dev https://github.com/mesilov/bitrix24-php-sdk

A powerfull PHP library for the Bitrix24 REST API

  Sources   Download

MIT

The Requires

 

The Development Requires

by Maxim Mesilov

api php rest bitrix24

27/04 2018

dev-dev

dev-dev https://github.com/mesilov/bitrix24-php-sdk

A powerfull PHP library for the Bitrix24 REST API

  Sources   Download

MIT

The Requires

 

The Development Requires

by Maxim Mesilov

api php rest bitrix24

27/04 2018

dev-issue#108

dev-issue#108 https://github.com/mesilov/bitrix24-php-sdk

A powerfull PHP library for the Bitrix24 REST API

  Sources   Download

MIT

The Requires

 

The Development Requires

by Maxim Mesilov

api php rest bitrix24

11/04 2018

0.6.0

0.6.0.0 https://github.com/mesilov/bitrix24-php-sdk

A powerfull PHP library for the Bitrix24 REST API

  Sources   Download

MIT

The Requires

 

The Development Requires

by Maxim Mesilov

api php rest bitrix24

11/04 2018

dev-task#102

dev-task#102 https://github.com/mesilov/bitrix24-php-sdk

A powerfull PHP library for the Bitrix24 REST API

  Sources   Download

MIT

The Requires

 

The Development Requires

by Maxim Mesilov

api php rest bitrix24

18/02 2018

dev-task#96

dev-task#96 https://github.com/mesilov/bitrix24-php-sdk

A powerfull PHP library for the Bitrix24 REST API

  Sources   Download

MIT

The Requires

 

The Development Requires

by Maxim Mesilov

api php rest bitrix24

30/10 2017

dev-issue#86

dev-issue#86 https://github.com/mesilov/bitrix24-php-sdk

A powerfull PHP library for the Bitrix24 REST API

  Sources   Download

MIT

The Requires

 

The Development Requires

by Maxim Mesilov

api php rest bitrix24

30/10 2017

dev-issue#84

dev-issue#84 https://github.com/mesilov/bitrix24-php-sdk

A powerfull PHP library for the Bitrix24 REST API

  Sources   Download

MIT

The Requires

 

The Development Requires

by Maxim Mesilov

api php rest bitrix24

30/10 2017

dev-issue#82

dev-issue#82 https://github.com/mesilov/bitrix24-php-sdk

A powerfull PHP library for the Bitrix24 REST API

  Sources   Download

MIT

The Requires

 

The Development Requires

by Maxim Mesilov

api php rest bitrix24

29/10 2017

dev-issue#79

dev-issue#79 https://github.com/mesilov/bitrix24-php-sdk

A powerfull PHP library for the Bitrix24 REST API

  Sources   Download

MIT

The Requires

 

The Development Requires

by Maxim Mesilov

api php rest bitrix24

24/10 2017

dev-issue#77

dev-issue#77 https://github.com/mesilov/bitrix24-php-sdk

A powerfull PHP library for the Bitrix24 REST API

  Sources   Download

MIT

The Requires

 

The Development Requires

by Maxim Mesilov

api php rest bitrix24

16/07 2016

0.4.0

0.4.0.0 https://github.com/mesilov/bitrix24-php-sdk

A powerfull PHP library for the Bitrix24 REST API

  Sources   Download

MIT

The Requires

 

The Development Requires

by Maxim Mesilov

api php rest bitrix24

24/06 2015

v0.2.0

0.2.0.0 https://github.com/mesilov/bitrix24-php-sdk

A powerfull PHP library for the Bitrix24 REST API

  Sources   Download

MIT

The Requires

  • php >=5.3.2
  • ext-json *
  • ext-curl *

 

by Maxim Mesilov

api php rest bitrix24