Processors

Processors reduce the raw results from a collector to one value. Use them when several modules contribute data but the caller needs a clear answer, such as the first available email, a merged list, or a boolean decision.

Processors apply only to collectors. Actions return void, and filters already return their transformed value.

Configure and process

The processor methods have distinct responsibilities:

Method	Use it for	Returns or does
`setProcessor()`	Configure the reduction for a collector point.	The same `Hooks` instance.
`hasProcessor()`	Check whether a processor is configured.	`bool`.
`processor()`	Inspect the configured processor reference.	A processor, callable, class name, or `null`.
`clearProcessor()`	Remove the configured processor.	`bool`.
`process()`	Collect and reduce results.	The processor output.
`processWith()`	Reduce one call without changing configuration.	The processor output.

setProcessor()

public function setProcessor(
  string $hookPoint,
  ResultProcessor|callable|string $processor,
): self

Use it when:

you want every later process() call for a collector to use the same reduction.

Applies to: Collectors and processors

Returns: The same Hooks instance.

Exceptions: An invalid class-name processor raises InvalidProcessorException when processing resolves it.

Configuration: Yes. It stores or replaces the collector's processing slot.

hasProcessor()

public function hasProcessor(string $hookPoint): bool

Use it when:

you need to check configuration before calling process().

Applies to: Collectors and processors

Returns: true when a processor slot exists, otherwise false.

Configuration: No. It only inspects configuration.

processor()

public function processor(string $hookPoint): ResultProcessor|callable|string|null

Use it when:

you need to inspect or replace the current processor reference.

Applies to: Collectors and processors

Returns: The stored processor reference, or null.

Configuration: No. It only inspects configuration.

clearProcessor()

public function clearProcessor(string $hookPoint): bool

Use it when:

you want to stop using the configured processor for a collector.

Applies to: Collectors and processors

Returns: true when a slot was removed; false when none existed.

Configuration: Yes. It removes the processor slot.

process()

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

Use it when:

you want to collect and reduce a collector’s results using its configured processor.

Applies to: Collectors and processors

Returns: The configured processor's output.

With no listeners: The collector supplies an empty array to the processor.

Exceptions: MissingProcessorException is thrown when no processor is configured; invalid processor classes raise InvalidProcessorException.

Configuration: No. It reads but does not change the configured slot.

processWith()

public function processWith(
  string $hookPoint,
  ResultProcessor|callable|string $processor,
  mixed ...$arguments,
): mixed

Use it when:

you need a different reduction for one call without changing the persistent choice.

Applies to: Collectors and processors

Returns: The supplied processor's output.

With no listeners: The supplied processor receives an empty result array.

Exceptions: Invalid processor class references raise InvalidProcessorException; custom processor exceptions propagate.

Configuration: No. The supplied processor is used once and is not stored.

Processors apply only to collectors. collect() still returns the raw list and bypasses this configuration.

collect() always returns raw callback results. process() collects those results and then applies the configured processor:

PHP
Laravel

use App\Models\Customer;
use Magdicom\Hooks;
use Magdicom\Processors\FirstNonNullProcessor;

$hooks = new Hooks();
$hooks->addCollector('customer.primary_email', static fn (Customer $customer): ?string => $customer->workEmail);
$hooks->addCollector('customer.primary_email', static fn (Customer $customer): ?string => $customer->personalEmail);
$hooks->setProcessor('customer.primary_email', FirstNonNullProcessor::class);

$email = $hooks->process('customer.primary_email', $customer);

use App\Models\Customer;
use Magdicom\Processors\FirstNonNullProcessor;

hooks()->addCollector('customer.primary_email', static fn (Customer $customer): ?string => $customer->workEmail);
hooks()->addCollector('customer.primary_email', static fn (Customer $customer): ?string => $customer->personalEmail);
hooks()->setProcessor('customer.primary_email', FirstNonNullProcessor::class);

$email = hooks()->process('customer.primary_email', $customer);

Calling collect('customer.primary_email', $customer) on the same endpoint still returns one raw result per listener. It bypasses processor and renderer configuration. Without a configured processor, process() throws MissingProcessorException. clearProcessor() removes the slot and reports whether one existed. setProcessor() replaces the processor for that collector point.

One-off processing

