### Install Verbs Package

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

Installs the hirethunk/verbs package using Composer. Requires Laravel 10+ and PHP 8.1+.

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

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

### PlayerTransaction Event Handling

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

Example of how a PlayerTransaction event applies changes to the PlayerState and then updates the Player model.

```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,
        ]);
}
```

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

### Event Apply Example

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

Illustrates how to use the 'apply' hook to update state for an event. Apply methods are prefixed with 'apply' and are executed for each state the event is associated with, both during initial firing and during replays.

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

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

### Player Level Up and Reward Event Example

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

Illustrates a game scenario where a player leveling up triggers a reward event. The `apply` method increments the player's level, and the `fired` method triggers a `PlayerRewarded` event, which grants a reward based on the new level.

```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;
```

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

### CountIncremented Event Example

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

Demonstrates the `fired()` hook in the `CountIncrementedTwice` event, showing how one event can trigger another and how state is updated sequentially. The `apply` method increments a count, and the `fired` method triggers another event.

```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
```

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

### Event Validation Example

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

Demonstrates how to implement validation methods for an event based on different states. Validation methods are prefixed with 'validate' and are called for each state the event is firing on.

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

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

### State Collection Methods

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

Provides examples of common methods used with State Collections, including aliasing, retrieving states by index or alias, filtering by type, and filtering by ID.

```php
$collection->alias('foo', $state_1);
$collection->get(0); // returns the first state in the collection
$collection->get('foo'); // returns the state with the alias
$collection->ofType(FooState::class);
$collection->firstOfType(FooState::class);
$collection->withId(1);
$stateCollection->filter(function ($state) {
    return $state->isActive;
});
```

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

### Database Migrations with Snowflake IDs

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

Provides examples of using `glhd/bits` helper methods in Laravel migrations to create columns for Snowflake IDs. It shows how to create a primary key column (`snowflakeId()`) and regular columns (`snowflake()`) suitable 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');
        // ...
    });
}
```

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

### Publish and Run Migrations

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

Publishes Verbs migrations and runs them to set up the necessary database schema.

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

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

### Define CustomerState with Timestamp

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

Defines the CustomerState class, adding a trial_started_at property to track when a trial began. Requires the Carbon library.

```php
use Carbon\Carbon;

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

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

### Run Verbs Migrations

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

Commands to publish and run the database migrations for the hirethunk/verbs package. This is necessary to update the `verb_snapshots` table to the new schema introduced in v0.5.1.

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

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

### Implement Event Validation and Application Logic

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

Implements the validate() and apply() methods for the CustomerBeganTrial event. The validate() method prevents trials within the last year, and apply() sets the trial_started_at timestamp.

```php
use Carbon\Carbon;
use HireThunk\Verbs\Attributes\StateId;
use HireThunk\Verbs\Event;

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();
    }
}
```

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

### Loading Singleton State

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

Demonstrates how to load a singleton state using the `singleton()` method. Attempting to load a singleton state through other means will result in a `BadMethodCall` exception.

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

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

### Executing an Event Replay

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

Shows how to initiate an event replay using the Artisan command-line tool or programmatically within application files. This process rebuilds the application state by re-running all recorded events.

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

```php
Verbs::replay()
```

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

### Using Custom State Factory

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

Demonstrates how to use a custom state factory to create states with pre-defined configurations, such as setting a 'confirmed' property to true.

```php
ExampleState::factory()->confirmed()->create();
```

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

### State Factory Creation

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

Demonstrates creating states using the State::factory() method, similar to Eloquent factories. Allows bypassing manual state building and directly creating states with specified data and IDs.

```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]
    );

// Singleton state example:
ChurnState::factory()->create(['churn' => 40]);
```

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

### Generate CustomerState

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

Generates a new state class named CustomerState using the Verbs artisan command. The state is created in the app/States directory.

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

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

### Replay Events from Event Store

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

Demonstrates how to replay events from an event store. This function fetches events sequentially and applies them to a given aggregate. It's crucial for rebuilding state or debugging.

```python
from hirethunk.verbs.eventstore import EventStore
from hirethunk.verbs.aggregate import Aggregate

def replay_events(event_store: EventStore, aggregate_id: str) -> Aggregate:
    """Replays events for a given aggregate ID from the event store."""
    aggregate = Aggregate(aggregate_id)
    events = event_store.get_events(aggregate_id)
    for event in events:
        aggregate.apply_event(event)
    return aggregate

# Example Usage:
# event_store = EventStore()
# user_aggregate = replay_events(event_store, "user-123")
# print(f"Replayed state for user-123: {user_aggregate.state}")
```

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

### Multiple State Application Methods

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

Demonstrates how an event can apply changes to multiple states by defining separate `apply` methods for each state, or by loading multiple states within a single `apply` method.

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

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

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

### Using the handle() Method with State Injection

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

Demonstrates how to use the `handle()` method within an event to perform business logic, such as updating database records. It highlights the automatic injection of State objects when they are type-hinted as parameters.

