Issue #3605789: Add an InstanceStarted event for atomic start-time wiring

Adds a typed InstanceStartedEvent the engine dispatches inside the start transaction, after the instance is saved (so it has its id) and its variables are seeded, but before the start token is placed and the workflow runs.

Why

An integrator that creates an external entity alongside a process (a booking, an order, a transaction) often needs to link the two and have the link committed atomically with the start. This event is the extension point for that: a subscriber wires the external entity to the instance using the now-known instance id, atomically with the start (a subscriber that throws rolls the whole start back), with the link already in place if the run is synchronous.

It is the idiomatic, decoupled alternative to passing a callback into start(): subscribers depend only on the event, not on the engine signature. A plain entity insert hook is not enough, because it fires before the variables are seeded, so a subscriber could not yet tell which entity the run is for. The matching reverse link is the instance id (the integer primary key), which an external table holds as a foreign key for a Views relationship.

What is included

  • src/Event/InstanceStartedEvent.php carrying the saved instance and the seeded variables.
  • The engine dispatches it in start() after variable seeding, before the start token (the event dispatcher is injected into the engine).
  • A kernel test: the event carries the saved instance and the seeded variables, fires before any token exists, and a throwing subscriber rolls the start back.
  • An "Events" section in the extending guide.

phpcs (Drupal, DrupalPractice) and cspell are clean; the engine test suites pass locally.

Merge request reports

Loading