Справочник по основным хукам и фильтрам: полное руководство для разработчиков

Last updated on Aug 23, 2026 5:50 PM 5:50 PM 261.19 ms

Справочник по основным хукам и фильтрам

Аудитория: Разработчик - Требуются знания PHP/Laravel. Категория: Технический справочник - Техническая документация для интегрированных программистов.

Чему вы научитесь

[] Понимание механизма действия и фильтра в PolyCMS.
Поиск имени крюка, параметров, места отправки
Уметь регистрировать хуки из темы functions.php и модуля ServiceProvider
Использовать приоритет для управления порядком выполнения
Применить реальные варианты использования к каждой группе крючков.

1. Знакомство с системой Hook

PolyCMS использует систему Hook/Filter, аналогичную WordPress, изначально созданную на Laravel:

Действие (Hook::doAction): запуск побочных эффектов (ведение журнала, отправка электронной почты, синхронизация данных). Нет необходимости возвращаться.
Filter (Hook::applyFilters): получить значение, отредактировать и принудительно вернуть скорректированное значение.

Основной синтаксис

use App\Facades\Hook;

// Sign up for Action
Hook::addAction('order_completed', function ($order) {
    Mail::to($order->user)->send(new OrderCompletedMail($order));
}, priority: 10);

// Sign up for Filter
Hook::addFilter('post.default_image', function (?string $imageUrl, $post) {
    if ($post?->categories->contains('slug', 'news')) {
        return '/images/news-default.jpg';
    }
    return $imageUrl;
}, priority: 10);

2. Контент и публикации

Фильтры

Крюк	Параметры	Описание
`post.default_image`	`$imageUrl, $context`	Изображение по умолчанию, если в статье нет избранного изображения
`post.frontend_url`	`$url, $post`	Настройте общедоступный URL-адрес публикации
`post.content.render`	`$html, $post`	Фильтрация содержимого HTML перед возвратом API
`post.query.builder`	`$query, $request`	Редактировать запрос Eloquent для списка сообщений
`category.frontend_url`	`$url, $category`	Настройте общедоступный URL-адрес вашей категории
`content.render.blocks`	`$blocks`	Фильтровать массив блоков перед рендерингом
`content.render.html`	`$html, $blocks`	Фильтрация конечного вывода HTML
`content.render.block.{type}`	`$html, $block`	Отображение или переопределение определенного типа блока

Действия

Крюк	Параметры	Описание
`tag.saved`	`$tag, $context`	После создания/обновления тега
`tag.deleted`	`$tag, $context`	После удаления тега
`category.saved`	`$category, $context`	После создания/обновления категории
`category.deleted`	`$category, $context`	После удаления категории

Практические примеры использования

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

Hook::addFilter('post.default_image', function (?string $url, $post) {
    if ($post?->categories->contains('slug', 'tech')) return '/images/defaults/tech.jpg';
    if ($post?->categories->contains('slug', 'lifestyle')) return '/images/defaults/lifestyle.jpg';
    return $url; // fallback admin setting
});

UC2 - URL-адрес Wiki: Тема документа требует переместить URL-адрес публикации из /posts/slug в /docs/slug:

Hook::addFilter('post.frontend_url', function ($url, $post) {
    return ($post->type === 'wiki') ? '/docs/' . $post->slug : $url;
});

UC3 - Автоматическая вставка рекламы: Рекламный модуль хочет вставить баннер после третьего абзаца в тексте статьи:

Hook::addFilter('content.render.html', function (string $html) {
    $adBanner = '<div class=\"ad-inline\">Advertisement</div>';
    $parts = explode('</p>', $html, 4);
    if (count($parts) > 3) {
        $parts[2] .= '</p>' . $adBanner;
        return implode('</p>', $parts);
    }
    return $html;
});

3. Медиатека

Фильтры

Крюк	Параметры	Описание
`media.upload.file`	`$file, $data`	Редактировать файлы перед обработкой
`media.upload.data`	`$data, $file`	Редактировать метаданные загрузки
`media.create.data`	`$mediaData, $file`	Настройте данные записи перед сохранением БД
`media.delete.should`	`$shouldDelete, $media`	Ворота: верните false, чтобы предотвратить удаление
`media.url`	`$url, $media`	Перезаписать URL-адрес (e.g. CDN)

