PHP: полный мануал с примерами, функциями и ООП

Исторически PHP 5 и PHP 7 до 7.4; далее внешнее расширение. Проверяемый профиль interbase 3.0.1 / PHP 8.2. · interbase

ibase_wait_event(resource $connection, string $event_name, string ...$event_names): string|false

Когда фоновому обработчику нечего делать до изменения базы, ibase_wait_event позволяет ждать именованный сигнал. После возврата всё равно нужно прочитать текущее состояние или сохранённую очередь заданий: имя события не является самим документом.

ibase_wait_event(string $event_name, string ...$event_names): string|false
ibase_wait_event(resource $connection, string $event_name, string ...$event_names): string|false

POST_EVENT вызывается на сервере в PSQL, например в триггере или EXECUTE BLOCK, и публикует событие после commit. Длина имени в Firebird ограничена 127 байтами, а не 127 произвольными многобайтными символами. Имя выбирают коротким и стабильным. Регистр важен: catalog_changed и CATALOG_CHANGED — разные подписки. Транзакция связывает запись и её сигнал.

Применение 1: разбудить обновление конкретного товара

$event = ibase_wait_event($db, 'CATALOG_CHANGED');
if ($event === false) {
    $errorCode = ibase_errcode();
    throw new RuntimeException('Ожидание каталога не выполнено');
}
// Начинаем свежее чтение нужного представления, а не SELECT * по всей базе.
$result = ibase_query($db, 'SELECT ID, TITLE, QTY FROM LAB_ITEMS WHERE ID = ?', 1);

Здесь соединение и таблица уже подготовлены; результат SELECT ещё нужно прочитать и освободить. Полный проект с двумя процессами показывает исходные 3 и полученные 11, сохраняет событие и доказывает, что предметный UPDATE был один. Это полезно для worker, которому нужно обновить свой кэш или сформировать представление после сохранения.

Применение 2: одно представление зависит от двух видов изменений

$name = ibase_wait_event($db, 'PRICE_CHANGED', 'STOCK_CHANGED');
if ($name === false) {
    throw new RuntimeException('Не удалось дождаться изменения');
}
// Любое из двух имён означает, что выбранная карточка могла устареть.
$result = ibase_query($db, 'SELECT ID, TITLE, QTY FROM LAB_ITEMS WHERE ID = ?', $itemId);

Это контекстный вариант для заранее выбранного ID. Нельзя трактовать возвращённое PRICE_CHANGED как доказательство, что STOCK_CHANGED за это время не происходило: функция вернула одно имя, а не полный журнал. Для представления можно перечитать весь небольшой нужный набор выбранных полей. Если нужны все задания, их сохраняют в таблице, читают при старте и после пробуждения; потеря сигнала тогда не равна потере самого задания.

События не сохраняются как очередь для будущего клиента. Если commit произошёл до регистрации или клиент был отключён, он не получает исторический журнал при подключении. Поэтому запуск worker начинается с чтения сохранённой работы, а событие служит подсказкой для следующего чтения. В API ожидания есть также гонка между внешней отметкой готовности и внутренней регистрацией; проект явно показывает её ограниченное решение, а не обещает встроенный тайм-аут.

Вызов не подходит для бесконечного ожидания внутри обычного HTTP-запроса страницы: он занимает worker и зависит от лимитов веб-сервера. Для отдельного процесса проектируют остановку и повторное подключение. Альтернатива в этой же главе — регистрация callback, но она также не превращает события в надёжную очередь. Ошибки считывают сразу через ibase_errcode и ibase_errmsg, до следующего успешного вызова драйвера.

Историческая пометка PHP Manual «PHP 5, PHP 7 < 7.4» относится к расширению прежних поставок PHP. Здесь используется отдельное interbase 3.0.1 с PHP 8.2.35 NTS x64 и Firebird 5.0.4. Наличие похожего имени в PDO или другом драйвере не означает наличие этих функций. Настройка окружения и все файлы находятся в README архива. Реальные события проверяются между двумя PHP-процессами; это не вывод заранее подготовленной строки.

• PHP: ibase_wait_event
• Firebird 5: POST_EVENT
• Firebird: модель событий
• Firebird driver: свойства доставки событий
• Реализация interbase 3.0.1: события

