Async actions: capture() and when()

[ogorzalka]

Phase 2, step A (design doc, "Capturing values at trigger time").

capture()

Action::add('save_post_event', SyncEventToCrm::class)
    ->async()
    ->capture(fn (int $postId, WP_Post $post) => ['status' => $post->post_status]);
// at execution: $context->get('status')

• The callback runs at trigger time, in the original request, with the hook arguments. It must return an array; anything else throws UnexpectedValueException.
• Values are normalized like arguments, and an error names the value (Captured value 'request' cannot be carried…). An object travels by reference and is reloaded at execution; to keep its trigger-time state, capture a scalar (tested).
• A handler class's public capture() method is used automatically when capture() is not called (design doc). capture() on the registration wins over it.
• A capture that throws follows the queuing-failure rule: debug mode throws; production reports and runs the handler in place.

when()

• Queues only when the callback, given the hook arguments, returns true (strictly: a truthy value does not count).
• It runs before the capture.
• It sits outside the fallback: an exception it throws goes through even in production, as it would synchronously, rather than running the handler while ignoring the condition.

Also

• ArgumentNormalizer::normalize() takes the kind of value, for error messages.
• RecordingDriver test fixture, shared by the async tests.

Tests

164 passed, 12 new. PHPStan level 5 and Pint pass.