Verbs

https://github.com/hirethunk/verbs
Admin
Verbs is an event sourcing package for PHP that simplifies event sourcing by removing boilerplate...
Tokens:63,591
Snippets:449
Trust Score:5.1
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Configure afterCreating callback

Source: https://github.com/hirethunk/verbs/blob/main/docs/testing.md

The configure() method allows setting afterMaking and afterCreating callbacks. This example fires an ExampleEvent after creating the state.

```php
public function configure(): void
{
    $this->afterCreating(function (ExampleState $state) {
        ExampleEvent::fire(
            id: $state->id,
        );
    });
}
```

--------------------------------

### CustomerState with trial_started_at

Source: https://github.com/hirethunk/verbs/blob/main/docs/quickstart.md

Customize the generated state to add a nullable Carbon property for the trial start timestamp.

```php
class CustomerState extends State
{
	public Carbon|null $trial_started_at = null;
}
```

--------------------------------

### handle() method example

Source: https://github.com/hirethunk/verbs/blob/main/docs/events.md

Use the handle() method to update your database/models/UI data. States type-hinted as parameters are automatically injected. This example updates a subscription's renewal dates.

```php
class CustomerRenewedSubscription extends Event
{
    #[StateId(CustomerState::class)]
    public int $customer_id;

    public function handle(CustomerState $customer)
    {
        Subscription::find($customer->active_subscription_id)
            ->update([
                'renewed_at' => now(),
                'expires_at' => now()->addYear(),
            ]);
    }
}
```

--------------------------------

### Define default property values with definition()

Source: https://github.com/hirethunk/verbs/blob/main/docs/testing.md

The definition() method returns an array of default property values used when create() is called. This example sets 'example_count' to 4.

```php
public function definition(): array
{
    return [
        'example_count' => 4,
    ];
}
```

--------------------------------

### Install Verbs via Composer

Source: https://github.com/hirethunk/verbs/blob/main/docs/quickstart.md

Use Composer to install the Verbs package. Run this in your project root after ensuring Laravel 10+ and PHP 8.1+ are installed.

```shell
composer require hirethunk/verbs
```

--------------------------------

### CustomerBeganTrial with validate and apply

Source: https://github.com/hirethunk/verbs/blob/main/docs/quickstart.md

Complete event with validate() and apply() methods. validate() checks the state to prevent duplicate trials; apply() sets the trial start timestamp.

```php
class CustomerBeganTrial extends Event
{
    #[StateId(CustomerState::class)]
    public int $customer_id;

    public function validate(CustomerState $state)
	{
        $this->assert(
            $state->trial_started_at === null
            || $state->trial_started_at->diffInDays() > 365,
            'This user has started a trial within the last year.'
        );
    }

    public function apply(CustomerState $state)
    {
        $state->trial_started_at = now();
    }
}
```

--------------------------------

### Set up parent and child states for nested access

Source: https://github.com/hirethunk/verbs/blob/main/docs/attributes.md

Set up a parent state with a child_id property by firing a ChildAddedToParent event. The event uses AppliesToState to link to both ParentState and ChildState, and the ParentState and ChildState classes are defined for the nested state example.

```php
ChildAddedToParent::fire(parent_id: 1, child_id: 2);

// ChildAddedToParent.php
#[AppliesToState(state_type: ParentState::class, id: 'parent_id')]
#[AppliesToState(state_type: ChildState::class, id: 'child_id')]
class ChildAddedToParent extends Event
{
    public int $parent_id;

    public int $child_id;

    public function applyToParentState(ParentState $state)
    {
        $state->child_id = $this->child_id;
    }
}
```

```php
class ParentState extends State
{
    public int $child_id;
}
```

```php
class ChildState extends State
{
    public int $count = 0;
}
```

--------------------------------

### Get a state by key or alias with get()

Source: https://github.com/hirethunk/verbs/blob/main/docs/states.md

Retrieves a state by key or alias. Like Laravel's get() collection method but preserves aliases. Returns a state.

```php
$collection->get(0); // returns the first state in the collection
$collection->get('foo'); // returns the state with the alias
```

--------------------------------

### Use Event::commit() to fire and immediately access results

Source: https://github.com/hirethunk/verbs/blob/main/docs/events.md

Shows an event's handle() returning a Subscription, and a controller using Event::commit() to get that result directly.

