Текущее положение дел
Разработчики из Битрикс24 релизят новые методы и расширяют старые — добавляют в них поля

Задача
Сделать автоматическую проверку соответствия актуальности phpdoc документации во всех сущностях bitrix24-php-sdk.
Пример аннотации для контакта

/**
* @property-read array<int,int>|null $COMPANY_IDS
* @property-read int $CREATED_BY_ID
* @property-read CarbonImmutable $DATE_CREATE
* @property-read CarbonImmutable $DATE_MODIFY
* @property-read int|null $FACE_ID
* @property-read bool $EXPORT
* @property-read Email[] $EMAIL
* @property-read int $ID
* @property-read bool $HAS_EMAIL
*/

Эти аннотации используются в работе IDE и именно они обеспечивают полноту и правильность автокомплита.

Решение
Автоматическая сверка аннотаций с набором полей который возрващает Битрикс24.

Для чтения аннотаций в рантайме используется библиотека https://github.com/typhoon-php/typhoon

В phpunit добавлен кастомный ассерт

trait CustomBitrix24Assertions
{
    /**
     * @param array<int, non-empty-string> $fieldCodesFromApi
     * @param class-string $resultItemClassName
     * @return void
     */
    protected function assertBitrix24AllResultItemFieldsAnnotated(array $fieldCodesFromApi, string $resultItemClassName): void
    {
        sort($fieldCodesFromApi);

        // parse keys from phpdoc annotation
        $props = TyphoonReflector::build()->reflectClass($resultItemClassName)->properties();
        $propsFromAnnotations = [];
        foreach ($props as $meta) {
            if ($meta->isAnnotated() && !$meta->isNative()) {
                $propsFromAnnotations[] = $meta->id->name;
            }
        }
        sort($propsFromAnnotations);

        $this->assertEquals($fieldCodesFromApi, $propsFromAnnotations,
            sprintf('in phpdocs annotations for class %s we not found fields from actual api response: %s',
                $resultItemClassName,
                implode(', ', array_values(array_diff($fieldCodesFromApi, $propsFromAnnotations)))
            ));
    }
}

и теперь на любую сущность Битрикс24 можно навесить новый тип теста — проверка актуальности документации

public function testAllSystemFieldsAnnotated(): void
{
    $propListFromApi = (new Core\Fields\FieldsFilter())->filterSystemFields(array_keys($this->contactService->fields()->getFieldsDescription()));
    $this->assertBitrix24AllResultItemFieldsAnnotated($propListFromApi, ContactItemResult::class);
}

Задача
Есть REST-API на 1000+ методов, требуется:
1. отслеживать, какие методы SDK поддерживает и какой % покрытия
2. генерировать документацию для разработчиков
3. давать структурированный JSON для возможной кодогенерации силами LLM (планы)

Решение
Нам помогут атрибуты – https://www.php.net/manual/en/language.attributes.php
Вешаем на каждый метод кастомный атрибут ApiEndpointMetadata:

#[ApiEndpointMetadata(
    'crm.contact.add',
    'https://training.bitrix24.com/rest_help/crm/contacts/crm_contact_add.php',
    'Creates a new contact.'
)]
public function add(array $fields, array $params = ['REGISTER_SONET_EVENT' => 'N']): AddedItemResult
{
    return new AddedItemResult(
        $this->core->call(
            'crm.contact.add',
            [
                'fields' => $fields,
                'params' => $params,
            ]
        )
    );
}

И получаем возможность их распарсить и собрать из них документацию.
В части методов используются генераторы, поэтому там есть проблема с выводом правильного типа возвращаемого результата. Её мы решаем конечно же за счёт использования typhoon-php

 * @return Generator<int, ContactItemResult> <==== ПРАВИЛЬНЫЙ ТИП    
 * @throws BaseException
 */
#[ApiBatchMethodMetadata(
    'crm.contact.list',
    'https://training.bitrix24.com/rest_help/crm/contacts/crm_contact_list.php',
    'Returns in batch mode a list of contacts'
)]
public function list(array $order, array $filter, array $select, ?int $limit = null): Generator <==== общий тип Generator
{
    $this->log->debug(
        'list',
        [
            'order' => $order,
            'filter' => $filter,
            'select' => $select,
            'limit' => $limit,
        ]
    );
    foreach ($this->batch->getTraversableList('crm.contact.list', $order, $filter, $select, $limit) as $key => $value) {
        yield $key => new ContactItemResult($value);
    }
}

Что в итоге
1. Все методы аннотированы и генерируется документация
2. Видим % покрытия методов и можем планировать работы и цели по улучшению покрытия

Bitrix24 API-methods count: 1131
Supported in bitrix24-php-sdk methods count: 160
Coverage percentage: 14.15% 🚀

