PHPackages                             x3group-dev/bitrix24-api-laravel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. x3group-dev/bitrix24-api-laravel

ActiveLibrary[API Development](/categories/api)

x3group-dev/bitrix24-api-laravel
================================

b24 rest api

3.4.0(2w ago)13577↓50%3MITPHPPHP ^8.4

Since Jul 12Pushed 1w agoCompare

[ Source](https://github.com/x3group-dev/bitrix24-api-laravel)[ Packagist](https://packagist.org/packages/x3group-dev/bitrix24-api-laravel)[ RSS](/packages/x3group-dev-bitrix24-api-laravel/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (10)Dependencies (10)Versions (44)Used By (0)

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

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

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

Установка

```
composer require x3group-dev/bitrix24-api-laravel

```

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

```
php artisan vendor:publish --provider="X3Group\Bitrix24\Bitrix24ServiceProvider"

```

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

```
php artisan migrate

```

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

Приложение:

```
https://host/app

```

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

```
https://host/install

```

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

```
BITRIX24_PHP_SDK_APPLICATION_CLIENT_ID=
BITRIX24_PHP_SDK_APPLICATION_CLIENT_SECRET=
# вместо crm,user_brief укажите скоупы приложения
BITRIX24_PHP_SDK_APPLICATION_SCOPE="crm,user_brief"
BITRIX24_LOG_MAX_FILES=3

```

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

```
BX24.ready(async function () {
    await BX24.init(async function () {
        window.axios.defaults.headers.common['X-b24api-access-token'] = BX24.getAuth().access_token;
        window.axios.defaults.headers.common['X-b24api-refresh-token'] = BX24.getAuth().refresh_token;
        window.axios.defaults.headers.common['X-b24api-domain'] = BX24.getAuth().domain;
        window.axios.defaults.headers.common['X-b24api-member-id'] = BX24.getAuth().member_id;
        window.axios.defaults.headers.common['X-b24api-expires-in'] = BX24.getAuth().expires_in;
    });
});

```

**Cron**

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

```
* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1
```

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

[](#миграция-на-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)
----------------------------------------

[](#установщики-приложения-реестр-с-310)

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

- Класс реализует интерфейс `X3Group\Bitrix24\Contracts\Bitrix24Installer`: ```
    public function install(\Bitrix24\SDK\Services\ServiceBuilder $b24): void;
    ```
- Регистрируются упорядоченным списком в `config('bitrix24.installers')`: ```
    'installers' => [
        App\Install\InstallEvents::class,
        App\Install\InstallLists::class,
        // ...в нужном порядке
    ],
    ```
- **Когда это выполняется.** Весь 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`)
------------------------------------------------

[](#владелец-app-токена-портала-b24_appsuser_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`](CHANGELOG.md).

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

[](#консольные-команды)

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

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

[](#структурированное-логирование)

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

**Как включить**

```
STRUCTURED_LOG_ENABLED=true
APP_LOG_NAME=base
# необязательные:
STRUCTURED_LOG_PATH=storage/logs/structured/app.json
STRUCTURED_LOG_MAX_FILES=14
STRUCTURED_LOG_TRUNCATE_AT=200

```

- `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`](docs/structured-logging-infra.md).

###  Health Score

56

—

FairBetter than 97% of packages

Maintenance97

Actively maintained with recent releases

Popularity26

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity75

Established project with proven stability

 Bus Factor1

Top contributor holds 82.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~38 days

Recently: every ~2 days

Total

30

Last Release

20d ago

Major Versions

1.0.9 → 2.0.0.x-dev2024-11-19

1.0.15 → 2.0.32025-04-08

1.0.16 → 2.0.62025-05-26

1.x-dev → 2.0.82026-07-15

2.0.8 → 3.0.02026-07-20

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/22890988?v=4)[Evgeniy Pedan](/maintainers/MrDeff)[@MrDeff](https://github.com/MrDeff)

---

Top Contributors

[![MrDeff](https://avatars.githubusercontent.com/u/22890988?v=4)](https://github.com/MrDeff "MrDeff (33 commits)")[![maximyugov](https://avatars.githubusercontent.com/u/78841025?v=4)](https://github.com/maximyugov "maximyugov (7 commits)")

---

Tags

laravelbitrixBitrix24

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/x3group-dev-bitrix24-api-laravel/health.svg)

```
[![Health](https://phpackages.com/badges/x3group-dev-bitrix24-api-laravel/health.svg)](https://phpackages.com/packages/x3group-dev-bitrix24-api-laravel)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3345.4M354](/packages/psalm-plugin-laravel)[craftcms/cms

Craft CMS

3.6k3.7M3.4k](/packages/craftcms-cms)[pressbooks/pressbooks

Pressbooks is an open source book publishing tool built on a WordPress multisite platform. Pressbooks outputs books in multiple formats, including PDF, EPUB, web, and a variety of XML flavours, using a theming/templating system, driven by CSS.

45844.8k1](/packages/pressbooks-pressbooks)[mongodb/laravel-mongodb

A MongoDB based Eloquent model and Query builder for Laravel

7.1k8.9M110](/packages/mongodb-laravel-mongodb)[rapidez/core

Rapidez Core

1824.4k80](/packages/rapidez-core)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)