search

bitrix24 / b24phpsdk

Bitrix24 PHP SDK for REST API
MIT License
22 stars 7 forks source link

readme

Bitrix24 REST API PHP SDK

Total Downloads Latest Stable Version

An official PHP library for the Bitrix24 REST API

Build status

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

Integration tests run in GitHub actions with real Bitrix24 portal

Installation

Install the latest version with

composer require bitrix24/b24phpsdk

Or add "bitrix24/b24phpsdk": "1.1.*" to composer.json of your application.

B24PhpSdk ✨FEATURES✨

Support both auth modes:

Domain core events:

API - level features

Performance improvements 🚀

Development principles

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

Examples

Work with webhook

  1. Go to /examples/webhook folder
  2. Open console and install dependencies
composer install
  1. Open Bitrix24 account: Developer resources → Other → Inbound webhook
  2. 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'));
  1. Call php file in shell
php -f example.php

Work with local application

  1. Go to /examples/local-app 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 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
  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\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());

  1. 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:

Steps:

  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.

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:

  1. Create new Bitrix24 account 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 Bitrix24 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

License

B24PhpSdk is licensed under the MIT License - see the MIT-LICENSE.txt file for details