Действия

Крюк	Параметры	Описание
`media.uploaded`	`$media, $file, $data`	После успешной загрузки
`media.deleting`	`$media`	Перед удалением
`media.deleted`	`$media`	После удаления

Практические примеры использования

UC1 - перезапись CDN: интегрирует Cloudflare R2/S3, автоматически преобразует URL-адреса мультимедиа в домен CDN:

Hook::addFilter('media.url', function (string $url, $media) {
    return str_replace('/storage/', 'https://cdn.mysite.com/', $url);
});

UC2 - Защитите важные файлы. Запретите удаление изображений, используемых в качестве логотипов сайта:

Hook::addFilter('media.delete.should', function (bool $allow, $media) {
    $logoUrl = get_option('site_logo', null, 'general');
    return ($media->url === $logoUrl) ? false : $allow;
});

UC3 - Автоматическая оптимизация при загрузке: Автоматически создавать WebP из загруженных изображений:

Hook::addAction('media.uploaded', function ($media, $file) {
    if (str_starts_with($media->mime_type, 'image/')) {
        dispatch(new ConvertToWebpJob($media));
    }
});

4. Электронная коммерция - заказы и возврат средств

Действия

Крюк	Параметры	Описание
`order_status_updated`	`$order, $oldStatus, $newStatus`	При изменении статуса заказа
`order_completed`	`$order`	Когда заказ выполнен
`order.refund.processing`	`$order, $validated`	Прежде чем сделать возврат
`order.refund.completed`	`$order, $result`	После успешного возврата
`order.refund.succeeded`	`$order, $result, $validated, $userId`	Возврат API успешен
`order.refund.failed`	`$order, $validated, $exception, $userId`	Возврат API не удался

Фильтры

Крюк	Параметры	Описание
`order.refund.preview.result`	`$preview, $order, $input`	Предварительный просмотр настройки возврата

Практические примеры использования

UC1 - уведомление в Telegram при появлении нового заказа:

Hook::addAction('order_status_updated', function ($order, $old, $new) {
    if ($old === 'pending' && $new === 'processing') {
        TelegramBot::send("Order #{$order->code} has been confirmed!");
    }
});

UC2 - Зарабатывайте баллы лояльности при заполнении заявки:

Hook::addAction('order_completed', function ($order) {
    if ($order->user_id) {
        $points = (int) floor($order->total / 10000); // 1 point per 10k
        LoyaltyService::addPoints($order->user_id, $points, "Order #{$order->code}");
    }
});

UC3 - запись журнала аудита в случае неудачного возврата средств:

Hook::addAction('order.refund.failed', function ($order, $data, $exception, $userId) {
    AuditLog::create([
        'action' => 'refund_failed',
        'order_id' => $order->id,
        'user_id' => $userId,
        'reason' => $exception->getMessage(),
    ]);
});

5. Электронная коммерция - корзина, доставка, налоги, инвентарь.

Фильтры

Крюк	Параметры	Описание
`cart.totals`	`$totals, $cart`	Изменить общую сумму корзины
`shipping.calculate_cost`	`$cost, $method, $cart`	Отменить стоимость доставки
`shipping.available_methods`	`$methods, $address, $cart`	Фильтровать способы доставки
`tax.calculated`	`$result, $subtotal, $address`	Переопределить результаты расчета налога
`inventory.is_stockable_product`	`$default, $product, $context`	Идентификация продуктов с помощью управления запасами
`review.can_submit`	`$allowed, $user, $product`	Gate: разрешены ли отзывы?

Действия

Крюк	Параметры	Описание
`cart.item.added`	`$item, $cart`	После добавления товаров в корзину
`cart.item.updated`	`$item, $oldQty, $newQty`	После обновления количества
`cart.item.removed`	`$item, $cart`	После удаления товаров из корзины
`cart.cleared`	`$cart`	После удаления всей корзины
`cart.merged`	`$userCart, $guestCart`	При объединении гостевой корзины с пользовательской
`review.submitted`	`$review`	После отправки отзыва
`review.approved`	`$review`	После просмотра отзывов
`review.rejected`	`$review`	После отклонения отзыва