Исторически PHP 5 и PHP 7 до 7.4; далее внешнее расширение. Проверяемый профиль interbase 3.0.1 / PHP 8.2. · interbase

ibase_set_event_handler(resource $connection, callable $callback, string $event_name, string ...$event_names): resource|false

Если процессу нужно продолжать управлять своей работой, ему можно зарегистрировать функцию обратного вызова. ibase_set_event_handler сохраняет подписку, а при событии драйвер вызовет вашу функцию. Самый понятный обработчик лишь помечает данные как устаревшие; SQL и запись результата выполняет основной код после этого.

ibase_set_event_handler(callable $callback, string $event_name, string ...$event_names): resource|false
ibase_set_event_handler(resource $connection, callable $callback, string $event_name, string ...$event_names): resource|false

Применение 1: обновить складское представление после commit

$GLOBALS['refreshCatalog'] = false;
function onCatalogChange($eventName, $connection) {
    $GLOBALS['refreshCatalog'] = true;
    return true;
}
$handler = ibase_set_event_handler($db, 'onCatalogChange', 'CATALOG_CHANGED');
if ($handler === false) {
    throw new RuntimeException('Подписка не установлена');
}

Это регистрация, а не полный цикл worker. Основной код позднее проверит флаг, выберет свежие данные, обработает остановку и освободит handler. В самостоятельном сравнении rollback и commit есть два настоящих подключения, синхронизация готовности, конкретные 3 → 7 и завершение ресурсов. Преждевременный сигнал о ещё не принятом значении 99 не становится полезным результатом.

Применение 2: прекратить одноразовую подписку после сигнала

$GLOBALS['reportMayBeReady'] = false;
function reportReadyOnce($eventName, $connection) {
    $GLOBALS['reportMayBeReady'] = true;
    return false;
}
$handler = ibase_set_event_handler($db, 'reportReadyOnce', 'REPORT_CHANGED');
// Основной код проверяет сохранённый статус отчёта через SELECT.
// Когда handler больше не нужен, он отдельно освобождает ресурс в finally.

Одноразовость означает прекращение уведомлений, а не доказательство завершения любого отчёта. Имя не несёт ID: проверяйте нужный отчёт по сохранённому ключу. Возврат false отменяет дальнейшую обработку; сохранённую ссылку на ресурс в конце всё равно нужно освободить. Полный пример явного снятия подписки показывает другой управляемый способ: free после обработки первого подтверждённого состояния.

Ограничения именно реализации interbase 3.0.1

Исходник драйвера отличает необязательное соединение по типу первого аргумента. Поэтому короткая форма с замыканием или массивом callable без явного соединения не равнозначна общему обещанию callable в документации; передавайте $db первым. Также цикл регистрации данной версии сохраняет не более 13 имён при явном соединении (14 в короткой строковой форме), хотя PHP Manual сообщает 15. Это замечание по прочитанному исходнику, а не отдельный испытанный максимум. Наши работающие проекты подписаны на одно имя.

Обработка нативного буфера в этой версии выбирает первое имя с ненулевым внутренним счётчиком; PHP эти счётчики не получает. Не используйте её как перечислитель всех изменений. У Firebird нет гарантии нужной приложению группировки уведомлений: три POST могут прийти иначе, чем три вызова функции. Практика с двумя товарами и тремя POST_EVENT сохраняет фактическое число callback отдельно и проверяет нужные строки базы, а не удобное предполагаемое количество вызовов.

Callback вызывается нативным клиентом асинхронно. Держите его коротким, не выполняйте в нём длительный ввод-вывод, SQL на том же ресурсе и освобождение самого активного обработчика. В примере callback лишь сохраняет простые наблюдения; операции с ресурсами делает основной код. Реальный запуск подтверждает конкретный профиль, но не автоматически все сочетания PHP, NTS/TS, клиентских библиотек и режимов сервера. Отдельный listener и внешний предел времени делают эту лабораторию контролируемой.

