Релокейт-ориентированное программирование

Вышли на финишную прямую сборки билда v2-alpha7, список изменений и закрытых задач — https://github.com/mesilov/bitrix24-php-sdk/issues/273

Если у вас ещё не горят сроки, то переключитесь на ветку и погоняйте новый функционал.

Быстрый вопрос: у когото были потребности вида «достать активити определённого типа» например, заполнения конкретной CRM-формы или звонки там. Т.е. можно поверх активити сделать хелперы для получения конкретных типов.

Если с таким сталкивались — напишите пожалуйста в комментариях

Новый релиз bitrix24-php-sdk — 2.0-alpha.7
Обновляемся и тестируем! 🚀
https://github.com/mesilov/bitrix24-php-sdk

Добавлено:
— скоуп Telephony и сервисы по работе с ней
— скоуп UserConsent и сервисы по работе с ним
— скоуп Placements и сервисы по работе с ним
— скоуп IMOpenLines и сервисы по работе с ним
— скоуп CRM добавлен сервис Leads
— скоуп CRM добавлен сервис Activity
— скоуп CRM добавлен метод Services\CRM\Deal\Service\Batch:update
— скоуп CRM добавлен метод Services\CRM\Contact\Service\Batch:delete
— скоуп CRM добавлены сервисы Services\CRM\Activity\ReadModel для: EmailFetcher, OpenLineFetcher, VoximplantFetcher, WebFormFetcher
— скоуп Main добавлена поддержка сервиса Events
— добавлена поддержка событий уровня приложения: ONAPPINSTALL и ONAPPUNINSTALL
— добавлена поддержка событий уровня приложения: PortalDomainUrlChangedEvent
— добавлен метод Core\Batch:updateEntityItems
— добавлен метод Core\Contracts\BatchInterface:updateEntityItems
— скоуп Placements добавлен сервис Placement\Service\UserFieldType для работы с типами полей подразумеващюих встройку
— скоуп Telephony, добавлена поддержка событий: OnExternalCallBackStart, OnExternalCallStart, OnVoximplantCallEnd, OnVoximplantCallEnd, OnVoximplantCallInit, OnVoximplantCallStart
— добавлена поддержка DTO ApplicationStatus
— добавлен метод AccessToken:initFromPlacementRequest
— добавлен метод ApplicationProfile:initFromArray when application profile stored in ENV-variables
— добавлена поддержка инициализации плейсментов Bitrix24\SDK\Application\Requests\Placement\PlacementRequest
— добавлен метод Credentials:initFromPlacementRequest когда приложение инициализируется при загрузке плеймента
— добавлен метод Services\Main\Service:getServerTime возвращает время сервера
— добавлен метод Services\Main\Service:getCurrentUserProfile возвращает базовую инфу по текущему юзеру.
— добавлен метод Services\Main\Service:getAccessName возвращает наименования разрешений.
— добавлен метод Services\Main\Service:checkUserAccess
— добавлен метод Services\Main\Service:getMethodAffordability
— добавлена поддержка полей operating и operating_reset_at в Bitrix24\SDK\Core\Response\DTO\Time

Изменено
— обновили состав скоупов
— увеличили требования для компонентов symfony/* до версии 6.*
— метод Services\Main\Service:getAvailableMethods помечен как deprecated
— метод Services\Main\Service:getAllMethods помечен как deprecated
— метод Services\Main\Service:getMethodsByScope помечен как deprecated
— ❗️метод Bitrix24\SDK\Core\Credentials переименован: createFromWebhook, createFromOAuth, createFromPlacementRequest
— ❗️удалён класс Bitrix24\SDK\Core\Response\DTO\ResponseDataCollection
— ❗️удалён класс Bitrix24\SDK\Core\Response\DTO\Result
— ❗️удалён метод CoreBuilder:withWebhookUrl, используйте
method CoreBuilder:withCredentials

Исправления ошибок
— add bugfix for batch method for reverse order queries
— fix type compatible errors for Core\Result\AbstractItem
— error in NetworkTimingParser
— error in RenewedAccessToken DTO, remove Scope
enum

etc
— добавлена возможность спонсирования разработки https://boosty.to/bitrix24-php-sdk

Привет, новая сборка SDK на подходе:

2.0-beta.1 — 18.02.2024
https://github.com/mesilov/bitrix24-php-sdk/releases – полный список изменений

Добавлено
add php 8.3, 8.2 support, drop 8.1 and 8.0 support
add Symfony\Component\Uid\Uuid requirements
add contracts for bitrix24 applications based on bitrix24-php-sdk - Bitrix24\SDK\Application\Contracts, now added Bitrix24Account
add service builder factory https://github.com/mesilov/bitrix24-php-sdk/issues/328
add method Bitrix24\SDK\Core\Credentials\Scope::initFromString
add method Bitrix24\SDK\Application\ApplicationStatus::initFromString
add system CRM multi-field type Bitrix24\SDK\Services\CRM\Common\Result\SystemFields\Types\Phone
add scope user,user_basic,user_brief,user.userfield and services https://github.com/mesilov/bitrix24-php-sdk/issues/339
– Bitrix24\SDK\Services\User\Service\User::fields - get user fields
– Bitrix24\SDK\Services\User\Service\User::current - get current user
– Bitrix24\SDK\Services\User\Service\User::add - add user
– Bitrix24\SDK\Services\User\Service\User::get - get user
– Bitrix24\SDK\Services\User\Service\User::update - update user
– Bitrix24\SDK\Services\User\Service\User::search - search users
add method \Bitrix24\SDK\Services\CRM\Contact\Service\Batch::update() for batch update contacts
add crm item support https://github.com/mesilov/bitrix24-php-sdk/issues/330
add enum DealStageSemanticId
add Duplicate search support for Bitrix24\SDK\Services\CRM\Duplicates\Service\Duplicate
add x-request-id header support https://github.com/mesilov/bitrix24-php-sdk/issues/354
add CRM multifields support https://github.com/mesilov/bitrix24-php-sdk/issues/338
– Email
– Phone
– Website
– IM
add Catalog https://github.com/mesilov/bitrix24-php-sdk/issues/364 scope services support

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

Спонсором разработки 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);
}