```php
// CustomerBeganTrial event
public function handle()
{
    return Subscription::create([
        'customer_id' => $this->customer_id,
        'expires_at' => now()->addDays(30),
    ]);
}

// TrialController
{
    public function store(TrialRequest $request) {
        $subscription = CustomerBeganTrial::commit(customer_id: Auth::id());
        return to_route('subscriptions.show', $subscription);
    }
}
```

--------------------------------

### Get first state of a type with firstOfType()

Source: https://github.com/hirethunk/verbs/blob/main/docs/states.md

Returns the first state item with the given type.

```php
$collection->firstOfType(FooState::class);
```

--------------------------------

### Apply methods for an event firing on two states

Source: https://github.com/hirethunk/verbs/blob/main/docs/event-lifecycle.md

Example of an event with two apply methods, one for each state it fires on. The apply hook updates the state for the given event. These methods are called immediately after the event is fired and also when state is rebuilt from existing events.

```php
class UserJoinedTeam
{
    // ...
    
    public function applyToUser(UserState $user)
    {
        $user->team_id = $this->team_id;
    }
    
    public function applyToTeam(TeamState $team)
    {
        $team->team_seats--;
    }
}
```

--------------------------------

### fired() hook example

Source: https://github.com/hirethunk/verbs/blob/main/docs/events.md

Use the fired() hook to trigger subsequent events. It executes in memory after the event fires but before it's stored in the database, allowing state changes to be applied before the next event. This example fires CountIncremented twice, resulting in a count of 2.

```php
CountIncrementedTwice::fire(count_id: $id);

// CountIncrementedTwice event
public function fired()
{
    CountIncremented::fire(count_id: $this->count_id);
    CountIncremented::fire(count_id: $this->count_id);
}

// CountIncremented event
public function apply(CountState $state)
{
    $state->count++;
}

// test or other file
CountState::load($id)->count; // 2
```

--------------------------------

### StateCollection Methods

Source: https://github.com/hirethunk/verbs/blob/main/docs/states.md

Documentation for the StateCollection class methods in the Verbs library, including alias, get, ofType, firstOfType, withId, and filter.

```APIDOC
## State Collections

Your events may sometimes need to affect multiple states.

Verbs supports State Collections out of the box, with several convenience methods:

```php
$event_with_single_state->state(); // State
$event_with_multiple_states->states(); // StateCollection
```

### `alias(?string $alias, State $state)`

Allows you to set a shorthand name for any of your states.

```php
$collection->alias('foo', $state_1);
```

You can also set state aliases by setting them in the optional params of some of
our [attributes](/docs/technical/attributes): any `#[AppliesTo]` attribute, and `#[StateId]`.

### `get($key, $default = null)`

Like the `get()` [collection method](https://laravel.com/docs/11.x/collections#method-get), but also preserves any
aliases. Returns a state.

```php
$collection->get(0); // returns the first state in the collection
$collection->get('foo'); // returns the state with the alias
```

### `ofType(string $state_type)`

Returns a state collection with only the state items of the given type.

```php
$collection->ofType(FooState::class);
```

### `firstOfType()`

Returns the `first()` state item with the given type.

```php
$collection->firstOfType(FooState::class);
```

### `withId(Id $id)`

(`Id` is a stand-in for `Bits|UuidInterface|AbstractUid|int|string`)

Returns the collection with only the state items with the given id.

```php
$collection->withId(1);
```

### `filter(?callable $callback = null)`

Like the `filter()` collection method, but also preserves any aliases. Returns a state collection.

```php
$activeStates = $stateCollection->filter(function ($state) {
    return $state->isActive;
});
```
```

--------------------------------

### fired() hook with state update example

Source: https://github.com/hirethunk/verbs/blob/main/docs/events.md

Illustrates using the fired() hook to trigger a subsequent event that uses the updated state. When a player levels up to level 5, the reward event sets max_inventory to 100.

```php
PlayerLeveledUp::fire(player_id: $id);

// PlayerLeveledUp event
public function apply(PlayerState $state)
{
    $state->level++;
}

public function fired()
{
    PlayerRewarded::fire(player_id: $this->player_id);
}

// PlayerRewarded event
public function apply(PlayerState $state)
{
    if ($state->level === 5) {
        $state->max_inventory = 100;
    }
}

// test or other file
PlayerState::load($id)->max_inventory; // 100;
```

--------------------------------

### Specify state ids with #[AppliesToState] id parameter

Source: https://github.com/hirethunk/verbs/blob/main/docs/attributes.md

Use the AppliesToState attribute with explicit id parameters to specify which property belongs to which state. Without the id parameter, Verbs automatically finds the id based on the state's prefix (e.g., ExampleState would be example, meaning example_id or example_ids).

```php
#[AppliesToState(state_type: GameState::class, id: foo_id)]
#[AppliesToState(state_type: PlayerState::class, id: bar_id)]
class RolledDice extends Event
{
    use PlayerAction;

    public function __construct(
        public int $foo_id,
        public int $bar_id,
        public array $dice,
    )
}
```

--------------------------------

### Validation methods for an event firing on two states

Source: https://github.com/hirethunk/verbs/blob/main/docs/event-lifecycle.md

Example of an event with two validation methods, one for each state it fires on. The validate hook ensures the event can be fired given the current states. The methods use the assert method to check conditions and provide error messages.

```php
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.');
    }
}
```

--------------------------------

### Use custom factory to create state

Source: https://github.com/hirethunk/verbs/blob/main/docs/testing.md

Shows how to use the custom factory: ExampleState::factory()->confirmed()->create() will create a state with 'confirmed' set to true.

```php
ExampleState::factory()->confirmed()->create(); // ->confirmed will be true
```

--------------------------------

### Link custom factory to ExampleState

Source: https://github.com/hirethunk/verbs/blob/main/docs/testing.md

Adds a newFactory() method to ExampleState that returns an instance of ExampleStateFactory. This method is required to use the custom factory.

```php
public bool $confirmed = false;

