Download the PHP package x3group-dev/bitrix24-api-laravel without Composer

Пакет Laravel для удобной работы с REST API Битрикс24 и написания приложений.

Включает в себя:

• Миграции для сбора статистики запросов и сохранения авторизации(токенов) пользователей
• Роуты в зависимости от типа приложения и запросов к нему
• Шаблоны для установки и работы приложения
• Проверку статуса порталов на которые было установлено приложение
• Автоматическое обновление токенов пользователей

Установка

Выполнить публикацию (скопируются routes, blade, базовые контроллеры)

Выполнить миграции

В адреса приложений вписываем

Приложение:

Установка приложения:

в файл .env добавляем и заполняем своими данными

В сборку фронта добавить проброс авторизации в заголовках, чтобы работали роуты b24appFrontRequest

Cron

Для автообновления токенов приложения обязательно требуется добавить запись в crontab

Миграция на b24phpsdk ^3 (SDK 3)

Начиная с версии 3.0.0 пакет переведён на официальный bitrix24/b24phpsdk ^3 и требует PHP 8.4. В SDK 3 адрес OAuth-сервера (обновление токенов) задаётся через объект Endpoints и хранится отдельно для каждого портала.

• Требуется PHP 8.4 и bitrix24/b24phpsdk ^3.
• В таблице b24_apps добавлена колонка oauth_server_url (миграция включена) — адрес OAuth-сервера (v3 Endpoints), используемый для обновления токенов. Значение выводится автоматически из SERVER_ENDPOINT запроса установки/плейсмента; фолбэк — EAST https://oauth.bitrix24.tech/ (захардкожен в OauthServerUrlResolver, переменная окружения не нужна).
• В таблице b24_users отдельной колонки нет — адрес OAuth-сервера резолвится из b24_apps по member_id.
• Потребителям при обновлении необходимо перейти на PHP 8.4 и выполнить php artisan migrate.

Установщики приложения (реестр, с 3.1.0)

Создание сущностей приложения (списки, entity, встройки, поля и т.п.) при установке вынесено в реестр установщиков — приложению больше не нужен свой install-контроллер, только классы-установщики.

• Класс реализует интерфейс X3Group\Bitrix24\Contracts\Bitrix24Installer:

• Регистрируются упорядоченным списком в config('bitrix24.installers'):

• Когда это выполняется. Весь install-флоу (InstallService: запись app-токена + прогон установщиков) работает только на установке/переустановке приложения — это маршрут /install (InstallController) и серверное событие ONAPPINSTALL (OnApplicationInstallController). На обычных открытиях приложения (главный маршрут /app, плейсменты, front-запросы) install-флоу НЕ запускается и app-токен не трогается — там работает пер-юзерная авторизация (b24_users через middleware). Установщики вызываются по порядку, из одного места (идемпотентно).
• Установщики ОБЯЗАНЫ быть идемпотентны. Ошибка любого установщика логируется и пробрасывается (fail-loud), страница установки показывает install-fail — то есть неидемпотентный установщик (напр. «поле уже существует») превратит повторную установку/переустановку в экран ошибки.
• App-токен портала (b24_apps) — пишется только на установке/переустановке (/install / ONAPPINSTALL) и только если устанавливающий — администратор (profile->ADMIN). Проверка идёт на обоих путях и не сокращается для первой установки портала; не-админ прерывает установку исключением InstallerCannotOwnPortalException. Подробнее — в разделе «Владелец app-токена портала» ниже.
• По умолчанию installers пуст — обратная совместимость.

Владелец app-токена портала (b24_apps.user_id)

Колонка user_id в b24_apps — владелец app-токена портала: пользователь, чьим токеном приложение ходит в REST от имени всего портала. Записывается один раз, при установке, и обновлением токена не меняется. user_id = NULL — «владелец не установлен или не доверен»: для такой строки правило 2 не срабатывает вовсе (fail-closed). Без явного владельца в b24_apps мог оказаться токен рядового сотрудника, после чего админ-методы (userfieldconfig.*) падали «нет прав».

