RecipeApplyRequested

RecipeApplyRequested fires when a recipe should be applied to the current installation. Recipes are fully resolved JSON configurations that describe programs, program groups, and distributors. This event is the mechanism that turns a recipe payload into actual records in the database, and it is mutable: handlers record what they create so the caller can report the results.

The event ID is recipe_apply_requested, and its fully qualified class is Siren\Recipes\Core\Events\RecipeApplyRequested.

What does this event carry?

The event carries a RecipePayload model, which contains the deserialized recipe data describing the programs, program groups, and distributors that should be created.

use Siren\Recipes\Core\Events\RecipeApplyRequested;

public function handle(Event $event): void
{
    $payload = $event->getRecipePayload();

    // The payload contains the full recipe configuration:
    // programs, program groups, and distributors to create
}

Why is this event mutable?

Unlike most events in Siren, RecipeApplyRequested is designed for handlers to write back to it. As each handler processes its portion of the recipe, it records what it created using the event’s mutation methods: addCreatedProgram, addCreatedProgramGroup, and addCreatedDistributor. After all handlers have run, the caller can inspect the event to see exactly what was created, enabling confirmation messages and error reporting.

public function handle(Event $event): void
{
    // After creating a program from the recipe payload...
    $event->addCreatedProgram($program);

    // After creating a program group...
    $event->addCreatedProgramGroup($programGroup);

    // After creating a distributor...
    $event->addCreatedDistributor($distributor);
}

This pattern keeps recipe application decoupled. Each domain handles its own portion of the recipe independently, and the event itself serves as the coordination point that tracks the aggregate result.

For the full lifecycle of system events and how they connect to the rest of Siren’s architecture, see the System Events overview.