Add methods to register fallback handlers

[roxblnfk]

What was changed

Added methods to define dynamic handlers for Signals, Updates, and Queries.

• Workflow::registerDynamicQuery($handler)
• Workflow::registerDynamicSignal($handler)
• Workflow::registerDynamicUpdate($handler, $validator)

Checklist

1. Closes [Feature Request] Add fallback Update/Signal/Query listeners #508
2. How was this tested: added tests
3. Todo:
   • check that naming is OK
   • should we add the ability to unset the handlers?

Documentation

Dynamic Signal Handler

You can register a Signal handler that will be called if a handler for a specific Signal is not found.

If by the time the dynamic handler is registered, the Workflow has already received unhandled Signals, they will be processed immediately in the order they were received.

 \Temporal\Workflow::registerDynamicSignal(function (string $name, ValuesInterface $arguments): void {
     \error_log(\sprintf(
         'Executed signal `%s` with %d arguments',
         $name,
         $arguments->count(),
     ));
 });

Dynamic Query Handler

You can register a Query handler that will be called if a handler for a specific Query is not found.

\Temporal\Workflow::registerDynamicQuery(function (string $name, ValuesInterface $arguments): string {
    return \sprintf(
        'Got query `%s` with %d arguments',
        $name,
        $arguments->count(),
    );
});

Dynamic Update Handler

You can register an Update handler that will be called if a handler for a specific update is not found.
The registerDynamicUpdate() method accepts two arguments:

• Update handler.
• Update validator (optional) that should throw an exception if the validation fails.

\Temporal\Workflow::registerDynamicUpdate(
    static fn(string $name, ValuesInterface $arguments): string => \sprintf(
        'Got update `%s` with %d arguments',
        $name,
        $arguments->count(),
    ),
    static fn(string $name, ValuesInterface $arguments) => \str_starts_with(
        $name,
        'update_',
    ) or throw new \InvalidArgumentException('Invalid update name'),
);

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
php	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Apr 1, 2025 7:31pm

[Sushisource]

This all looks good to me but we tend to call these "dynamic" handlers in the other SDKs (though, I agree fallback probably makes more sense).

I think we probably should name them that just to be consistent.

As far as unsetting goes - yeah, I think that's reasonable to have.

[roxblnfk]

@Sushisource we already have methods like registerSignal(name, handler), registerQuery(name, handler), and registerUpdate(name, handler) in this SDK.
As you can see, they don't have the dynamic suffix in the name, even though they work at runtime, and there's no option to unregister handlers.
That's why the questions arise.

[Sushisource]

@Sushisource we already have methods like registerSignal(name, handler), registerQuery(name, handler), and registerUpdate(name, handler) in this SDK. As you can see, they don't have the dynamic suffix in the name, even though they work at runtime, and there's no option to unregister handlers. That's why the questions arise.

Right, in this case we would not take the name parameter, but would have the "dynamic" suffix.

As for un-registering, after looking again other SDKs don't have it so we probably don't need that.