Практические примеры использования

UC1 - Бесплатная доставка для заказов на сумму более 500 000:

Hook::addFilter('shipping.calculate_cost', function ($cost, $method, $cart) {
    $subtotal = collect($cart->items)->sum(fn($i) => $i->price * $i->quantity);
    return ($subtotal >= 500000) ? 0 : $cost;
});

UC2 - Блокируйте отзывы, если вы еще не купили:

Hook::addFilter('review.can_submit', function (bool $allowed, $user, $product) {
    $hasPurchased = Order::where('user_id', $user->id)
        ->where('status', 'completed')
        ->whereHas('items', fn($q) => $q->where('product_id', $product->id))
        ->exists();
    return $hasPurchased;
});

UC3 - отслеживание пикселей Facebook при добавлении корзины:

Hook::addAction('cart.item.added', function ($item, $cart) {
    session()->push('fb_pixel_events', [
        'event' => 'AddToCart',
        'product_id' => $item->product_id,
        'value' => $item->price,
    ]);
});

6. Электронная коммерция - платежные шлюзы

Фильтры

Крюк	Параметры	Описание
`payment.gateway.config_schema`	`$schema, $gateway`	Разверните схему конфигурации шлюза

Вариант использования: добавьте поле «Код отделения» для шлюза банковских переводов:

Hook::addFilter('payment.gateway.config_schema', function ($schema, $gateway) {
    if ($gateway->code === 'bank_transfer') {
        $schema['branch_code'] = [
            'type' => 'text', 'label' => 'Branch code', 'required' => false,
        ];
    }
    return $schema;
});

7. Тема и внешний вид

Фильтры

Крюк	Параметры	Описание
`theme.view.data`	`$data, $viewName`	Вставка данных в любое представление
`theme.template.resolve`	`$viewName, $templateTheme, $entityType, $entity`	Представление Override Blade отображается
`theme.template.registry`	`$templates, $viewType`	Зарегистрируйте новый шаблон страницы
`theme.options.values`	`$options`	Фильтрация параметров темы
`theme.options.css_vars`	`$cssVars, $themeOptionValues`	Настройка пользовательских свойств CSS
`theme.breadcrumbs.post`	`$breadcrumbs, $post`	Редактировать навигационную цепочку статьи
`theme.breadcrumbs.product`	`$breadcrumbs, $product`	Редактировать хлебные крошки продукта
`theme.show_page_header`	`$show, $page`	Скрыть/показать заголовок страницы
`frontend.topbar.banners`	`$banners`	Внедрить рекламные баннеры
`themes.list`	`$themes`	Фильтрация списка тем администратора

Действия

Крюк	Параметры	Описание
`theme.activated`	`$theme`	Когда загружена основная тема
`theme.main.changed`	`$theme, $oldMainTheme`	При смене основной темы
`theme.installing`	`$file`	Перед обработкой темы ZIP
`theme.activating`	`$slug, $type, $mode`	Перед активацией темы
`theme.deactivating`	`$slug`	Перед деактивацией темы
`theme.deleting`	`$theme`	Перед удалением темы
`cms_head`	(нет)	Перехватчик вывода в `<head>`

Практические примеры использования

UC1 - Рекламный баннер на весь сайт из модуля:

Hook::addFilter('frontend.topbar.banners', function (array $banners) {
    $banners[] = [
        'text' => ' Flash Sale - 30% off today!',
        'url' => '/sale',
        'bg_color' => '#ff4444',
    ];
    return $banners;
});

UC2 - внедрить Google Analytics в <head>:

Hook::addAction('cms_head', function () {
    $ga = get_option('google_analytics_id', null, 'seo');
    if ($ga) {
        echo "<script async src='https://www.googletagmanager.com/gtag/js?id={$ga}'></script>";
    }
});

UC3 - Вставка данных боковой панели для страницы блога:

Hook::addFilter('theme.view.data', function ($data, $viewName) {
    if ($viewName === 'posts.index') {
        $data['popular_posts'] = Post::orderBy('views', 'desc')->limit(5)->get();
    }
    return $data;
});

8. Настройки и конфигурация

Фильтры