public int $example_count = 0;

public static function newFactory(): ExampleStateFactory
{
    return ExampleStateFactory::new(static::class);
}
```

--------------------------------

### Run Verbs migrations for v0.5.1

Source: https://github.com/hirethunk/verbs/blob/main/docs/upgrading.md

Run these commands to publish and run the migrations that update the verbs_snapshots table for v0.5.1. After migrating, a backup table named __verbs_snapshots_pre_050 is created.

```bash
php artisan vendor:publish --tag=verbs-migrations
php artisan migrate
```

--------------------------------

### Create ExampleStateFactory class

Source: https://github.com/hirethunk/verbs/blob/main/docs/testing.md

Defines a custom state factory extending Thunk\Verbs\StateFactory. The confirmed() method sets the 'confirmed' state to true.

```php
namespace App\States\Factories;

use Thunk\Verbs\StateFactory;

class ExampleStateFactory extends StateFactory
{
    public function confirmed(): static
    {
        return $this->state(['confirmed' => true]);
    }
}
```

--------------------------------

### StateFactory create() method

Source: https://github.com/hirethunk/verbs/blob/main/docs/testing.md

Create a state with explicit data, returning a State or StateCollection.

```php
UserState::factory()->create([ /* state data */ ]);
```

--------------------------------

### State::factory() with create() and id()

Source: https://github.com/hirethunk/verbs/blob/main/docs/testing.md

Create a state directly with data and an ID. If an ID is passed to both id() and create(), create() takes precedence.

```php
BankAccountState::factory()->create(
    data: ['balance' => 1337]
    id: $bank_account_id
);

// Or, using `id()` syntax:

BankAccountState::factory()
    ->id($bank_account_id)
    ->create(
        data: ['balance' => 1337]
    );
```

--------------------------------

### StateFactory count() method

Source: https://github.com/hirethunk/verbs/blob/main/docs/testing.md

Create multiple states at once, returning a StateCollection.

```php
UserState::factory()->count(3)->create();
```

--------------------------------

### Load a Singleton State with singleton()

Source: https://github.com/hirethunk/verbs/blob/main/docs/states.md

Loads a singleton state using the singleton() method. Trying to load a singleton state in any other way results in a BadMethodCall exception.

```php
YourState::singleton();
```

--------------------------------

### Generate CustomerState via Artisan

Source: https://github.com/hirethunk/verbs/blob/main/docs/quickstart.md

Use the built-in artisan command to create a CustomerState class in app/States.

```shell
php artisan verbs:state CustomerState
```

--------------------------------

### Multiple Apply Methods for Different States

Source: https://github.com/hirethunk/verbs/blob/main/docs/states.md

Demonstrates writing separate, descriptive apply methods to update multiple states in one event. Verbs will find and call all relevant state and event methods prefixed with 'apply' on fire().

```php
public function applyToGameState(GameState $state) {}