Use processWith() when the caller needs a different reduction for one invocation. It accepts the same processor instance, callable, or class name as setProcessor(), collects the listeners once, and passes the results and ProcessingContext to that processor. The supplied processor is not stored, and an existing configured processor remains unchanged.

This is useful when the same collector can be viewed in more than one way. For example, an endpoint may normally use a configured processor, while an export or fallback path needs the first available value for one call:

PHP
Laravel

use Magdicom\Hooks;
use Magdicom\Processors\FirstNonNullProcessor;

$hooks = new Hooks();
$hooks->addCollector('customer.email_candidates', static fn (): ?string => null);
$hooks->addCollector('customer.email_candidates', static fn (): ?string => 'billing@example.test');

$email = $hooks->processWith('customer.email_candidates', FirstNonNullProcessor::class);
// 'billing@example.test'

use Magdicom\Processors\FirstNonNullProcessor;

hooks()->addCollector('customer.email_candidates', static fn (): ?string => null);
hooks()->addCollector('customer.email_candidates', static fn (): ?string => 'billing@example.test');

$email = hooks()->processWith('customer.email_candidates', FirstNonNullProcessor::class);
// 'billing@example.test'

processWith() is part of magdicom/hooks v2.0.0-beta.2. Use it when one call needs a different processor without changing the persistent processor configured for that hook point.

Built-in processors

The released built-ins live under Magdicom\Processors and implement ResultProcessor. Each receives (array $results, ProcessingContext $context) and returns its documented value.

Processor	Collector results	Return value	Empty results	Keys and failures
`FirstProcessor`	Any values	First value	`null`	Keeps the selected value; no extra validation
`LastProcessor`	Any values	Last value	`null`	Keeps the selected value; no extra validation
`FirstNonNullProcessor`	Any values	First non-`null` value	`null`	Keeps the selected value; no extra validation
`MergeProcessor`	Arrays	One merged array	`[]`	`array_merge()` semantics; non-arrays throw `UnexpectedValueException`
`FlattenProcessor`	Arrays	One flattened array	`[]`	Numeric keys are reindexed and array keys are discarded; invalid depth or non-arrays throw
`BooleanAndProcessor`	Strict booleans	`bool`	`true`	Non-booleans throw `UnexpectedValueException`
`BooleanOrProcessor`	Strict booleans	`bool`	`false`	Non-booleans throw `UnexpectedValueException`

All built-ins receive the original hook point and invocation arguments through ProcessingContext. They do not add shortcut methods such as first(), last(), merge(), or flatten().

FirstProcessor

Use FirstProcessor when the first registered contribution wins. It returns the first raw result, or null when no collectors ran. It accepts any result type and has no configuration options.

use Magdicom\Hooks;
use Magdicom\Processors\FirstProcessor;

$hooks = new Hooks();
$hooks->addCollector('customer.primary_email', static fn (): ?string => 'work@example.test');
$hooks->addCollector('customer.primary_email', static fn (): ?string => 'personal@example.test');
$hooks->setProcessor('customer.primary_email', FirstProcessor::class);

$email = $hooks->process('customer.primary_email');
// 'work@example.test'

LastProcessor

LastProcessor is useful when later registration should provide the final fallback or override. It returns the last result, or null for an empty list. It accepts any result type and has no options.

use Magdicom\Hooks;
use Magdicom\Processors\LastProcessor;

$hooks = new Hooks();
$hooks->addCollector('checkout.banner', static fn (): string => 'Standard checkout');
$hooks->addCollector('checkout.banner', static fn (): string => 'Holiday checkout');
$hooks->setProcessor('checkout.banner', LastProcessor::class);

$banner = $hooks->process('checkout.banner');
// 'Holiday checkout'

FirstNonNullProcessor

FirstNonNullProcessor skips null results until it finds a value. It returns null when every result is null or there are no results. It accepts any result type and has no options.

use Magdicom\Hooks;
use Magdicom\Processors\FirstNonNullProcessor;

$hooks = new Hooks();
$hooks->addCollector('customer.primary_email', static fn (): ?string => null);
$hooks->addCollector('customer.primary_email', static fn (): ?string => 'personal@example.test');
$hooks->setProcessor('customer.primary_email', FirstNonNullProcessor::class);

$email = $hooks->process('customer.primary_email');
// 'personal@example.test'

MergeProcessor

