Привет, у нас хорошие новости!

Спонсором разработки https://github.com/mesilov/bitrix24-php-sdk на этот год становится компания Яндекс.

В рамках программы грантов Yandex Open Source компания перечислит 600 000 руб. для развития проекта.
Поддержка будет оказана в виде оплаты расходов в их вычислительном облаке.

По всей видимости, в течении этого года, можно будет ожидать примеров приложений, развёрнутых на базе yandex.cloud
stay tuned 🚀

Если вы уже живёте в их облаке и разрабатываете приложения, то напишите пожалуйста в комментариях свои впечатления и какие сервисы вы используете.

Привет, вот вам тема на подумать и предложить более элегантное решение:

При разработке bitrix24-php-sdk я все методы стараюсь покрывать интеграционными тестами, это позволяет:
⁃ найти расхождения с документацией по структурам данных
⁃ убедиться здесь и сейчас, что оно работает
⁃ быстро дёрнуть метод при поиске решения и убедиться, что это то что надо.

Авторизация идёт через входящий вебхук, который прокидывается из переменных окружения, это позволяет:
- гнать тесты внутри CI пайплайна
- при необходимости подпихнуть свой и вызвать тест на интересующий метод (об свой портал)

Боль: часть методов требует токенов приложения, от вебхука они не работают.

Варианты:
1. На эти методы тестов не писать 🤡, а проверить работу на локальном приложении и надеяться на лучшее. Считаю, что этот подход можно использовать если остальные слишком дорогие в реализации.

2. Тесты написать, сделать костыль для получения токена локального приложения которое запущено рядом, т.е. если хотите протестировать эти методы, то сделайте локальное приложение по инструкции, поднимите его, получите актуальные токены и уже потом запускайте все тесты. Из минусов - такое не взлетит в CI-пайплайне.

3. Тесты написать, сделать костыль для получения и обновления токенов приложения, которое бежит как условная лямбда в облаке и хранит там-же актуальные токены. Будет работать локально и в CI-пайплайне, больше всего мороки.

Что выбираем?

Обнаружил себя в ситуации, когда в одном окне у меня открыта документация к REST-API Битрикс24 и ряд дампов с ответами от сервера, а в другом — руководство от посудомоечной машины.
В одном из них все сразу понятно, хорошо структурировано и не допускает различных прочтений.
А второе — это записки сумасшедшего, что ты несёшь блядь.

Так вот, с телефонией разобраться проще.

Привет!
В рамках работ по выпуску сборки bitrix24-php-sdk v2.0 был полностью переписан скоуп telephony,

https://github.com/mesilov/bitrix24-php-sdk/pull/388

Теперь поддерживаются все методы, в т.ч. из неймспейса voximplant, всё покрыто тестами, в проект занесли rector.
Т.к. меняется мажорная версия, то происходит полная потеря обратной совместимости с предыдущими версиями 🤗

Пару человек в личку спросили, почему с контрактами так заморочено получается, сделал компактный пример с пояснением

https://www.youtube.com/watch?v=GupH7WB_7Tg

Сделал подход к сущности «Bitrix24Accounts», что у нас есть:
– Контракт на методы самой сущности https://github.com/mesilov/bitrix24-php-sdk/blob/feature/383-refactor-app-contracts-and-add-documentation-for-use-cases/src/Application/Contracts/Bitrix24Accounts/Entity/Bitrix24AccountInterface.php
— Контракт на методы репозитория который хранит эту сущность https://github.com/mesilov/bitrix24-php-sdk/blob/feature/383-refactor-app-contracts-and-add-documentation-for-use-cases/src/Application/Contracts/Bitrix24Accounts/Repository/Bitrix24AccountRepositoryInterface.php
— Дока с описанием этого добра https://github.com/mesilov/bitrix24-php-sdk/blob/feature/383-refactor-app-contracts-and-add-documentation-for-use-cases/src/Application/Contracts/Bitrix24Accounts/Docs/Bitrix24Accounts.md
— Контрактные тесты https://github.com/mesilov/bitrix24-php-sdk/tree/feature/383-refactor-app-contracts-and-add-documentation-for-use-cases/tests/Unit/Application/Contracts/Bitrix24Accounts


Если вы делали приложение для Битрикс24, то пожалуйста:
1. Посмотрите на методы сущности и репозитория и сравните со своими
2. Напишите в комментариях, чего по вашему мнению не хватает.
3. Что ещё требуется в документации к этой сущности?

Сущности, которые будут поддержаны на уровне контрактов в bitrix24-php-sdk v2

Если вы делаете приложения без сохранения контактных данных, то ничего страшного у вас будет только Application Installations и Bitrix24 Accounts, там никаких перс. данных нет.

В Bitrix24 Partners только общие данные — наименование, сайт, почта [email protected] и т.д. А должно ли приложение регистрировать открытую линию партнёра, который ставит приложение?

Основная мотивация добавления поддержки Contact Persons — это упрощение поддержки приложений.

Контракты для приложений маркетплейса влиты в релизную ветку 🚀 (https://github.com/mesilov/bitrix24-php-sdk/pull/398)

Сейчас «из коробки» SDK даёт вам подсказки, как можно организовать:
— хранение токенов Bitrix24Accounts
— факты установок ApplicationInstallations
— информация о контактных лицах, которые поставили приложение ContactPersons , вещь опциональная, на любителя работать с перс.данными.
— информация о партнёре который сопровождает портал или производил установку Bitrix24Partners , опционально.

Каждый из контрактов содержит:
- документацию
- интерфейс для сущности
- интерфейс для репозитория
- события
- контрактные тесты (`248 tests, 386 assertions`) об которые можно проверять свои собственные реализации этих контратов.

Что дальше будет в плане улучшения жизни разработчиков приложений:
- отдельный репозиторий с фреймворк-агностик реализацией сущностей и хранением их в БД (привет доктрина) котороый завязан на эти контракты
- использование этого решения уже внутри фреймворка (symfony или laravel).

Следующий шаг — подготовка к сборке версии 2.0

Вчера Валентин Удальцов (если вы пишите на PHP, то вы про него слышали) решил сделать срез знаний по PHP для подписчиков своего канала @phpyh и задал пяток вопросов:

1. Назови несколько принятых в PHP 8.4 изменений
2. Почему некоторые расширения, например, ext-pcntl, в composer.json принято прописывать с констрейнтом "*"?
3. По какому принципу выбраны значения констант ReflectionProperty::IS_*? https://www.php.net/manual/ru/class.reflectionproperty.php
4. Можно ли расширить возвращаемый тип метода в дочернем классе и почему?
5. Как соотносятся понятия "полиморфизм" и "наследование"?
6. Реши задачу. https://gist.github.com/vudaltsov/f2606f3adb562cc8e9375a0c69527693
7. Почему попросить ИИ-помощника написать тесты может быть не очень хорошей идеей?
8. В чём оптимизм оптимистичной блокировки?

Разбор ответов у Валентина будет позже, часть вопросов намекают на его текущую работу.

У меня в планах попробовать использовать библиотеку Валентина для автовывода типов возвращаемых результатов.
Если у вас есть много свободного времени и есть желание попробовать поработать с системой типов в PHP, то ставьте + в комментарии.

Текущее положение дел
Разработчики из Битрикс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, примеров - планов много.