```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(),
            ]);
    }
}
```

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

### Update Database with Eloquent Model

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

Adds a handle() method to the CustomerBeganTrial event to create a Subscription Eloquent model. This method is executed after the event is committed.

```php
use Carbon\Carbon;
use HireThunk\Verbs\Attributes\StateId;
use HireThunk\Verbs\Event;
use App\Models\Subscription; // Assuming Subscription model exists

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();
    }

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

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

### Firing Events with Named Parameters

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

Demonstrates how to fire an event using named parameters, ensuring that the parameters passed during firing match the properties defined in the event class.

```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;
```

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

### Configure Factory Callbacks

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

Configures the factory to run callbacks after creating model instances. It utilizes the `afterCreating` method to trigger an event with the created state's ID. This method is essential for defining post-creation logic.

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

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

### Applying Event Data to State

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

Illustrates how to update state properties using the `apply()` method within an event class. It shows how to reference the state, increment a counter, and then load and check the updated state.

```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
```

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

### Loading a State

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

Provides the method for retrieving a state instance by its ID. It also mentions `loadOrFail()` for handling cases where a state might not exist, potentially triggering a 404 response.

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

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

### Committing Events and Accessing Results

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

Shows how to use `Event::commit()` to both fire and commit an event, and importantly, how to retrieve the return value from the event's `handle()` method. This is useful when the event's result is needed immediately.

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

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

### Create Event Metadata

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

Defines a callback to automatically populate event metadata. This is useful for including data like team IDs or user preferences with every event. The callback receives a Metadata object and the Event object.

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

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

### State Factory Create Method

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

Creates a state with explicit data. It can return a single State object or a StateCollection if used with count().

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

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

### Generate a State

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

Demonstrates the artisan command to generate a new state file in the Verbs framework. It specifies the command and the expected output directory.

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

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

### Generate a Verbs Event

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

Generates a new event class using the Verbs artisan command. The event is created in the app/Events directory.

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

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

### Custom Serialization with Verbs

Source: https://github.com/hirethunk/verbs/blob/main/docs/state-hydration-snapshots.md

Details how to implement custom serialization for specific object types in Verbs by implementing the `SerializedByVerbs` interface and using the `NormalizeToPropertiesAndClassName` trait.

```PHP
interface SerializedByVerbs {}

trait NormalizeToPropertiesAndClassName {}
```

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

### Applying Events to Aggregate State

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

Illustrates the core logic of applying an event to an aggregate's state. This is a fundamental operation during event replay.

```python
from hirethunk.verbs.aggregate import Aggregate

class UserAggregate(Aggregate):
    def __init__(self, user_id):
        super().__init__(user_id)
        self.state = {"name": None, "email": None}

    def apply_user_created(self, event):
        self.state["name"] = event.data["name"]
        self.state["email"] = event.data["email"]

    def apply_email_changed(self, event):
        self.state["email"] = event.data["new_email"]

# Example Usage:
# user_agg = UserAggregate("user-456")
# user_created_event = {"type": "UserCreated", "data": {"name": "Alice", "email": "alice@example.com"}}
# user_agg.apply_event(user_created_event)
# print(user_agg.state) # Output: {'name': 'Alice', 'email': 'alice@example.com'}
```

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

### State Collection API

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

Documentation for the State Collection methods, detailing their functionality and parameters.

```APIDOC
StateCollection:
  alias(?string $alias, State $state)
    Sets a shorthand name for a state within the collection.
    Parameters:
      - alias: The shorthand name for the state.
      - state: The State object to alias.

  get($key, $default = null)
    Retrieves a state from the collection by its index or alias. Preserves aliases.
    Parameters:
      - key: The index or alias of the state to retrieve.
      - default: The default value to return if the state is not found.
    Returns: The State object or the default value.

  ofType(string $state_type)
    Filters the collection to return only states of the specified type.
    Parameters:
      - state_type: The class name of the state type to filter by.
    Returns: A new StateCollection containing only matching states.

  firstOfType(string $state_type)
    Returns the first state in the collection that matches the specified type.
    Parameters:
      - state_type: The class name of the state type to find.
    Returns: The first matching State object, or null if none found.

  withId(Id $id)
    Filters the collection to return only states with the specified ID.
    Parameters:
      - id: The ID of the state to filter by. Accepts various ID types (Bits, UuidInterface, AbstractUid, int, string).
    Returns: A new StateCollection containing only matching states.

  filter(?callable $callback = null)
    Filters the collection based on a callback function. Preserves aliases.
    Parameters:
      - callback: A callable function that returns true for states to keep.
    Returns: A new StateCollection containing the filtered states.
```

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

### Linking Custom Factory to State

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

Associates a custom state factory with a specific state class by implementing the newFactory() static method.

```php
public bool $confirmed = false;

public int $example_count = 0;

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

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

### Define CustomerBeganTrial Event

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

