# Hooks — низкоуровневый диспетчер

`App\Helpers\Hooks` — низкоуровневая регистрация и отправка событий/фильтров.
Стабильные системные точки, контексты и подключение через модуль описаны в
[разделе «Хуки и события»](../hooks/README.md).
Два вида:

- **action** — «событие»: обработчики выполняют побочные эффекты, ничего не
  возвращают.
- **filter** — «фильтр»: значение пропускается через цепочку и возвращается
  изменённым.

```php
use App\Helpers\Hooks;
```

---

## Подписка

### `add($name, $function, $priority = 10)`
Подписать обработчик. **Меньший приоритет = раньше** выполняется.
### `once($name, $function, $priority = 10)` — сработает один раз.
### `remove($name, $function, $priority = 10)` — отписать.

```php
Hooks::add('reviews.title', function ($title) {
    return trim((string) $title);
}, 10);
```

---

## Вызов

### `action($name, $arguments = '')`
Выполнить все обработчики события. Если подписчиков нет — вернёт `$arguments` как есть.
```php
Hooks::action('reviews.rebuilt', $summary);
```

### `filter($name, $value)`
Пропустить `$value` через цепочку фильтров и получить результат. Нет подписчиков —
вернёт исходное значение.
```php
Hooks::add('document.title', function ($t) { return trim($t); });
Hooks::add('document.title', function ($t) { return mb_strtoupper($t, 'UTF-8'); }, 20);

$title = Hooks::filter('document.title', $rawTitle);
```

---

## Интроспекция

| Метод | Назначение |
| --- | --- |
| `exists($name)` | Зарегистрирован ли хук. |
| `has($hook, $priority = 10)` | Есть ли обработчик на приоритете. |
| `current()` | Имя текущего выполняемого хука. |
| `debug()` | Отладочный дамп подписок. |
| `trace()`, `enableTrace()` | Структурированный runtime trace для защищённого отладчика. |
| `resetRuntime()` | Очистить runtime-журнал между запросами долгоживущего процесса. |
| `init()` | Инициализация системы (вызывается ядром). |

---

## action vs filter — как выбрать

| Нужно… | Метод |
| --- | --- |
| Сделать что-то в ответ на событие (очистить кеш, залогировать) | `action` |
| Изменить/дополнить значение и вернуть его | `filter` |

> Порядок выполнения определяется приоритетом (по возрастанию). Одинаковый
> приоритет — в порядке добавления.