website·Indexed 33 days ago
https://verbs.thunk.devA PHP framework for event sourcing that replaces traditional jargon with a simplified model of Events and States. It features 64-bit Snowflake IDs, automated state mutation, and specialized attributes like #[StateId] and #[AppliesToState] to link events to their respective states.
config/verbs.php.When a Verbs event is fired for the first time, it progresses through three major phases:
apply) -> Model modification (handle).Event Sourcing is a pattern where every change (event) that leads to the current state of an application is stored, rather than storing only the final state. This approach provides a granular history of how the system arrived at its current state and allows for state reconstruction or analysis at any point in time.
Key advantages include:
config/verbs.php configuration file if complex data structures are required. The default serializer context can also be modified in the same configuration file.The Monopoly example demonstrates how to manage a complex set of rules and multiple interacting states using Verbs. It utilizes two primary state types:
GameState: A singleton state per game that tracks the overall status, including the active player, the current state of the board, and the bank.PlayerState: An instance-per-player state used to track individual player data, such as current balance and the assigned token.Verbs::unlessReplaying() check. This replaces the formal 'Reactor' concept found in other event sourcing systems.Verbs::unlessReplaying(function () {
// Code for one-time side effects (e.g., sending an email)
});During the Firing phase, you can control whether an event is allowed to proceed using the constructor, authorization, and validation hooks.
__construct(): Used to gather all data needed for the event lifecycle. It is only called once during the initial fire and is skipped during replay.authorize: Ensures the current user is permitted to fire the event (behaves like Laravel form request authorization).validate hooks: Any method starting with validate is treated as a validation method. These run for each state the event is firing on based on the type-hinted state object.class UserJoinedTeam
{
public function validateUser(UserState $user)
{
$this->assert($user->can_join_teams, 'This user must upgrade before joining a team.');
}
public function validateTeam(TeamState $team)
{
$this->assert($team->seats_available > 0, 'This team does not have any more seats available.');
}
}GlobalReportGenerated event demonstrates how to use the #[AppliesToState] attribute to bind an event to a specific state class (GlobalReportState) and the #[Once] attribute to ensure the handler runs only once. In this example, the event extracts subscription metrics from the state, persists them into a Report model, and then triggers a ResetGlobalReportState event to clear the state for the next reporting period.namespace Thunk\Verbs\Examples\Subscriptions\Events;
use Thunk\Verbs\Attributes\Autodiscovery\AppliesToState;
use Thunk\Verbs\Attributes\Hooks\Once;
use Thunk\Verbs\Event;
use Thunk\Verbs\Examples\Subscriptions\Models\Report;
use Thunk\Verbs\Examples\Subscriptions\States\GlobalReportState;
#[AppliesToState(GlobalReportState::class)]
class GlobalReportGenerated extends Event
{
#[Once]
public function handle()
{
$state = $this->state(GlobalReportState::class);
Report::create([
'plan_id' => null,
'subscribes_since_last_report' => $state->subscribes_since_last_report,
'unsubscribes_since_last_report' => $state->unsubscribes_since_last_report,
'total_subscriptions' => $state->total_subscriptions,
'summary' => $state->summary(),
]);
ResetGlobalReportState::fire();
}
}Events are executed using the fire() method. When an event is fired, it is added to an in-memory queue and eventually 'committed' to the database in a single insert.
Verbs::commit() is called automatically at the end of requests, console commands, and queued jobs. However, you may need to call it manually in tests or within database transactions to ensure events are included in the transaction.
If you need to fire an event and immediately access the return value of its handle() method, use Event::commit() instead of fire().
// Standard fire (queued for commit)
PlayerAddedToGame::fire(game_id: $this->id, player_id: $player->id);
// Manual commit in transaction
DB::transaction(function() {
CustomerRegistered::fire(...);
Verbs::commit();
});
// Fire and commit immediately to get result
$subscription = CustomerBeganTrial::commit(customer_id: Auth::id());ResetPlanReportState event demonstrates how to reset reporting metrics for a specific plan. It loads the PlanReportState associated with a given plan_id and resets the subscription/unsubscription counters to zero while updating the last_reported_at timestamp to the current time.namespace Thunk\Verbs\Examples\Subscriptions\Events;
use Thunk\Verbs\Event;
use Thunk\Verbs\Examples\Subscriptions\States\PlanReportState;
use Thunk\Verbs\Support\StateCollection;
class ResetPlanReportState extends Event
{
public int $plan_id;
public function states(): StateCollection
{
return new StateCollection([
PlanReportState::class => PlanReportState::load($this->plan_id),
]);
}
public function apply(PlanReportState $state)
{
$state->subscribes_since_last_report = 0;
$state->unsubscribes_since_last_report = 0;
$state->last_reported_at = now();
}
}