Релиз 2.0-beta.3 — https://github.com/mesilov/bitrix24-php-sdk/releases/tag/2.0-beta.3

Added
❗️ add scope bizproc and services for work with workflows
add method Bitrix24\SDK\Core\Credentials\AccessToken::initFromWorkflowRequest
add method Bitrix24\SDK\Core\Credentials\AccessToken::initFromEventRequest
add Bitrix24\SDK\Infrastructure\Filesystem\Base64Encoder for work with base64 encoding
add Bitrix24\SDK\Core\Exceptions\FileNotFoundException if file not found
add Bitrix24\SDK\Core\Exceptions\MethodConfirmWaitingException if api call waiting for confirm
add Bitrix24\SDK\Core\Exceptions\UserNotFoundOrIsNotActiveException exception if user not found, or it is not active
add Bitrix24\SDK\Core\Result\UserInterfaceDialogCallResult result of call UI
add Bitrix24\SDK\Core\Result\EmptyResult empty result
add IncomingRobotRequest wrapper for data from crm-robot request
add IncomingWorkflowRequest wrapper for data from biz proc activity request
add Bitrix24\SDK\Core\Credentials::isWebhookContext - for check is current context init from webhook
add method Bitrix24\SDK\Application\Requests\Events\AbstractEventRequest::getEventId - for get event id
add method Bitrix24\SDK\Application\Requests\Events\AbstractEventRequest::getAuth - get event auth token
add method Bitrix24\SDK\Application\Requests\Events\EventAuthItem - event auth token
add method Bitrix24\SDK\Application\Requests\Events\EventInterface - for event fabrics
add method Bitrix24\SDK\Infrastructure\Filesystem\Base64Encoder::encodeCallRecord(string $filename): string - for
work with call records
add class Bitrix24\SDK\Services\Main\Service\EventManager - improve DX for work with events lifecycle bind or unbind
add method Bitrix24\SDK\Services\Main\Common\EventHandlerMetadata - improve DX for work with install events
add enum Bitrix24\SDK\Services\CRM\Common\Result\DiscountType
add exception Bitrix24\SDK\Core\Exceptions\WrongAuthTypeException – if you use wrong auth type.
add class fields filter Bitrix24\SDK\Core\Fields\FieldsFilter for fields filtration in result array.
improve DX – add Rector for improve code quality and speed up releases cycle
improve DX – add attributes for generate documentation and calculate methods coverage.

Changed
❗️ migrate from ramsey/uuid to symfony/uid
❗️ migrate from DateTimeImmutable to CarbonImmutable from carbon
❗️ refactor Bitrix24\SDK\Application\Contracts:
❗️ update scope telephony, scope fully rewritten
update scope im, add service Notify
change signature Bitrix24\SDK\Core\Credentials\AccessToken::getRefreshToken()?string; - add nullable option for
event tokens
change signature Bitrix24\SDK\Core\Commands\Command::getName():?string renamed to getId():string
add fields and change return types in Bitrix24\SDK\Services\CRM\Deal\Result\DealProductRowItemResult
change typehints in Bitrix24\SDK\Services\CRM\Activity\Service\Activity::add

Deleted
remove class Bitrix24\SDK\Application\Requests\Events\OnApplicationInstall\Auth
remove class Bitrix24\SDK\Application\Requests\Events\OnApplicationUninstall\Auth
remove method Bitrix24\SDK\Core\Response\Response::__destruct
remove interface Bitrix24\SDK\Services\Telephony\Common\StatusSipCodeInterface
remove class Bitrix24\SDK\Services\Telephony\Common\StatusSipRegistrations
remove class Bitrix24\SDK\Services\Telephony\Common\TypeAtc

Bugfix
fix typehint for Bitrix24 User entity with field ID
fix default arguments for Bitrix24 User get method
fix limit argument not worked in batch list and read model

Good news, everyone!

Коллеги, есть важная новость.

Давно зарекоменовавший себя PHP SDK от @mesilov теперь становится официальным SDK для разработки на PHP.

Актуальная версия доступна в официальном репозитории https://github.com/bitrix24/b24phpsdk

Для тех, кто еще не использовал библиотеку, можно перечислить основные преимущества:

1. Красотища. Ну, то есть, code completion в IDE, причем даже на уровне параметров методов. Это не избавляет от необходимости почитать документацию, но это точно защищает от глупых ошибок при формировании запросов. И ускоряет разработку

2. Эффективная работа со списочными методами. Мы все знаем, что это не простая штука - вытащить стотыщпяссот записей. В SDK не просто есть поддержка batch (она и в CRest как бы есть), там есть правильное использование возможностей языка, что позволяет значительно экономить память, что для веб-приложений может являться критичным.