public function applyToPlayerState(PlayerState $state) {}
```

--------------------------------

### State::factory() for singleton states

Source: https://github.com/hirethunk/verbs/blob/main/docs/testing.md

Create a singleton state without an ID.

```php
ChurnState::factory()->create(['churn' => 40]);
```

--------------------------------

### Fire event with named parameters and state attributes

Source: https://github.com/hirethunk/verbs/blob/main/docs/events.md

Shows how to fire an event with named parameters that correspond to its properties, and how to define those properties with #[StateId] attributes.

```php
// Game model
PlayerAddedToGame::fire(
    game_id: $this->id,
    player_id: $player->id,
);

// PlayerAddedToGame event
#[StateId(GameState::class)]
public string $game_id;

#[StateId(PlayerState::class)]
public string $player_id;
```

--------------------------------

### Replay events with artisan verbs:replay

Source: https://github.com/hirethunk/verbs/blob/main/docs/events.md

Use this artisan command to replay all recorded events in chronological order. Verbs will prompt for confirmation before executing, and will ask again if running in production.

```shell
php artisan verbs:replay
```

--------------------------------

### PlayerTransaction event with apply() and handle()

Source: https://github.com/hirethunk/verbs/blob/main/docs/state-first-development.md

Shows the event lifecycle order: apply() updates the state before handle() updates the model. Use this pattern to keep business logic in states and reduce database queries.

```php
public function apply(PlayerState $state)
{
    $state->wealth += $this->amount;
}

public function handle()
{
    // our apply method has already happened!

    Player::fromId($this->player_id)
        ->update([
            'wealth' => $this->state(PlayerState::class)->wealth,
        ]);
}
```

--------------------------------

### Custom StateFactory with initial_event

Source: https://github.com/hirethunk/verbs/blob/main/docs/testing.md

Override the initial event fired by the StateFactory by setting the $initial_event property. Ensure your replacement event implements CommitsImmediately.

```php
class ExampleStateFactory extends StateFactory
{
    protected string $initial_event = ExampleCreated::class;
}
```

--------------------------------

### Access State and StateCollection from an event

Source: https://github.com/hirethunk/verbs/blob/main/docs/states.md

Shows how to access a single state or a StateCollection from an event. The single-state accessor returns a State instance, while the multi-state accessor returns a StateCollection.

```php
$event_with_single_state->state(); // State
$event_with_multiple_states->states(); // StateCollection
```

--------------------------------

### StateFactory state() method

Source: https://github.com/hirethunk/verbs/blob/main/docs/testing.md

Set default data that will be overridden by create(). Useful for custom factories.

```php
UserState::factory()->state([ /* state data */ ])->create();
```

--------------------------------

### Use Bits migration helpers for snowflake columns

Source: https://github.com/hirethunk/verbs/blob/main/docs/ids.md

Use Bits migration helpers: snowflakeId() creates a primary key column named 'id', and snowflake() adds a regular snowflake column ideal for foreign keys.

```php
/**
 * Run the migrations.
 */
public function up(): void
{
    Schema::create('job_applications', function (Blueprint $table) {
        $table->snowflakeId();
        $table->snowflake('user_id')->index();
        $table->foreign('user_id')->references('id')->on('users');
        // ...
    });
}
```

--------------------------------

### Pair state to model with #[StateId]

Source: https://github.com/hirethunk/verbs/blob/main/docs/states.md

Shows a state class with a #[StateId] attribute linking the event to a model instance. The handle method creates a model using the state's id as the snowflake value.

```php
class FooCreated
{
    #[StateId(FooState::class)]
    public int $foo_id;

    // etc

    public function handle()
    {
        Foo::create(
            snowflake: $this->foo_id
        );
    }
}
```

--------------------------------

### Update Subscription Model in handle Method

Source: https://github.com/hirethunk/verbs/blob/main/docs/quickstart.md

Add a handle() method to the event to create a Subscription record when the event is committed. Assumes a Subscription model with customer_id and expires_at columns.

```php
// after apply()

