Розробка PHP-хуків для подій 1С-Бітрикс

Після чергового оновлення ядра Бітрикс на одному з проєктів перестали працювати обробники подій модуля sale. Користувачі не отримували сповіщення про оплату, замовлення не потрапляли в CRM. Причина — конфлікт реєстрацій у init.php: два модулі вішали обробники на одну подію з різними sort, і після оновлення порядок змінився. Такі ситуації трапляються постійно. Розробка надійних PHP-хуків для 1С-Бітрикс потребує розуміння архітектури ядра та дисципліни кодування. За 8 років ми розробили понад 50 проєктів з подійною моделлю і виробили стандарти, що виключають типові помилки. Нижче — практичні прийоми, які допоможуть створити стійку подійну архітектуру та скоротити час на налагодження на 30–40%.

Як працюють події в Бітрикс

Ядро Бітрикс генерує події в ключових точках: до операції (Before-події) та після (After-події). Обробник реєструється через EventManager:

use Bitrix\Main\EventManager; EventManager::getInstance()->addEventHandler( 'sale', // модуль 'OnSaleOrderBeforeSaved', // подія ['MyHandler', 'onBeforeOrderSave'] // callback ); 

Реєстрація обробників — у файлі init.php (/local/php_interface/init.php або /bitrix/php_interface/init.php). Для модулів — у методі installEvents(). Документація Бітрикс рекомендує вказувати параметр sort для контролю порядку.

Before-події дозволяють модифікувати дані до збереження або скасувати операцію. Повертаєте EventResult з типом ERROR — операція переривається. After-події — для реакції на вже здійснену дію: відправити сповіщення, записати лог, оновити пов'язані дані.

Каталог ключових подій

Повний список — у файлах модулів: /bitrix/modules/{module}/lib/events.php або в документації.

Чому варто виносити обробники в окремий модуль?

Модуль надійніший за init.php при оновленнях та міграціях. При деактивації модуля обробники вимикаються автоматично — у випадку з init.php потрібно чистити код вручну. Якщо логіка універсальна (наприклад, інтеграція з платіжним шлюзом) — модуль обов'язковий. Проєктні одноразові задачі можна залишити в init.php з класами.

Як уникнути циклічних викликів?

Обробник OnAfterIBlockElementUpdate всередині себе оновлює елемент інфоблоку → знову спрацьовує OnAfterIBlockElementUpdate → нескінченна рекурсія. Рішення — статичний прапорець:

class IblockHandler { private static bool $isProcessing = false; public static function onAfterUpdate($arFields): void { if (self::$isProcessing) return; self::$isProcessing = true; // ... логіка self::$isProcessing = false; } } 

Важкі операції в Before-подіях — ще одна поширена помилка. OnSaleOrderBeforeSaved викликається 3-5 разів за оформлення замовлення. Якщо всередині — HTTP-запит до зовнішнього API — оформлення гальмує. Рішення: важкі операції виносити в After-події або в чергу (агенти, \Bitrix\Main\Event з відкладеною обробкою).

Архітектура обробників: як організувати код

На реальному проєкті обробників — десятки. Без організації init.php перетворюється на смітник. Рекомендована структура:

/local/php_interface/ ├── init.php → тільки require файлів реєстрації ├── handlers/ │ ├── sale.php → реєстрація обробників модуля sale │ ├── iblock.php → реєстрація обробників модуля iblock │ └── main.php → реєстрація обробників модуля main ├── classes/ │ ├── SaleHandler.php → класи з логікою обробників sale │ ├── IblockHandler.php │ └── MainHandler.php 

Кожен клас-обробник — статичні методи. Один метод — одна подія. Всередині методу — мінімум логіки: валідація вхідних даних, виклик сервісного класу, повернення результату.

Порівняння init.php і модуля

Налагодження обробників: інструменти та прийоми

Стандартний спосіб — Bitrix\Main\Diag\Debug::writeToFile(). Пише у файл /local/php_interface/debug.log.

Більш системний підхід — модуль perfmon. Показує, які обробники зареєстровані на кожну подію та скільки часу кожен споживає (у мілісекундах). Вмикається в Налаштування → Продуктивність → Панель продуктивності.

Для Before-подій модуля sale — особливість: ланцюжок обробників переривається при першому ERROR. Якщо ваш обробник не викликається — перевірте, чи не повертає ERROR інший обробник, зареєстрований з меншим sort. Це економить до 2 годин налагодження на місяць.

Процес розробки обробників у нашій команді

1. Аудит: аналізуємо поточні обробники, виявляємо конфлікти, вузькі місця та витоки пам'яті. Зазвичай знаходимо 5-10 проблем за 2 години.
2. Проєктування: обираємо архітектуру (модуль або init.php), погоджуємо з вами.
3. Реалізація: пишемо код з тестуванням на стенді, покриваємо крайові випадки (наприклад, порожнє замовлення, некоректні ID).
4. Тестування: навантажувальне тестування (симулюємо 100+ одночасних замовлень), перевірка сумісності з вашими доробками.
5. Деплой: викатка на бій, моніторинг протягом тижня. При проблемах — відкат за 15 хвилин.

Що входить у роботу та гарантії

• Аудит поточних обробників та виявлення конфліктів
• Проєктування архітектури (модуль або init.php з класами)
• Реалізація з тестуванням на стенді
• Документація та передача вихідних кодів
• Пост-релізна підтримка 1 місяць

Наші інженери мають досвід розробки на Бітрикс понад 8 років та сертифікацію Bitrix. За 50+ проєктів ми виробили стандарти, що виключають типові помилки. Замовте аудит поточних обробників — отримайте звіт з рекомендаціями щодо оптимізації. Зв'яжіться з нами для консультації. Отримайте консультацію з архітектури подій безкоштовно.