Историческая пометка PHP Manual «PHP 5, PHP 7 < 7.4» относится к расширению прежних поставок PHP. Здесь используется отдельное interbase 3.0.1 с PHP 8.2.35 NTS x64 и Firebird 5.0.4. Наличие похожего имени в PDO или другом драйвере не означает наличие этих функций. Настройка окружения и все файлы находятся в README архива. Реальные события проверяются между двумя PHP-процессами; это не вывод заранее подготовленной строки.

• PHP: ibase_set_event_handler
• Firebird 5: POST_EVENT
• Firebird: модель событий
• Firebird driver: свойства доставки событий
• Реализация interbase 3.0.1: события

Исторически PHP 5 и PHP 7 до 7.4; далее внешнее расширение. Проверяемый профиль interbase 3.0.1 / PHP 8.2. · interbase

ibase_free_event_handler(resource $event): bool

Когда экран закрывается или worker завершает задачу, ему нужно снять собственную подписку. ibase_free_event_handler освобождает handler и прекращает вызовы связанного с ним callback. Она не отменяет UPDATE, не выполняет rollback и не удаляет само имя события из базы для всех остальных клиентов.

ibase_free_event_handler(resource $event): bool

Применение 1: подписка существует ровно на время работы

$handler = ibase_set_event_handler($db, 'onCatalogChange', 'CATALOG_CHANGED');
if ($handler === false) {
    throw new RuntimeException('Нет подписки');
}
try {
    // Здесь ограниченный цикл приложения, работа с флагом обновления и остановкой.
} finally {
    if (ibase_free_event_handler($handler) !== true) {
        throw new RuntimeException('Подписка не освобождена');
    }
    $handler = null;
}

callback onCatalogChange определён в предыдущей карточке. finally выполняет завершение и при выходе из блока, и при исключении; проект должен также сохранять причину исходной ошибки. Это контекстный шаблон владения, а полный запускаемый пример имеет настоящий отправитель: сначала он сохраняет 7, затем после free сохраняет 11. Результат показывает 11 в SQL и отсутствие прироста callback этой подписки.

Применение 2: переключить worker на другой канал

if (ibase_free_event_handler($oldHandler) !== true) {
    throw new RuntimeException('Старая подписка не остановлена');
}
$oldHandler = null;
$newHandler = ibase_set_event_handler($db, 'onCatalogChange', 'OTHER_CATALOG_CHANGED');
if ($newHandler === false) {
    throw new RuntimeException('Новая подписка не установлена');
}
// Сразу перечитать сохранённое состояние нового каталога через SELECT.

Это не атомарная замена каналов. Между освобождением и регистрацией существует промежуток; события не являются сохраняемой очередью. После смены подписки перечитывают текущее состояние или сохранённые задания, а не ожидают, что новое соединение получит прошлые сигналы. Для надёжного учёта операций нужна таблица состояния и правило повторного чтения.

В interbase 3.0.1 нельзя экспериментировать с повторным вызовом на уже освобождённом ресурсе: внутренний fetch такого ресурса не во всех ветках безопасно обработан. Обнуляйте свою переменную и не храните её копии как якобы действующий handler. Не закрывайте соединение раньше события и не передавайте handle между PHP-процессами. Каждый процесс в лаборатории освобождает только собственные ресурсы.

После возврата false из callback дальнейшая доставка прекращается, но владение сохранённым ресурсом всё равно нужно завершить. Если целью является отмена данных, переходите к ibase_rollback; если обычное закрытие соединения — к ibase_close. Для создания новой подписки служит ibase_set_event_handler, а для синхронного ожидания без сохранённого handler — ibase_wait_event.

Историческая пометка PHP Manual «PHP 5, PHP 7 < 7.4» относится к расширению прежних поставок PHP. Здесь используется отдельное interbase 3.0.1 с PHP 8.2.35 NTS x64 и Firebird 5.0.4. Наличие похожего имени в PDO или другом драйвере не означает наличие этих функций. Настройка окружения и все файлы находятся в README архива. Реальные события проверяются между двумя PHP-процессами; это не вывод заранее подготовленной строки.

• PHP: ibase_free_event_handler
• Firebird 5: POST_EVENT
• Firebird: модель событий
• Firebird driver: свойства доставки событий
• Реализация interbase 3.0.1: события