public function handle()
{
    Subscription::create([
        'customer_id' => $this->customer_id,
        'expires_at' => now()->addDays(30),
    ]);
}
```

--------------------------------

### Toggle metadata per event

Source: https://github.com/hirethunk/verbs/blob/main/docs/metadata.md

Shows how to opt out of metadata for a specific event by setting a flag, then resetting it for the next user. Note the variable name mismatch ($user_preferences vs $userPreferences) in the original.

```php
public function sendPromotionalNotification($user)
{
    $user_preferences = $this->getUserPreferences($user->id);

    Verbs::createMetadataUsing(fn (Metadata $metadata) => [
        'suppress_notifications' => !$userPreferences->acceptsPromotionalNotifications,
    ]);

    PromotionalEvent::fire(details: $user->location->promoDetails());

    // resets Metadata bool for the next user
    Verbs::createMetadataUsing(fn (Metadata $metadata) => ['suppress_notifications' => false]);
}
```

--------------------------------

### Create metadata with closure

Source: https://github.com/hirethunk/verbs/blob/main/docs/metadata.md

Use in a ServiceProvider or Middleware to automatically include metadata on every event. Can be called multiple times, useful for third-party packages.

```php
Verbs::createMetadataUsing(function (Metadata $metadata, Event $event) {
  $metadata->team_id = current_team_id();
});
```

--------------------------------

### New event class template

Source: https://github.com/hirethunk/verbs/blob/main/docs/events.md

A brand-new event file generated by the artisan command, containing a handle() method where you define what happens when the event fires.

```php
class MyEvent extends Event
{
    public function handle()
    {
        // what you want to happen
    }
}
```

--------------------------------

### Link event class to states with #[AppliesToState]

Source: https://github.com/hirethunk/verbs/blob/main/docs/attributes.md

Use the AppliesToState attribute above an event class to link it to multiple states. It has the same parameters as StateId, with an additional optional id parameter to specify which property belongs to which state.

```php
#[AppliesToState(GameState::class)]
#[AppliesToState(PlayerState::class)]
class RolledDice extends Event
{
    use PlayerAction;

    public function __construct(
        public int $game_id,
        public int $player_id,
        public array $dice,
    )
}
```

--------------------------------

### New State Class File

Source: https://github.com/hirethunk/verbs/blob/main/docs/states.md

A brand new state file generated by the verbs:state command. It extends the Thunk\Verbs\State base class and is placed in the app/States directory.

```php
namespace App\States;

use Thunk\Verbs\State;

class ExampleState extends State
{
    // It ain't my birthday but I got my name on the cake - Lil Wayne
}
```

--------------------------------

### Filter states with a callback using filter()

Source: https://github.com/hirethunk/verbs/blob/main/docs/states.md

Filters the collection with a callback, preserving aliases. Returns a state collection.

```php
$activeStates = $stateCollection->filter(function ($state) {
    return $state->isActive;
});
```

--------------------------------

### Create metadata with array return

Source: https://github.com/hirethunk/verbs/blob/main/docs/metadata.md

Alternative to the closure form: return an array (or Collection) and Verbs merges it into the metadata. Useful when accompanying data is about the event rather than a parameter.

```php
Verbs::createMetadataUsing(fn () => ['team_id' => current_team_id()]);
```

--------------------------------

### Define a Singleton State

Source: https://github.com/hirethunk/verbs/blob/main/docs/states.md

Defines a singleton state by extending SingletonState instead of State. Singleton states require no ID because only one copy exists across the entire app.

```php
class CountState extends SingletonState {}
```

--------------------------------

### Generate CustomerBeganTrial Event

Source: https://github.com/hirethunk/verbs/blob/main/docs/quickstart.md

Use the built-in artisan command to generate an event class. This creates an event in app/Events with a handle() method.

```shell
php artisan verbs:event CustomerBeganTrial
```

--------------------------------

### Check metadata flag in event handler

Source: https://github.com/hirethunk/verbs/blob/main/docs/metadata.md

Handles the promotional event by checking the 'suppress_notifications' metadata flag (default false) and skipping notification if true.

```php
public function handlePromotionalEvent(PromotionalEvent $event)
{
    if ($event->metadata('suppress_notifications', false)) {
        return;
    }

    $this->sendNotification($event->details);
}
```

--------------------------------

### Generate a State with verbs:state

Source: https://github.com/hirethunk/verbs/blob/main/docs/states.md

Generates a new state class file in the app/States directory using the built-in artisan command.

```shell
php artisan verbs:state ExampleState
```

--------------------------------

### Fire CustomerBeganTrial Event

Source: https://github.com/hirethunk/verbs/blob/main/docs/quickstart.md

Fire the event anywhere in your code using the static fire method. Pass the customer_id as a named argument.

```php
CustomerBeganTrial::fire(customer_id: 1);
```

--------------------------------

### Prevent one-time effects during replay with Verbs::unlessReplaying()

Source: https://github.com/hirethunk/verbs/blob/main/docs/events.md

Wrap one-time effects (like sending a welcome email) in this callback to prevent them from triggering during a replay. Alternatively, use the #[Once] attribute.

```php
Verbs::unlessReplaying(function () {
    // one-time effect
});
```

--------------------------------

### Prevent replay with #[Once]

Source: https://github.com/hirethunk/verbs/blob/main/docs/attributes.md

Use the Once attribute above any handle() method that you do not want replayed. You may also use Verbs::unlessReplaying for one-time effects.

```php
class YourEvent extends Event
{
    #[Once(YourState::class)]
    public function handle()
    {
        //
    }
}
```

--------------------------------

### Applying Event Data to a State

Source: https://github.com/hirethunk/verbs/blob/main/docs/states.md

Shows how to apply event data to a state using the apply() hook. The event increments the state's event_count property, and after firing and committing, the state reflects the updated value.

```php
// CountIncremented.php
class CountIncremented extends Event
{
    #[StateId(CountState::class)]
    public int $example_id;