Крюк	Параметры	Описание
`settings.defaults`	`$defaults, $settingsService`	Расширить/переопределить определения настроек
`settings.media.drivers`	`$drivers`	Зарегистрируйте новый драйвер хранилища
`settings.permalinks.structure`	`$structure, $settingsService`	Изменить структуру постоянных ссылок

Действия

Крюк	Параметры	Описание
`setting.updating`	`$key, $value, $group, $type`	Перед сохранением настроек
`settings.saved`	`$payload`	После сохранения настроек

Практические примеры использования

UC1 - Модуль регистрирует отдельные настройки на странице «Настройки»:

Hook::addFilter('settings.defaults', function ($defaults) {
    $defaults['mymodule'] = [
        'mymodule_api_key' => [
            'key' => 'mymodule_api_key', 'value' => '', 'type' => 'text',
            'label' => 'API Key', 'description' => 'Enter your API key',
        ],
    ];
    return $defaults;
});

UC2 - Очистить кеш при обновлении постоянной ссылки:

Hook::addAction('settings.saved', function ($payload) {
    if (($payload['group'] ?? '') === 'permalinks') {
        Artisan::call('route:clear');
        Cache::tags('routes')->flush();
    }
});

9. Пользователи, роли и аутентификация

Фильтры

Крюк	Параметры	Описание
`user.resource.to_array`	`$data, $user, $request`	Развернуть ответ пользовательского API
`auth.login.pre_token`	`$response, $user, $request`	Перехват входа (для 2FA)

Действия

Крюк	Параметры	Описание
`user.creating` / `user.updating` / `user.deleting`	`$user\|$data`	Жизненный цикл CRUD
`role.creating` / `role.updating` / `role.deleting` / `role.cloning`	`$role\|$data`	Жизненный цикл CRUD

Практические примеры использования

UC1 - для администратора требуется двухфакторная аутентификация:

Hook::addFilter('auth.login.pre_token', function ($response, $user, $request) {
    if ($user->hasRole('admin') && !$request->filled('otp_code')) {
        return response()->json(['requires_2fa' => true, 'user_id' => $user->id], 403);
    }
    return $response; // null = continue creating tokens
});

UC2 - Отправка приветственного письма при создании пользователя:

Hook::addAction('user.creating', function ($data) {
    // Queued email will be sent after the user is saved
    dispatch(new SendWelcomeEmail($data['email'], $data['name']));
});

10. SEO

Фильтры

Крюк	Параметры	Описание
`seo.canonical_url`	`$url`	Переопределить канонический URL
`seo.site_favicon`	`$iconUrl`	Переопределить URL-адрес значка

Вариант использования - канонический URL-адрес для нескольких языков:

Hook::addFilter('seo.canonical_url', function (string $url) {
    $locale = app()->getLocale();
    if ($locale !== 'en') {
        return url("/{$locale}" . parse_url($url, PHP_URL_PATH));
    }
    return $url;
});

11. Виджеты

Фильтры

Крюк	Параметры	Описание
`widget.render.instance`	`$instance`	Настройте экземпляр виджета перед рендерингом
`widget.render.{widget_type}`	`$widget`	Редактировать определенные данные виджета
`widget.area.render.instances`	`$instances, $area`	Фильтровать экземпляры по области
`widget.render.output`	`$html, $instance`	Виджет фильтра вывода HTML
`widget.area.render.output`	`$html, $area`	Фильтрация области вывода HTML
`widgets.types`	`$widgets`	Фильтровать типы виджетов администратор

Действия

Крюк	Параметры	Описание
`widgets.register_types`	`$widgetManager`	Зарегистрируйте виджет нового типа
`widgets.register_areas`	`$widgetManager`	Зарегистрируйте новую область виджетов

Вариант использования - зарегистрировать тип виджета «Карта магазина»:

Hook::addAction('widgets.register_types', function ($manager) {
    $manager->registerType('store_map', [
        'label' => 'Store Map',
        'description' => 'Google Maps showing store locations',
        'fields' => [
            'api_key' => ['type' => 'text', 'label' => 'Google Maps API Key'],
            'lat' => ['type' => 'text', 'label' => 'Latitude'],
            'lng' => ['type' => 'text', 'label' => 'Longitude'],
        ],
        'view' => 'widgets.store-map',
    ]);
});

