Collectors

Collectors

Use a collector when several callbacks should contribute independently. Register with addCollector() and call collect() with the arguments every callback needs.

For example, dashboard cards may come from several packages. Each package can return one card without knowing about the others.

Register and collect

The collector methods have two jobs:

Method	Use it for	Returns
addCollector()	Registering a callback that contributes one result.	A RegistrationHandle.
collect()	Invoking every collector with the same arguments.	One raw result per listener.

addCollector()

public function addCollector(
  string $hookPoint,
  array|callable $callback,
  int $priority = 10,
): RegistrationHandle

Use it when:

you want an independent module to contribute one result to a collection.

Applies to: Collectors

Returns: A handle for this exact registration.

With no listeners: The registration is stored, but contributes nothing until collect() runs.

Exceptions: Callback and resolver exceptions surface when the collector is invoked.

Configuration: Yes. The callback remains registered until removed.

collect()

public function collect(
  string $hookPoint,
  mixed ...$arguments,
): array

Use it when:

you want the raw contributions and will decide how to interpret them.

Applies to: Collectors

Returns: One raw callback result per listener, in priority and registration order.

With no listeners: An empty array is returned.

Exceptions: Exceptions from listeners bubble to the caller.

Configuration: No. It does not configure or change a processor or renderer.

The default priority is 10. collect() does not merge, flatten, process, or render the returned entries; choose those operations explicitly when you need them.

Every listener receives the same explicit arguments, and its return value becomes one entry in the result array:

PHP

use Magdicom\Hooks;

$hooks = new Hooks();

$hooks->addCollector('dashboard.widgets', static fn (string $userId): array => ['owner' => $userId]);
$hooks->addCollector('dashboard.widgets', static fn (string $userId): array => ['count' => 3]);

$cards = $hooks->collect('dashboard.widgets', 'user-42');
// [['owner' => 'user-42'], ['count' => 3]]

Laravel

hooks()->addCollector('dashboard.widgets', static fn (string $userId): array => ['owner' => $userId]);
hooks()->addCollector('dashboard.widgets', static fn (string $userId): array => ['count' => 3]);

$cards = hooks()->collect('dashboard.widgets', 'user-42');
// [['owner' => 'user-42'], ['count' => 3]]

collect() preserves dispatch order and leaves interpretation to you. It does not flatten nested arrays, merge associative keys, or discard duplicates.

Priority and empty results

The default priority is 10. Lower priorities run first, and equal priorities preserve registration order. With no listeners, a collector returns []:

<?php

declare(strict_types=1);

use Magdicom\Hooks;

$hooks = new Hooks();

$results = $hooks->collect('navigation.items');
// []

Arguments are explicit. collect('navigation.items', $userId) passes $userId to every listener; Hooks does not keep a global parameter array or hidden invocation state.

Remove a collector

As with the other hook types, addCollector() returns a handle for that exact registration:

<?php

declare(strict_types=1);

use Magdicom\Hooks;

$hooks = new Hooks();

$handle = $hooks->addCollector('navigation.items', static fn (): string => 'Help');
$handle->remove();

$items = $hooks->collect('navigation.items');
// []

removeCollector() removes the first matching callback at the requested priority. removeAllCollectors(?string $hookPoint = null) removes collector registrations in bulk.

collect(), process(), and render()

These methods have different jobs:

• collect() returns the raw result array. It does not need a processor or renderer.
• process() collects results and passes them with a ProcessingContext to the configured processor. It throws MissingProcessorException when no processor is configured.
• render() collects results and passes them to the configured renderer, which must return a string. Missing or invalid renderer configuration raises the documented renderer exceptions.

Processors and renderers apply to collectors only—not actions or filters. See processors and renderers for the released built-ins and their failure behavior.