Правило 1 — установка и переустановка (/install, ONAPPINSTALL): пишет токен и владельца, и только если устанавливающий — администратор.

Правило 2 — обновлённый токен владельца: свежий токен пользователя из b24_users переносится в b24_apps, только если этот пользователь и есть записанный владелец портала. Срабатывает в B24AppUserMiddleware (владелец открыл приложение — основной путь) и в UserAuthDatabaseStorage::saveRenewedToken(). Меняет только access_token, refresh_token, expires, expires_in и сбрасывает error_update.

Ломающие изменения и порядок обновления — CHANGELOG.md.

Консольные команды

Пакет поставляет три artisan-команды: bitrix24:backfill-app-owner, bitrix24:reanchor-app-token и bitrix24:remove-uninstalled. Что каждая делает, когда её запускать, опции, ограничения и порядок выката — docs/console-commands.md.

Структурированное логирование

Пакет умеет собирать структурированный JSON-лог REST-вызовов Битрикс24 и ошибок приложения — для последующей централизованной доставки (Vector → ClickHouse) и разбора. По умолчанию выключено: пока не включишь — поведение пакета не меняется вовсе, ничего не пишется. Подключение zero-config: пакет уже установлен, канал регистрируется через auto-discovery, включается парой переменных .env.

Как включить

• APP_LOG_NAME — метка app в каждой записи (какое приложение пишет); если пуст, берётся config('app.name'). Задавайте явно, когда логи многих приложений сливаются в одно хранилище.

Что пишется

• REST-вызовы Битрикс24 — ровно одна запись на вызов: метод, параметры (для воспроизведения) и исход (ok/http/duration_ms, id либо count, при ошибке — error). Полный result не тащится. Многословный debug-поток родного SDK в этот канал не течёт.
• Ошибки приложения — записи уровня WARNING и выше (Log::warning/error, необработанные исключения) дублируются в тот же файл. Стек логирования приложения при этом не переопределяется — канал работает как дополнительный приёмник.

Где файл и ротация

storage/logs/structured/app.json через monolog RotatingFileHandler (daily) — реально пишется app-ГГГГ-ММ-ДД.json, старые файлы monolog удаляет сам, оставляя последние STRUCTURED_LOG_MAX_FILES дней. Локальный файл — это короткий буфер на случай недоступности доставки, а не архив; долгое хранение — в ClickHouse по TTL (см. ниже).

Что маскируется

• Секреты — значения ключей auth/AUTH, access_token, refresh_token, application_token, webhook_token и JWT-подобные строки (eyJ…) → ***, рекурсивно по всей записи.
• Персональные данные — только для методов user.* вырезаются NAME, LAST_NAME, SECOND_NAME, EMAIL, PERSONAL_MOBILE, PERSONAL_PHONE, WORK_PHONE, LOGIN. Вне user.* не трогаются (чтобы, например, NAME заголовка статьи сохранился).
• Длинный контент — любая строка длиннее STRUCTURED_LOG_TRUNCATE_AT (дефолт 200) обрезается с пометкой полной длины: «…первые 200 символов… (всего N символов)».

Списки ключей-масок и лимит обрезки настраиваются в config/structured-logging.php (php artisan vendor:publish --provider="X3Group\Bitrix24\Bitrix24ServiceProvider" для переопределения; работает и с дефолтами без публикации).

Поле schema_version

Каждая запись помечена schema_version (старт "1") — константой формата в коде пакета. При несовместимом изменении состава полей версия поднимается, чтобы хранилище и разбор различали старые и новые записи и не ломались на них.

Доставка лога в хранилище (Vector → ClickHouse) — задача инфраструктуры, от кода приложения не зависит; чек-лист девопсу: docs/structured-logging-infra.md.