12. Административная навигация и редактор

Фильтры

Крюк	Параметры	Описание
`topbar.menu.items`	`$items, $request, $user`	Добавить/удалить элемент верхней панели интерфейса
`topbar.menu.should_show`	`$show, $user`	Переключить отображение верхней панели
`admin.editor.panels`	`$panels, $type, $user`	Добавить пользовательскую панель в редактор блоков

Действия

Крюк	Параметры	Описание
`admin.menu.build`	(нет)	Когда создано боковое меню администратора
`topbar.menu.context`	`$request, $user`	Когда контекст верхней панели инициализируется

Вариант использования - модуль добавляет пункт меню «SEO Score» на верхнюю панель:

Hook::addFilter('topbar.menu.items', function (array $items, $request, $user) {
    $items[] = [
        'key' => 'seo_score',
        'label' => 'SEO Score',
        'icon' => 'chart-bar',
        'url' => '/admin/seo/score',
        'position' => 50,
    ];
    return $items;
});

13. Модули

Фильтры

Крюк	Параметры	Описание
`module.resource.meta`	`$meta, $moduleData`	Развернуть модуль метаданных
`modules.list`	`$modulesArray`	Фильтровать список модулей администратора
`product.query.builder`	`$query, $request`	Настройте запрос Eloquent для продуктов

Действия

Крюк	Параметры	Описание
`module.activating`	`$moduleKey, $module`	Перед активацией модуля
`module.deactivating`	`$moduleKey, $module`	Перед деактивацией модуля
`module.deleting`	`$moduleKey, $module`	Перед удалением модуля
`module.installing`	`$uploadedFile`	При установке ZIP

Вариант использования - запуск миграции при активации модуля:

Hook::addAction('module.activating', function ($moduleKey, $module) {
    Artisan::call('migrate', [
        '--path' => "modules/Polyx/{$moduleKey}/database/migrations",
        '--force' => true,
    ]);
});

14. Загрузка системы

Действия

Крюк	Параметры	Описание
`roles.register_permissions`	`$permissionRegistry`	Регистрация пользовательских разрешений
`register_email_templates`	`$emailTemplateManager`	Подпишитесь на рассылку шаблонов электронной почты
`layout.register_assets`	`$layoutAssetManager`	Зарегистрируйте ресурсы макета
`routes.frontend.register`	(нет)	Зарегистрируйте дополнительные маршруты интерфейса

Вариант использования - Модуль регистрации частных разрешений:

Hook::addAction('roles.register_permissions', function ($registry) {
    $registry->register('manage analytics', 'Analytics', 'View and manage analytics dashboard');
    $registry->register('export reports', 'Analytics', 'Export analytics reports to CSV');
});

Справочник по основным хукам и фильтрам: полное руководство для разработчиков

Справочник по основным хукам и фильтрам

Чему вы научитесь

1. Знакомство с системой Hook

Основной синтаксис

2. Контент и публикации

Фильтры

Действия

Практические примеры использования

3. Медиатека

Фильтры

Действия

Практические примеры использования

4. Электронная коммерция - заказы и возврат средств

Действия

Фильтры

Практические примеры использования

5. Электронная коммерция - корзина, доставка, налоги, инвентарь.

Фильтры

Действия

Практические примеры использования

6. Электронная коммерция - платежные шлюзы

Фильтры

Вариант использования: добавьте поле «Код отделения» для шлюза банковских переводов:

7. Тема и внешний вид

Фильтры

Действия

Практические примеры использования

8. Настройки и конфигурация

Фильтры

Действия

Практические примеры использования

9. Пользователи, роли и аутентификация

Фильтры

Действия

Практические примеры использования

10. SEO

Фильтры

Вариант использования - канонический URL-адрес для нескольких языков:

11. Виджеты

Фильтры

Действия

Вариант использования - зарегистрировать тип виджета «Карта магазина»:

12. Административная навигация и редактор

Фильтры

Действия

Вариант использования - модуль добавляет пункт меню «SEO Score» на верхнюю панель:

13. Модули

Фильтры

Действия

Вариант использования - запуск миграции при активации модуля:

14. Загрузка системы

Действия

Вариант использования - Модуль регистрации частных разрешений:

Похожие статьи