Defines the CustomerBeganTrial event class, including a customer_id property. This event is intended for use with Verbs.

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

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

### Verbs Serialization Configuration

Source: https://github.com/hirethunk/verbs/blob/main/docs/state-hydration-snapshots.md

Explains how Verbs uses the Symfony Serializer component for JSON serialization and how to configure custom normalizers in `config/verbs.php` for specific object types.

```PHP
You can add another type of object like this:
    - SerializeByVerbs interface
    - And a Trait called something like "SerializesToPropertyNamesAndValues"
        - I'll take all this and serialize to JSON
```

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

### Custom State Factory Definition

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

Defines a custom state factory by extending the base StateFactory class. Allows for custom methods to set specific states or configurations.

```php
namespace AppStatesFactories;

use ThunkVerbsStateFactory;

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

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

### State Factory State Method

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

Defines default data for a state. This data will be used if no specific data is provided during the create() call, and is particularly useful in custom factories.

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

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

### Fire CustomerBeganTrial Event

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

Fires the CustomerBeganTrial event with a specified customer ID. Assumes the event is properly defined.

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

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

### Custom Initial Event for State Factory

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

Allows customization of the initial event fired by the StateFactory. By default, it uses VerbsStateInitialized, but can be overridden by setting the $initial_event property on a custom StateFactory.

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

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

### Singleton State Structure

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

Demonstrates how to define a singleton state by extending the `SingletonState` class instead of the base `State` class. Singleton states do not require an ID as only one instance exists application-wide.

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

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

### Basic State Structure

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

Shows the fundamental structure of a Verbs state class, extending the base `State` class. It includes the namespace and a placeholder comment.

```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
}
```

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

### Verbs State Dehydration

Source: https://github.com/hirethunk/verbs/blob/main/docs/state-hydration-snapshots.md

Explains the dehydration process in Verbs, where `Verbs::commit()` serializes affected state values and writes them to the `VerbSnapshot` table in the database.

```APIDOC
State Dehydration:
  Verbs::commit()
    - Processes the event queue.
    - Serializes all affected state values.
    - Writes serialized data to the `VerbSnapshot` table in the database.
```

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

### State Factory Count Method

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

Creates a specified number of states and returns them as a StateCollection. This method is used to generate multiple state instances at once.

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

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

### Generate an Event

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

This snippet shows how to generate a new event using the Verbs artisan command. It also illustrates the basic structure of a generated event file.

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

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

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

### Create Event Metadata with Array Return

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

An alternative method to create event metadata by returning an array or Collection directly from the callback. Verbs will merge this data into the event's metadata. This is useful for event-specific data.

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

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

### Link Event to State with StateId Attribute

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

Links the CustomerBeganTrial event to the CustomerState using the #[StateId] attribute on the customer_id property. This allows the event to access and mutate the state.

```php
use HireThunk\Verbs\Attributes\StateId;

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

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

### Verbs Event Assertions

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

Provides methods to assert the state of committed Verbs events. Requires Verbs::fake() to be called first to set up a fake event store for isolated testing.

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

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

### Commit Immediately

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

Enables automatic committing of all fired events within tests. This is typically set in a test's beforeEach hook to ensure all events are committed without manual intervention.

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

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

### Routing to States

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

Explains how States implement Laravel's `UrlRoutable` interface, allowing them to be used directly in routes for automatic loading, similar to route-model binding.

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

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

### Verbs State Hydration

Source: https://github.com/hirethunk/verbs/blob/main/docs/state-hydration-snapshots.md

Describes the process of hydrating state in Verbs. If a snapshot exists, it's deserialized; otherwise, the state is reconstructed from events. Hydrated states are kept in memory for subsequent access.

```APIDOC
State Hydration:
  load()
    - If a snapshot exists, the state is hydrated by loading and deserializing the snapshot data.
    - If not, the system reconstructs the state by applying the relevant events stored in the event store.
    - Once hydrated, the state object is kept in memory within the application.
    - Subsequent access to this state does not require fetching the snapshot from the database again unless the state is deleted from memory or the application restarts.
```

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

### Allow Model Normalization

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

Disables the default behavior that prevents storing model references within events or states, intended for advanced use cases.

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

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

### Accessing States from Events

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

Shows how to retrieve a single state or a collection of states from an event object.

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

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

### AppliesToState Attribute for Class-Level State Linking

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

The `AppliesToState` attribute links an entire event class to one or more state types. It can be applied to the class itself and supports specifying the state property ID, or it can infer it based on state prefixes. It also accepts an optional alias.

```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,
    )
}
```

```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,
    )
}
```

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

### StateId Attribute Usage

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

Illustrates how to use the `#[StateId]` attribute to associate a state with a model, specifically within an event handler.

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

    // etc

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

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

### Define Factory State

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

Defines the default property values for a custom state factory when creating new instances. This method returns an array of key-value pairs that will be used to populate the model's attributes.

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