    public function apply(CountState $state)
    {
        $state->event_count++;
    }
}

// CountState.php
class CountState extends State
{
    public $event_count = 0;
}

// test or other file
$id = snowflake_id();

CountIncremented::fire(example_id: $id);
Verbs::commit();
CountState::load($id)->event_count // = 1
```

--------------------------------

### Filter states by type with ofType()

Source: https://github.com/hirethunk/verbs/blob/main/docs/states.md

Filters the collection to only state items of the given type. Returns a state collection.

```php
$collection->ofType(FooState::class);
```

--------------------------------

### Load a State with CardState::load

Source: https://github.com/hirethunk/verbs/blob/main/docs/states.md

Loads a state by its ID. The state is loaded once and kept in memory, allowing real-time updates without additional database overhead.

```php
CardState::load($card_id);
```

--------------------------------

### Access nested state with #[AppliesToChildState]

Source: https://github.com/hirethunk/verbs/blob/main/docs/attributes.md

Use the AppliesToChildState attribute on an event class to allow Verbs to access a nested state. It takes a state_type (child state), parent_type, id (child state id), and an optional alias string. Remember to also use StateId or AppliesToState to identify the parent_id.

```php
NestedStateAccessed::fire(parent_id: 1);

// NestedStateAccessed.php
#[AppliesToChildState(
    state_type: ChildState::class,
    parent_type: ParentState::class,
    id: 'child_id'
)]
class NestedStateAccessed extends Event
{
    #[StateId(ParentState::class)]
    public int $parent_id;

    public function apply(ChildState $state)
    {
        $state->count++; // 1
    }
}
```

--------------------------------

### CustomerBeganTrial with StateId Attribute

Source: https://github.com/hirethunk/verbs/blob/main/docs/quickstart.md

Add the #[StateId(CustomerState::class)] attribute above the $customer_id property to link the event to the state.

```php
class CustomerBeganTrial extends Event
{
    #[StateId(CustomerState::class)]
	public int $customer_id;
}
```

--------------------------------

### Pest Testing Patterns with Verbs

Source: https://github.com/hirethunk/verbs/blob/main/CLAUDE.md

Testing patterns for Pest PHP: use Verbs::fake() to prevent database writes, Verbs::commitImmediately() for integration tests, and factories to create test states.

```php
// Use Verbs::fake() to prevent database writes during tests
Verbs::fake();

// Use Verbs::commitImmediately() for integration tests
Verbs::commitImmediately();

// Create test states using factories
CustomerState::factory()->id($id)->create();
```

--------------------------------

### Automatically generate snowflake ids with autofill

Source: https://github.com/hirethunk/verbs/blob/main/docs/ids.md

Set the event's state_id property to null and fire without an id to let Verbs' autofill default provide a snowflake_id(). The second block shows the resulting event's customer_id equals the generated snowflake.

```php
class CustomerBeganTrial extends Event
{
    #[StateId(CustomerState::class)]
    public ?int $customer_id = null;
}
```

```php
    $event = CustomerBeganTrial::fire() // no set customer_id

    $event->customer_id; // = snowflake_id()
