> For the complete documentation index, see [llms.txt](https://quantumphp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumphp.gitbook.io/docs/packages/hook/overview.md).

# Overview

The Hook package provides a small in-process event queue.

It lets code register named hooks, attach listeners to those hooks, and fire each hook later with one optional argument array.

In normal application code, the main entry points are `Quantum\Hook\HookManager` and the global `hook()` helper.

## Package shape

The package contains four source pieces:

* `Quantum\Hook\HookManager` loads configured hook names, stores listeners, and fires hooks
* `Quantum\Hook\Helpers\hook.php` exposes the shared `hook()` helper
* `Quantum\Hook\Exceptions\HookException` defines package-specific runtime errors
* `Quantum\Hook\Enums\ExceptionMessages` stores local exception message templates

## What the package actually does

`HookManager` creates a registry of hook names first, then allows listeners to be attached only to registered names.

When a hook is fired, the manager calls every queued listener for that hook and removes each listener from the store before invoking it. In practice, listeners are one-shot callbacks, not persistent subscriptions.

## Startup behavior

The constructor ensures a `hooks` config entry exists:

1. if `config()->has('hooks')` is false, it imports `config/hooks`
2. it merges `HookManager::CORE_HOOKS` with `config()->get('hooks') ?: []`
3. it registers each resulting hook name into the internal store

`CORE_HOOKS` is currently an empty array, so out of the box the package depends on the configured hook list.

Use a flat list of hook names in `config/hooks`, for example:

```php
return [
    'user.registered',
    'mail.sent',
    'report.generated',
];
```

If the list contains duplicate names, manager construction fails before you can attach or fire listeners.

## Important constraints

* hook names must be registered before `on()` or `fire()` can use them
* `config/hooks` should return a plain list of hook names, not a nested structure
* duplicate hook names fail during registration, including duplicates loaded from configuration
* unregistered hook names fail both when attaching listeners and when firing
* firing a registered hook with no queued listeners is a no-op
* listeners are consumed on first `fire()` call
* `fire()` always passes exactly one argument to each listener: the `?array $args` value
* a newly registered hook starts with an empty listener queue

## What the package does not do

The package is intentionally narrow.

It does not:

* provide listener priorities
* keep listeners after they are fired
* return values from listeners
* aggregate listener results
* expose a public API for registering new hook names after construction
* include wildcard hooks or pattern matching


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://quantumphp.gitbook.io/docs/packages/hook/overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.