Use MergeProcessor when each collector returns an array and the caller needs one combined array. It uses PHP’s array_merge() semantics: string keys later in the list overwrite earlier values, while numeric keys are reindexed. An empty result list returns []; a non-array result throws UnexpectedValueException.

use Magdicom\Hooks;
use Magdicom\Processors\MergeProcessor;

$hooks = new Hooks();
$hooks->addCollector('checkout.payment_data', static fn (): array => ['currency' => 'USD']);
$hooks->addCollector('checkout.payment_data', static fn (): array => ['provider' => 'card']);
$hooks->setProcessor('checkout.payment_data', MergeProcessor::class);

$data = $hooks->process('checkout.payment_data');
// ['currency' => 'USD', 'provider' => 'card']

FlattenProcessor

Use FlattenProcessor when collectors return nested arrays and the caller needs one list of values. Its constructor accepts depth, defaulting to -1 for unlimited flattening. Depth 0 keeps nested arrays at the current level; non-negative depths limit traversal. A depth below -1 throws InvalidArgumentException. Every top-level result must be an array or processing throws UnexpectedValueException. Flattening discards array keys and reindexes the result.

use Magdicom\Hooks;
use Magdicom\Processors\FlattenProcessor;

$hooks = new Hooks();
$hooks->addCollector('navigation.items', static fn (): array => ['Account', ['Billing', 'Help']]);
$hooks->setProcessor('navigation.items', new FlattenProcessor(depth: 1));

$items = $hooks->process('navigation.items');
// ['Account', 'Billing', 'Help']

BooleanAndProcessor

Use BooleanAndProcessor when every registered rule must approve a decision. Each collector must return a real bool; values are not coerced. It returns false as soon as it sees false, true for an empty result list, and throws UnexpectedValueException for any non-boolean result.

use Magdicom\Hooks;
use Magdicom\Processors\BooleanAndProcessor;

$hooks = new Hooks();
$hooks->addCollector('checkout.allowed', static fn (): bool => true);
$hooks->addCollector('checkout.allowed', static fn (): bool => true);
$hooks->setProcessor('checkout.allowed', new BooleanAndProcessor());

$allowed = $hooks->process('checkout.allowed');
// true

BooleanOrProcessor

Use BooleanOrProcessor when one approving rule is enough. Results must be real booleans. It returns true as soon as it sees true, false for an empty result list, and throws UnexpectedValueException for any non-boolean result.

use Magdicom\Hooks;
use Magdicom\Processors\BooleanOrProcessor;

$hooks = new Hooks();
$hooks->addCollector('checkout.expedited', static fn (): bool => false);
$hooks->addCollector('checkout.expedited', static fn (): bool => true);
$hooks->setProcessor('checkout.expedited', new BooleanOrProcessor());

$expedited = $hooks->process('checkout.expedited');
// true

Processor callbacks and class names

setProcessor() accepts a processor instance, a callable, or a class name. A callable receives the raw result array and ProcessingContext and may return any value:

use Magdicom\Hooks;
use Magdicom\ProcessingContext;

$hooks = new Hooks();
$hooks->addCollector('report.scores', static fn (): int => 8);
$hooks->addCollector('report.scores', static fn (): int => 13);
$hooks->setProcessor('report.scores', static function (array $results, ProcessingContext $context): int {
    return array_sum($results);
});

$total = $hooks->process('report.scores');
// 21

Class-name processors are resolved when process() runs and must implement ResultProcessor; otherwise InvalidProcessorException is thrown. The core NativeResolver creates a class with new $className(). Laravel replaces that resolver with a container-backed resolver, so constructor dependencies can be injected:

PHP
Laravel

use Magdicom\Hooks;
use Magdicom\Processors\FirstNonNullProcessor;

$hooks = new Hooks();
$hooks->setProcessor('customer.primary_email', FirstNonNullProcessor::class);
$email = $hooks->process('customer.primary_email', $customer);

use Magdicom\Processors\FirstNonNullProcessor;

hooks()->setProcessor('customer.primary_email', FirstNonNullProcessor::class);
$email = hooks()->process('customer.primary_email', $customer);

The same class-name configuration is shown in both tabs; Laravel’s resolver is what changes how the class is constructed. Custom processor exceptions propagate unchanged.

See renderers for string-specific collector output, and collectors for raw collection semantics.