```

--------------------------------

### StateFactory id() method

Source: https://github.com/hirethunk/verbs/blob/main/docs/testing.md

Set the state ID explicitly. Cannot be used with count().

```php
UserState::factory()->id(123)->create();
```

--------------------------------

### CustomerBeganTrial Event with customer_id

Source: https://github.com/hirethunk/verbs/blob/main/docs/quickstart.md

Replace the generated event with this class that has a public int $customer_id property. This is the initial version before adding state attributes.

```php
class CustomerBeganTrial extends Event
{
    public int $customer_id;
}
```

--------------------------------

### Set a state alias with alias()

Source: https://github.com/hirethunk/verbs/blob/main/docs/states.md

Sets a shorthand alias for a state in the collection. Aliases can also be set via the optional params of #[AppliesTo] and #[StateId] attributes.

```php
$collection->alias('foo', $state_1);
```

--------------------------------

### Route to a State with Route-Model Binding

Source: https://github.com/hirethunk/verbs/blob/main/docs/states.md

Uses Laravel's route-model binding to automatically load a state in a route. The state is injected into the closure based on the route parameter.

```php
Route::get('/users/{user_state}', function(UserState $user_state) {
  // $user_state is automatically loaded for you!
});
```

--------------------------------

### Link event to states with #[StateId]

Source: https://github.com/hirethunk/verbs/blob/main/docs/attributes.md

Use the StateId attribute on event properties to link the event to one or more states. Each attribute takes a state_type and optionally an alias string; by default it can automatically generate a snowflake_id for you.

```php
class YourEvent extends Event
{
    #[StateId(GameState::class)]
    public int $game_id;

    #[StateId(PlayerState::class)]
    public int $player_id;
}
```

--------------------------------

### Filter states by id with withId()

Source: https://github.com/hirethunk/verbs/blob/main/docs/states.md

Returns the collection with only the state items with the given id. The id can be a Bits, UuidInterface, AbstractUid, int, or string.

```php
$collection->withId(1);
```

--------------------------------

### Verbs assertion methods

Source: https://github.com/hirethunk/verbs/blob/main/docs/testing.md

Use these assertion methods after adding Verbs::fake() to isolate the test environment. They allow granular checking of committed events.

```php
Verbs::assertNothingCommitted();
Verbs::assertCommitted(...);
Verbs::assertNotCommitted(...);
```

--------------------------------

### Validating Event Data with validate() and assert()

Source: https://github.com/hirethunk/verbs/blob/main/docs/states.md

Uses the validate() hook with the built-in assert() method to prevent an event from firing if a state condition is not met. If the assertion fails, the event will not fire and the provided error message is displayed.

```php
public function validate()
{
    $this->assert(
        $game->started, // if this has not happened
        'Game must be started before a player can join.' // then display this error message
    )
}
```

--------------------------------

### Disable model normalization protection

Source: https://github.com/hirethunk/verbs/blob/main/docs/state-first-development.md

Disables the exception thrown when storing model references in events or states. Not recommended and may have unintended consequences.

```php
Thunk\Verbs\Support\Normalization\ModelNormalizer::dangerouslyAllowModelNormalization();
```

--------------------------------

### Commit events inside a database transaction

Source: https://github.com/hirethunk/verbs/blob/main/docs/events.md

Call Verbs::commit() before the transaction commits to include Verbs events in the transaction.

```php
DB::transaction(function() {
    // Some non-Verbs Eloquent calls
    
    CustomerRegistered::fire(...);
    CustomerBeganTrial::fire(...);
    
    // …some more non-Verbs Eloquent calls
    
    Verbs::commit();
});
```

--------------------------------

### Use HasSnowflakes trait and cast to Snowflake

Source: https://github.com/hirethunk/verbs/blob/main/docs/ids.md

Use the HasSnowflakes trait and cast an attribute to Snowflake to enable snowflake IDs on a model managed via events.

```php
use Glhd\Bits\Database\HasSnowflakes;
use Glhd\Bits\Snowflake;

class JobApplication extends Model
{
    use HasSnowflakes; // Add this to your model

    // Any attribute can be cast to a `Snowflake` (or `Sonyflake`)
    protected function casts(): array
    {
        return [
            'id' => Snowflake::class,
        ];
    }
}
```

--------------------------------

### Verbs::commitImmediately() in beforeEach

Source: https://github.com/hirethunk/verbs/blob/main/docs/testing.md

Call Verbs::commitImmediately() in a beforeEach hook to automatically commit all events fired during tests, avoiding manual commit calls.

```php
beforeEach(function () {
    Verbs::commitImmediately();
});
```
Tokens:
Raw