Skip to content

README.md

Latest commit

 

History

History
188 lines (141 loc) · 9.28 KB

README.md

File metadata and controls

188 lines (141 loc) · 9.28 KB

bitrix24-php-sdk documentation

Basic necessary knowledge

Full list of buzzwords, patterns and dependencies used in SDK.

Bitrix24

PHP

PHP standards for interoperability

Design patterns

  • Fabric: Create objects without specifying exact class
  • Observer: Implement publish-subscribe architecture
  • Builder: Design pattern that lets you construct complex objects step by step
  • Strategy: Behavioral design pattern that lets you define a family of algorithms, put each of them into a separate class, and make their objects interchangeable.

Software architecture

Infrastructure

  • composer: PHP dependency management tool
  • make: Automate build processes
  • env-files: Store configuration in the environment
  • yaml: YAML is a data serialisation language designed to be directly writable and readable by humans.
  • GitHub Actions: automate tasks throughout the software development lifecycle.
  • ngrok: Share your local app without deploying
  • PHP built-in web-server: This web server is designed to aid application development. It may also be useful for testing purposes or for application demonstrations that are run in controlled environments.
  • cURL: Command line tool and library for transferring data with URLs

Code quality and refactoring

  • phpunit: PHP testing framework
  • phpstan: PHP static analysis tool
  • rector: PHP automated refactoring tool

Additional PHP dependencies

Symfony components

  • symfony/http-client: low-level HTTP client with support for both PHP stream wrappers and cURL. It provides utilities to consume APIs and supports synchronous and asynchronous operations.
  • symfony/console: eases the creation of beautiful and testable command line interfaces.
  • symfony/dotenv: parses .env files to make environment variables stored in them accessible via $_SERVER or $_ENV.
  • symfony/filesystem: provides platform-independent utilities for filesystem operations and for file/directory paths manipulation.
  • symfony/mime: allows manipulating the MIME messages used to send emails and provides utilities related to MIME types.
  • symfony/finder: finds files and directories based on different criteria (name, file size, modification time, etc.) via an intuitive fluent interface.
  • symfony/http-client-contracts: a set of abstractions extracted out of the Symfony components.
  • symfony/http-foundation: defines an object-oriented layer for the HTTP specification.
  • symfony/event-dispatcher: provides tools that allow your application components to communicate with each other by dispatching events and listening to them.
  • symfony/uid: provides utilities to work with unique identifiers (UIDs) such as UUIDs and ULIDs.

Authorisation

List of all supported methods

All methods list, this list build automatically.

Call unsupported methods in SDK

In SDK all methods grouped by scope. If service still not implemented in SDK, You can directly call from SDK core:

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 core if method not implemented in services
var_dump($b24Service->core->call('user.current')->getResponseData()->getResult());

After that You can create new issue on GitHub – 🚀 SDK Feature Request, and we add new method support in services.

Application development

If you build application based on bitrix24-php-sdk You can use some domain contracts for interoperability. They store in folder src/Application/Contracts.

Available 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.
  • ContactPersons – Store information about person who installed application.
  • Bitrix24Partners – Store information about Bitrix24 Partner who supports client portal and install or configure application.

Errors handling

In SDK implemented exceptions hierarchy, they stored in Bitrix24\SDK\Core\Exceptions folder.

declare(strict_types=1);

use Bitrix24\SDK\Core\Exceptions\InvalidArgumentException;
use Bitrix24\SDK\Services\ServiceBuilderFactory;

require_once 'vendor/autoload.php';
try {
    // init bitrix24-php-sdk service from webhook
    $b24Service = ServiceBuilderFactory::createServiceBuilderFromWebhook('INSERT_HERE_YOUR_WEBHOOK_URL');

    // call unknown method and throw  exception
    $b24Service->core->call('Unknown method');
} catch (InvalidArgumentException $exception) {
    print(sprintf('ERROR IN CONFIGURATION OR CALL ARGS: %s', $exception->getMessage()) . PHP_EOL);
    print($exception::class.PHP_EOL);
    print($exception->getTraceAsString());
} catch (Throwable $throwable) {
    print(sprintf('FATAL ERROR: %s', $throwable->getMessage()) . PHP_EOL);
    print($throwable::class.PHP_EOL);
    print($throwable->getTraceAsString());
}

Development

Update internal documentation: regenerate methods list

  1. Create file /tests/.env.local
    • set env variable BITRIX24_WEBHOOK
    • set env variable DOCUMENTATION_DEFAULT_TARGET_BRANCH, default value blob/master
  2. Call make file
make build-documentation
  1. Commit updated file /docs/EN/Services/bitrix24-php-sdk-methods.md