3. Типизированные параметры и данные. Если метод работает с полем типа Дата, то это прямо дата в терминах PHP, а не просто строка с особыми циферками.

4. Подкапотные сценарии для тиражных приложений вроде автообновления токенов. Причем, поскольку это все же SDK, а не заготовка приложения, вы сами решаете, что с токенами делать и где хранить. Это несколько повышает порог входа для тех, кто вообще не в теме, но мы его закроем готовыми примерами How to

И т.д. Модно, грамотно, молодежно (зачеркнуто) по-стариковски. То есть, проверено реальным опытом в сложных и высоконагрузочных проектах.

Из нашей статистики могу сказать, что этот SDK является наиболее массовой библиотекой после CRest, но теперь мы будем стараться, чтобы при разработке приложений и локальных интеграций разработчики все же использовали новый SDK. Он просто лучше и надежнее.

Репа открыта, ждем issues, pull-requests, примеров - планов много.

Привет, вот и пришёл момент, когда репозиторий https://github.com/bitrix24/b24phpsdk/releases уходит вперёд.

🥲 Через некоторое время я архивирую свой репозиторий и добавлю уведомление, что библиотека переехала к вендору 🚲

Сегодня выпущен релиз библиотеки 1.1.0, в нём достаточно много улучшений направленных на повышение удобства работы новых разработчиков.
Часть фабричных методов обзавелась дефолтными значениями, что ещё больше упростило код.

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

Добавлены примеры, они все лежат в папке examples, по хорошему, её надо выносить в отдельный репозиторий. Итак, сейчас уже есть:
- работа с вебхуком /examples/webhook
- локальное приложение без хранения токена /examples/local-app
- локальное приложение с хранением токена examples/local-app-with-token-storage
- регистрация плейсмента /examples/local-app-placement

Сделаны фабрики событий приходящих от Битрикс24, теперь можно инстанцировать события одной строчкой.

// get application_token for check event security signature
// see https://apidocs.bitrix24.com/api-reference/events/safe-event-handlers.html
// on first lifecycle event OnApplicationInstall application token is null and file with auth data doesn't exists
// we save application_token and all next events will be validated security signature
$event = RemoteEventsFabric::init(self::getLog())->createEvent($incomingRequest, $applicationToken);

я: дорогая, мне нужно подумать и решить сложную задачу на пару часов
тоже я: *выбираю шрифт для ASCII-арт заставки в течении 40 минут*

🚀 b24phpsdk 1.2.0

Ключевые изменения
— добавлена поддержка компаний CRM\Company\Service и связанных сущностей CRM\Company\Service\CompanyUserfield, CRM\Company\Service\CompanyCompanyContact и т.д.
— добавлена поддержка перечислений CRM\Enum\Service\Enum
— в CI добавлена проверка зависимостей на соответствие лиценизиям MIT, BSD-3-Clause, Apache.
— исправлено 100500 ошибок в аннотациях типов и возвращаемых результатах (простите, без этого никак), в интеграционные тесты добавлены специальные методы:
assertBitrix24AllResultItemFieldsAnnotated - проверяет, что в phpdoc аннотации перечислены все поля возвращаемые методом *.fields
assertBitrix24AllResultItemFieldsHasValidTypeAnnotation - проверяет, что тип из phpdoc-аннотации правильно маппится на тип уже на уровне PHP.
Теперь следующие релизы sdk будут тестироваться и на такие вот вещи и это потенциально снизит человеческий фактор, когда вендор добавил поле, а ты забыл его аннотировать.

Огромное спасибо Валентину Удальцову, автору канала https://t.iss.one/phpyh за библиотеку typhoon/reflection вся эта магия работает поверх неё. Следующий шаг — сделать автоматический вывод возвращаемых типов на основании данных из аннотации, а не как сейчас — по символьному коду поля 🫠.
— потихоньку заносим PhpCsFixer
— много минорных правок

Статистика по покрытию

Bitrix24 API-methods count: 1135
Supported in bitrix24-php-sdk methods count: 191
Coverage percentage: 16.83% 🚀
Supported in bitrix24-php-sdk methods with batch wrapper count: 22

https://github.com/bitrix24/b24phpsdk/releases/tag/1.2.0

Да, всё так, напоминание от Сергея

🌿 Про статические анализаторы и входящие данные в библиотеках

Использование статических анализаторов существенно повышает качество кода, но при использовании их в библиотеках нужно учитывать один важный нюанс — нельзя доверять типу входящих данных.

