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

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

В приложении мы можем использовать расширенную типизацию (в случае 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

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

BITRIX24-PHP-SDK-EXAMPLES-05

tl;dr;
— Composer License Checker
— PHP Coding Standards Fixer
— PHPStan
— rector
— Composer dependency analyser

📺 https://youtu.be/g3hScZhUrcM

BITRIX24-PHP-SDK-EXAMPLES-06

tl;dr;
— добавили DI

📺 https://youtu.be/FAmNe12ioP0

BITRIX24-PHP-SDK-EXAMPLES-07

tl;dr;
— добавили Sentry

📺 https://youtu.be/QA367CPC_gU

BITRIX24-PHP-EXAMPLES-08

tl;dr;
— работа с batch-запросами
— CLI приложения на symfony console
— обработка сигналов POSIX

📺 https://youtu.be/Lg-FITVElNc

🚀 1.5.0 – 2025.08.01

Added
- service Services\Entity\Section\Service\Section with support methods,
see [crm.entity.section.* methods](https://github.com/bitrix24/b24phpsdk/issues/200):
- service Services\Entity\Item\Property\Service\Property with support methods:
- service Services\Department\Service\Department with support methods,
see [department.* methods](https://github.com/bitrix24/b24phpsdk/issues/204):
- service CRM\Requisites\Service\RequisiteUserfield with support methods,
see [add crm.requisite.userfield.* methods](https://github.com/bitrix24/b24phpsdk/issues/188):
- service CRM\Requisites\Service\RequisiteBankdetail with support methods:
- service CRM\Requisites\Service\RequisiteLink with support methods:
- service CRM\Requisites\Service\RequisitePresetField with support methods:
- service Services\CRM\Status\Service\Status with support methods,
see [crm.status.* methods](https://github.com/bitrix24/b24phpsdk/issues/194):
- service Services\CRM\Status\Service\StatusEntity
- service Services\CRM\Timeline\Service\Comment with support methods,
see [crm.timeline.comment.* methods](https://github.com/bitrix24/b24phpsdk/issues/196):
- Added support for events:
- OnCrmTimelineCommentAdd
- OnCrmTimelineCommentDelete
- OnCrmTimelineCommentUpdate
- service Services\CRM\Timeline\Service\Bindings
- service Services\CRM\Item\Productrow\Service\Productrow with support methods,
see [crm.item.productrow.* methods](https://github.com/bitrix24/b24phpsdk/issues/198)

Fixed
- Fixed typehints in Contact batch for method add, [see details](https://github.com/bitrix24/b24phpsdk/issues/202)

Changed
- Fixed constructor arguments in tests ApplicationInstallations [see details](https://github.com/bitrix24/b24phpsdk/issues/191)
- Bump giggsey/libphonenumber-for-php version to ^8|^9

Statistics
Bitrix24 API-methods count: 1166
Supported in bitrix24-php-sdk methods count: 362
Coverage percentage: 31.05%

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

Привет, текущее положение дел по шаблонам приложений

1. Самый нижний слой — SDK
https://github.com/bitrix24/b24phpsdk — плановые релизы раз в месяц по расширению функционала библиотеки.

2. Слой хранения данных — фреймворк-агностик (не зависящий) от фреймворка
https://github.com/mesilov/bitrix24-php-lib/
Тут созданы две сущности отвечающие контрактам из b24phpsdk:
Bitrix24Accounts — храним токены и вот это все связанное с их жизненным циклом
ApplicationInstallations — храним факты установок \ удаления приложения и его жизненного цикла

Т.е. это тот самый минимум, который надо для запуска:
- локального приложения
- тиражного приложения

На этой неделе закончим причесывать до первого релиза 0.x
Т.к. тут уже вариативность существенно больше, то пилим с двумя другими разработчиками, MIT вот это все.

Если прям придерживаться symfony \ laravel way, то там надо делать Symfony‑bundle и Laravel‑adapter, там есть выбор, чтобы это было в одном репе или несколькро репов.
Сейчас, если разработчик на Symfony \ laravel захочет использовать bitrix24-php-lib, то ему придется руками все что надо сконфигурировать у себя (пока нет бандла \ адаптера). Есть такие?

На текущий момент мне гораздо важнее проверить работу всех пользовательских сценариев, поэтому тут пока работы поставил на паузу, делаются только мелки вещи вроде поправить тесты, исправить очевидные косяки и т.д.

3. Шаблоны репозиториев на Symfony \ Laravel
Основная точка приложения усилий, сейчас собираю шаблон симфони, чтобы проверить сценарии которые реализует bitrix24-php-lib и то насколько безболезненно можно все в кучу собрать.
https://github.com/mesilov/bitrix24-application-symfony-template — работы тут
Как только отлажу на симфони сценарии (установка, удаление, очереди и т.д), то можно будет сделать бандл \ и адаптер для Laravel.
Такие вот дела.

Что по инфраструктуре?

Приложение работает поверх инфраструктуры, нфраструктурной единицей у нас будет докер-контейнер.
Вопрос в том, что будем выбирать в качестве аппликейшн\веб-сервера. Какие у нас варианты:

Встроенный в PHP dev-сервер
Все запускаем на встроенном в PHP дев-сервере, а production конфигурация это не наша головная боль. Крутитесь как хотите.
У всех пользователей начинает болеть голова, а как это вот все запускать и обслуживать.

nginx + phpfpm
Есть миллион рецептов, проверено годами, собрали @ запустили, для production контура каждый самостоятельно решает ряд вопросов: выпуск сертификатов, логи, телеметрия и т.д.
ru и западное комьюнити в целом понимают, что это такое и как настраивать. На уровне шаблонов приложений даем базовую конфигурацию и дальше сами конфигурируйте как хотите.
Отложенная проблема: развитие nginx начиная с 2022 года стагнирует. Приложения для Битрикс24 не упрутся в «архитектурные» ограничения nginx, но вот экосистема не предоставляет удобных решений «из коробки», настраивайте все сами, как лично вам удобно будет ©.

angie
Это форк nginx от русскоязычной части core-команды nginx, развивается более динамично, русскоязычное комьюнити. Если у вас есть «черный пояс по nginx», то это хорошая замена, которая отвечает на значительную часть требований к современному приложению. Если говорим про западное комьюнити, то выбор angie вызовет некоторые вопросики.
Ну и никуда не девается история с long-running режимом работы php, к которому старательно пытается подойти php-комьюнити.
Более детально с tech-drama можно ознакомиться глянув эти доклады:
https://www.youtube.com/watch?v=Qx9BB7w4mt4 — php и angie
https://www.youtube.com/watch?v=QeI5GMP4ukM&t=15s — деды под пиво бухтят и рассказывают закулисную часть истории

frankenphp
Если вы последний год сидели в пещере и пропустили все новости, то у PHP появился свой application-server.
https://thephp.foundation/blog/2025/05/15/frankenphp/
Из минусов: нужно выучить новый «птичьий язык» конфигурации веб-сервера caddy.
Из плюсов:
— аппликейшн-сервер развивают люди, которые знают с какой стороны PHP запрягать — Kévin Dunglas, creator of API Platform and Symfony Core Team member.
— готовые сценарии для наших любимых фреймворков (Symfony, Laravel, БУС)
— комьюнити адаптирует фреймворки\сценарии и всю обвязку под текущий стек, а под условный nginx вы должны будете портировать конфиги сами.

Поэтому, выбираем в качестве application-server frankenphp 🤔 и на нем отлаживаем «production-ready» конфигурацию приложения, заодно посмотрим, как это выглядит в реальности, а не на бодрых докладах инфлюенсеров с ютьюба, у которых все само работает.