> 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/architecture.md).

# Architecture

## Core object

The package is centered on `Quantum\Hook\HookManager`.

It keeps one internal property:

```php
private array $store = [];
```

The store shape is:

```php
array<string, array<int, callable>>
```

Each key is a registered hook name. Each value is the queued listeners for that hook.

## Registration model

Hook names are created through the protected `register()` method.

Registration rules are simple:

* if the name already exists in `$store`, `register()` throws `HookException::hookDuplicateName()`
* otherwise it creates an empty array for that hook name

Because `register()` is protected, package consumers cannot add hook names directly through the public API. Public use depends on whatever hook names were loaded during construction.

## Listener lifecycle

`on(string $name, callable $function)` appends the callable to `$store[$name][]`.

Before that, it checks `exists($name)`. If the hook name is unknown, it throws `HookException::unregisteredHookName()`.

There is no deduplication for listeners. The same callable can be queued multiple times.

## Fire lifecycle

`fire(string $name, ?array $args = null)` also validates the hook name first.

It then iterates over the queued listeners for that hook:

```php
foreach ($this->store[$name] as $index => $fn) {
    unset($this->store[$name][$index]);
    $fn($args);
}
```

This has two important consequences:

* each listener is removed before it runs
* firing the same hook again does nothing unless new listeners were added after the previous fire

The package therefore behaves more like a deferred callback queue than a reusable publish-subscribe bus.

## Read access

`getRegistered()` returns the full internal store.

That includes registered hook names and their currently queued listeners. It is a snapshot of the manager state at the time of the call.

## Error surface

The package defines two package-specific runtime errors:

* duplicate hook registration -> `HookException::hookDuplicateName()`
* missing hook name -> `HookException::unregisteredHookName()`

The constructor can also surface dependency errors from config loading and DI resolution because it calls `config()` and may import `config/hooks` automatically.


---

# 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/architecture.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.