В приложении мы можем использовать расширенную типизацию (в случае PHP и Psalm — с помощью аннотаций) для параметров функций, методов, конструкторов классов и быть уверенными, что параметры будут ожидаемых типов (конечно же если не забываем запускать статический анализ, а ещё лучше настроили его в CI).

Например, у нас есть класс, который в конструкторе ожидает массив из объектов и мы указываем это в аннотации:

final class Test {
    /**
     * @param object[] $objects
     */
    public function __construct(array $objects) {
        // ...
    }
}

При попытке создать объект с аргументами, которые соответствуют типизации языка, но не соответствуют расширенной типизации (например, new Test([1, 2]);), анализатор выдаст ошибку.

Но если тот же самый класс мы решим вынести в библиотеку, то у нас сразу исчезает уверенность, что параметр $objects будет именно массивом объектов. Разработчики, использующие нашу библиотеку:

• могут не использовать статические анализаторы,
• могут использовать другой анализатор.

А это значит, что ошибка будет обнаружена, возможно, не сразу и совсем в другом месте, так как код библиотеки будет работать неожиданным образом.

❗️В библиотеках все входящие параметры нужно проверять и не полагаться на статический анализ.

Current mood

🚀 b24phpsdk 1.3.0

➕Добавлено
— поддержка PHP 8.4
— метод Services\Main\Service::guardValidateCurrentAuthToken проверяющий, что идет работа с валидным OAUTH сервером.
— скоуп entity
— сервис Services\Entity\Service\Item
— сервис Services\Entity\Service\Entity
— скоупы humanresources.hcmlink и sign.b2e
— метод Core\Credentials\Scope::contains
— метод Core\Credentials\Scope::getAvailableScopeCodes
— сервис Services\CRM\VatRates\Service\Vat
— сервис Services\CRM\Contact\Service\ContactCompany
— сервис Services\CRM\Requisites\Service\Requisite
— сервис Services\CRM\Requisites\Service\RequisitePreset
— сервис Services\User\Service\Batch
— сервис Services\AI\Engine\Service\Engine
— класс Core\Exceptions\LogicException
DX: консольная команда b24-dev:show-sdk-coverage-statistics
DX: класс Bitrix24\SDK\Deprecations\DeprecatedMethods со списком методов, которые помечены как депрекейтед
DX: все консольные команды исполняются в докер-контейнере php-cli
DX: добавлено кеширование конфига phpstan
DX: добавлена статья «How to Contribute to Bitrix24 PHP SDK»

🪚Изменено
— добавлеен nullable аргумент $scope в методе Bitrix24\SDK\Attributes\Services::getSupportedInSdkApiMethods,
— изменения в методе Application\Contracts\Bitrix24Accounts\Entity::updateApplicationVersion
— ошибки в Bitrix24AccountInterfaceTest, изменены сигнатуры вызовов

🧰 Исправлено
— ошибка в Bitrix24\SDK\Core\Batch для методов: user.get, entity.item.get, entity.item.update
— ошибка в Bitrix24\SDK\Core\ApiClient
— ошибки в ApplicationInstallationRepositoryInterfaceTest

🔐Безопасность
- Добавлен метод Services\Main\Service::guardValidateCurrentAuthToken для проверки авторизационного токена путем вызова метода app.info на OAUTH сервере вендора. Можно использовать для проверки входящих токенов из плейсментов и событий для коробочных инсталляций.

➖Удалено
❗примеры выносятся в отдельный репозиторий → bitrix24/b24sdk-examples

📈 Статистика

Bitrix24 API-methods count: 1146
Supported in bitrix24-php-sdk methods count: 227
Coverage percentage: 19.81% 🚀
Supported in bitrix24-php-sdk methods with batch wrapper count: 29

👋 Новые контрибьюторы
— wmnnd made their first contribution in https://github.com/bitrix24/b24phpsdk/pull/118
— sallee113 made their first contribution in https://github.com/bitrix24/b24phpsdk/pull/146

https://github.com/bitrix24/b24phpsdk/releases/tag/1.3.0

BITRIX24-PHP-SDK-EXAMPLES-01

Стартовый шаблон
📺 https://www.youtube.com/watch?v=8y-vcc4KMdo

BITRIX24-PHP-SDK-EXAMPLES-02

tl;dr;
— используйте переменные окружения

📺 https://www.youtube.com/watch?v=jUBE5VyTkog

BITRIX24-PHP-SDK-EXAMPLES-03

tl;dr;
— научились подключать SDK через composer

📺 https://www.youtube.com/watch?v=iwR2eTvyBJ8

BITRIX24-PHP-SDK-EXAMPLES-04

tl;dr;
— научились подключать monolog

📺 https://www.youtube.com/watch?v=J3MHlF42fWM

Добавляем в календари и подаем свои доклады!