Brain

https://github.com/r2luna/brain
Admin
Brain is an elegant Laravel package that helps organize applications using Domain-Driven Design...
Tokens:70,458
Snippets:676
Trust Score:7.1
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install dev dependencies with composer install

Source: https://github.com/r2luna/brain/blob/main/CONTRIBUTING.md

Run this command after cloning your fork to install the development dependencies required for the project.

```bash
composer install
```

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

### Quick Example: Define and Run a Workflow

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Shows how to define a workflow with actions and run it, plus a query example. Requires PHP 8.3+ and Laravel 12.0+ or 13.0+.

```php
// Define a workflow with its actions
class CreateUser extends Workflow
{
    protected array $actions = [
        RegisterUser::class,
        SendWelcomeEmail::class,
        NotifyStaff::class,
    ];
}

// Run it
CreateUser::run([
    'name'  => 'John Doe',
    'email' => 'john@example.com',
]);

// Or use a query
$user = GetUserByEmail::run('john@example.com');
```

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

### Example Paths with Domains Enabled

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Shows the resulting file paths when BRAIN_USE_DOMAINS is enabled.

```text
app/Brain/Users/Workflows/CreateUser.php
app/Brain/Users/Actions/RegisterUser.php
app/Brain/Payments/Workflows/ChargeCustomer.php
```

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

### Install Brain via Composer

Source: https://github.com/r2luna/brain/blob/main/README.md

Install the Brain package using Composer. Run this command in your project root.

```bash
composer require r2luna/brain
```

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

### LogEventListener example (src/Actions/Listeners/LogEventListener.php)

Source: https://github.com/r2luna/brain/blob/main/_autodocs/api-reference/events.md

Example implementation of a LogEventListener that logs event details using Log::info. Includes runId, action, payload, workflow, timestamp, and meta fields.

```php
Log::info(
    "(id: {$event->runWorkflowId}) Action Event: {$class}",
    [
        'runId' => $event->runWorkflowId,
        'action' => $event->action,
        'payload' => $event->payload,
        'workflow' => $event->workflow,
        'timestamp' => now()->toDateTimeString(),
        'meta' => $event->meta,
    ]
);
```

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

### Query with Multiple Parameters

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Example of a Query with multiple constructor parameters, including defaults, and usage with named arguments.

```php
class GetOrders extends Query
{
    public function __construct(
        private readonly int $userId,
        private readonly string $status = 'completed',
        private readonly int $limit = 10,
    ) {}

    public function handle(): Collection
    {
        return Order::where('user_id', $this->userId)
            ->where('status', $this->status)
            ->limit($this->limit)
            ->get();
    }
}

// Usage
$orders = GetOrders::run(userId: 42);
$orders = GetOrders::run(userId: 42, status: 'pending', limit: 5);
```

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

### Example Paths with Domains Disabled

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Shows the resulting file paths when BRAIN_USE_DOMAINS is disabled (default).

```text
app/Brain/Workflows/CreateUser.php
app/Brain/Actions/RegisterUser.php
```

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

### Using Terminal facade to get columns

Source: https://github.com/r2luna/brain/blob/main/_autodocs/api-reference/service-provider.md

Example usage of the Terminal facade to retrieve the number of terminal columns via Terminal::cols().

```php
use Brain\Facades\Terminal;

$columns = Terminal::cols(); // number of terminal columns
```

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

### Terminal Output: brain:show example output

Source: https://github.com/r2luna/brain/blob/main/README.md

Example output from the brain:show command showing processes, tasks, and queries grouped by module, with status indicators like 'queued' and 'chained'.

```text
  USERS
  ├── PROC  CreateUserProcess ·······························
  ├── TASK  SendWelcomeEmailTask ····························
  ├── TASK  NotifyStaffTask ································· queued
  └── QERY  GetUserByEmailQuery ·····························

  PAYMENTS
  ├── PROC  PaymentSucceededProcess ················· chained
  └── QERY  GetPaymentQuery ································
```

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

### Custom listener usage example

Source: https://github.com/r2luna/brain/blob/main/_autodocs/api-reference/events.md

Shows how to register custom listeners for ActionProcessed and ActionError events in EventServiceProvider::$listen, and provides a listener class example with available event properties.

```php
use Brain\Actions\Events\Processed as ActionProcessed;
use Brain\Actions\Events\Error as ActionError;

// In your EventServiceProvider::$listen:
protected $listen = [
    ActionProcessed::class => [NotifyAdminOfActionCompletion::class],
    ActionError::class     => [LogActionErrorToExternalService::class],
];
```

```php
// Listener
class NotifyAdminOfActionCompletion
{
    public function handle(ActionProcessed $event): void
    {
        // $event->action        → class name
        // $event->payload       → payload object
        // $event->workflow      → parent workflow class or null
        // $event->runWorkflowId → run UUID
        // $event->meta          → ['microtime' => seconds]
    }
}
```

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

### Nesting Workflows as Sub-Workflows

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Shows how to nest workflows by including another Workflow class in the `$actions` array. The example mixes a workflow with regular actions.

```php
class OnboardUser extends Workflow
{
    protected array $actions = [
        CreateUser::class,          // another Workflow
        SetupBilling::class,        // an Action
        SendOnboardingEmail::class, // an Action
    ];
}
```

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

### Classic query usage with constructor input

Source: https://github.com/r2luna/brain/blob/main/_autodocs/api-reference/query.md

Example of running a query class with a single positional argument.

```php
use App\Brain\Users\GetUserByEmailQuery;

$user = GetUserByEmailQuery::run('john@example.com');
```

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

### Final event class marker example

Source: https://github.com/r2luna/brain/blob/main/_autodocs/api-reference/events.md

One-line marker for final event classes, with a docblock describing the event. Shown as an example of the pattern used for all final event classes.

```php
/** Dispatched when an action has been successfully processed. */
final class Processed extends BaseEvent {}
```

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

### Query Returning Aggregates

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Example of a Query that returns an aggregate value (sum) and its usage.

```php
class GetMonthlyRevenue extends Query
{
    public function __construct(
        private readonly int $year,
        private readonly int $month,
    ) {}

    public function handle(): float
    {
        return Payment::whereYear('created_at', $this->year)
            ->whereMonth('created_at', $this->month)
            ->sum('amount');
    }
}

$revenue = GetMonthlyRevenue::run(year: 2025, month: 11);
```

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

### Basic Query Class Structure

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

A Query class with constructor parameters and a handle() method that returns the result. The example shows a query fetching a user by email.

```php
<?php

namespace App\Brain\Queries;

use App\Models\User;
use Brain\Query;

class GetUserByEmail extends Query
{
    public function __construct(
        private readonly string $email,
    ) {}

    public function handle(): ?User
    {
        return User::where('email', $this->email)->first();
    }
}
```

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

### Query class implementation with constructor and handle()

Source: https://github.com/r2luna/brain/blob/main/_autodocs/api-reference/query.md

Shows a concrete query class extending Query, with constructor inputs and handle() logic. Includes usage examples with named and positional arguments.

```php
namespace App\Brain\Users;

use App\Models\User;
use Brain\Query;

class GetUserByEmailQuery extends Query
{
    public function __construct(
        private readonly string $email,
        private readonly bool $withRoles = false,
    ) {}

    public function handle(): ?User
    {
        $query = User::query()->where('email', $this->email);

        if ($this->withRoles) {
            $query->with('roles');
        }

        return $query->first();
    }
}

// Usage
$user  = GetUserByEmailQuery::run(email: 'john@example.com');
$withRoles = GetUserByEmailQuery::run('john@example.com', withRoles: true);
```

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

### Register event listeners in EventServiceProvider

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Register listeners for workflow and action events using the $listen property. This example listens for WorkflowCompleted and ActionFailed events.

```php
use Brain\Workflows\Events\Processed as WorkflowCompleted;
use Brain\Actions\Events\Error as ActionFailed;

protected $listen = [
    WorkflowCompleted::class => [
        NotifyAdmin::class,
    ],
    ActionFailed::class => [
        AlertOpsTeam::class,
    ],
];
```

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

### Custom root directory

Source: https://github.com/r2luna/brain/blob/main/README.md

Set BRAIN_ROOT in .env to change the base directory for Brain components. Example creates files in app/Domain instead of app/Brain.

```bash
# .env
BRAIN_ROOT=Domain  # Creates files in app/Domain instead of app/Brain
```

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

### Terminal Output: brain:show verbose output

Source: https://github.com/r2luna/brain/blob/main/README.md

Example output with -vv showing sub-tasks and task properties. Arrows indicate input (→) and output (←) properties.

```text
  USERS
  ├── PROC  PaymentSucceededProcess ················· chained
  │         ├── 1. T SavePaymentTask ················ queued
  │         └── 2. T InviteUserTask ·························
  ├── TASK  CreateCommentTask ·······························
  │            → user_id: int
  │            ← comment: \Comment|null
  └── QERY  ExampleQuery ···································
```

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

### Chaining Queued Actions with $chain = true

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

When `$chain` is set to true, queued actions are dispatched as a Laravel Bus chain instead of individually. All actions in the example implement ShouldQueue.

```php
class SyncData extends Workflow
{
    protected bool $chain = true;

    protected array $actions = [
        FetchExternalData::class,  // ShouldQueue
        TransformData::class,      // ShouldQueue
        SaveData::class,           // ShouldQueue
    ];
}
```

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

### Register Custom Event Listeners for Brain Events

Source: https://github.com/r2luna/brain/blob/main/README.md

Register custom event listeners in `app/Providers/EventServiceProvider.php` to handle Brain events. The example listens for `ProcessProcessed` and `TaskError` events.

```php
// app/Providers/EventServiceProvider.php

use Brain\Processes\Events\Processed as ProcessProcessed;
use Brain\Tasks\Events\Error as TaskError;

protected $listen = [
    ProcessProcessed::class => [
        NotifyAdminOfProcessCompletion::class,
    ],
    TaskError::class => [
        LogTaskErrorToExternalService::class,
    ],
];
```

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

### ExampleTask class with validation rules

Source: https://github.com/r2luna/brain/blob/main/todo.md

Defines a task class extending Task with validation rules for name and email fields. The rules method specifies required, string, and max length constraints for name, and required, email, and max length for email. The handle method is left empty for implementation.

```php
    /**
     * Class ExampleTask
     *
     * @property-read string $name
     * @property-read string $email
     */
    class ExampleTask extends Task
    {
        protected function rules(): array
        {
            return [
                'name' => ['required', 'string', 'max:255'],
                'email' => ['required', 'email', 'max:80']
            ];
        }

        public function handle():void
        {
            // ...
        }
    }
```

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

### Run Brain Process or Task Interactively

Source: https://github.com/r2luna/brain/blob/main/README.md

Use the `brain:run` command to interactively select and execute a Process or Task. Guides through selecting a target, choosing dispatch mode (sync or async), filling payload, previewing, and executing.

```bash
php artisan brain:run
```

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

### PHP: Using Query, Process, Task, and Dispatch

Source: https://github.com/r2luna/brain/blob/main/README.md

Shows how to run a query, define a process with tasks, run it synchronously, run a task directly, and dispatch to the queue. Includes async tasks and a sub-process.

```php
// Using a Query
$user = GetUserByEmailQuery::run('john@example.com');

// Setting up a Process
class CreateUserProcess extends Process
{
    protected array $tasks = [
        RegisterUserTask::class,
        SendWelcomeEmailTask::class, // Async task
        NotifyStaffTask::class, // Async task
        SubProcess::class
    ];
}

// Running a Process synchronously
CreateUserProcess::run([
    'name' => 'John Doe',
    'email' => 'john@example.com'
]);

// Running a Task without a process
SendWelcomeEmailTask::run([
    'user' => $user
]);

// Dispatching to the queue
CreateUserProcess::dispatch([
    'name' => 'John Doe',
    'email' => 'john@example.com'
]);
```

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

### Create a Process with php artisan make:process

Source: https://github.com/r2luna/brain/blob/main/README.md

Run this artisan command to scaffold a new process class. The domain prompt appears only when BRAIN_USE_DOMAINS=true. Generated file paths differ based on domain usage.

```bash
php artisan make:process
... follow prompt
name: CreateUserProcess
domain: Users  # Only asked if BRAIN_USE_DOMAINS=true
```

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

### Preview migration with brain:migrate --dry-run

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Shows planned changes without applying them. Output lists files to update, files to rename, and directories to rename.

```bash
php artisan brain:migrate --dry-run
```

```text
 Brain Migration: Process/Task → Workflow/Action
 ─────────────────────────────────────────────────
 Directory: /app/Brain
 Mode: dry-run (no changes will be made)

 Files to update:
   • Processes/CreateOrder.php
   • Tasks/ChargeUser.php

 Files to rename:
   • CreateOrderProcess.php → CreateOrderWorkflow.php

 Directories to rename:
   • Processes → Workflows
   • Tasks → Actions

 Dry-run complete. No changes were made.
```

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

### Enable v1.x domain behavior

Source: https://github.com/r2luna/brain/blob/main/README.md

Add this to your .env file to maintain v1.x domain organization in v2.0.

```bash
BRAIN_USE_DOMAINS=true
```

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

### Documenting Properties with Annotations

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Shows the recommended PHPDoc annotations for input and output properties.

```php
/**
 * @property-read string $name       ← input (required)
 * @property-read string $email      ← input (required)
 * @property int $userId             ← output (set during handle)
 */
```

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

### Create a Task with php artisan make:task

Source: https://github.com/r2luna/brain/blob/main/README.md

Run this artisan command to scaffold a new task class. The domain prompt appears only when BRAIN_USE_DOMAINS=true. Generated file paths differ based on domain usage.

```bash
php artisan make:task
... follow prompt
name: SendWelcomeEmailTask
domain: Users  # Only asked if BRAIN_USE_DOMAINS=true
```

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

### Creating a Query with Artisan

Source: https://github.com/r2luna/brain/blob/main/README.md

Run `php artisan make:query` and follow the prompt to create a new query class. The `domain` is only asked if `BRAIN_USE_DOMAINS=true`. The generated file path depends on whether domains are used.

```bash
php artisan make:query
... follow prompt
name: GetUserByEmailQuery
domain: Users  # Only asked if BRAIN_USE_DOMAINS=true
model: User
```

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

### boot() method signature

Source: https://github.com/r2luna/brain/blob/main/_autodocs/api-reference/service-provider.md

Public method signature for boot(). It is empty in the package itself; subclasses of the ejected copy may extend it.

```php
public function boot(): void {}
```

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

### Create a new Query class with make:query

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Scaffolds a new Query class. You can optionally specify a model when prompted.

```bash
php artisan make:query GetUserByEmail
```

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

### Run the Workflow

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Execute the CreateUser workflow with input data. The workflow runs RegisterUser inside a database transaction; if any action throws an exception, the entire transaction is rolled back.

```php
CreateUser::run([
    'name'  => 'John Doe',
    'email' => 'john@example.com',
]);
```

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

### Configuration Suffixes Migration from v2.x to v3.0

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Shows the change in configuration suffix keys from 'process'/'task' to 'workflow'/'action' in v3.0. The old keys still work but are deprecated.

```php
// v2.x
'suffixes' => [
    'process' => 'Process',
    'task'    => 'Task',
],

// v3.0
'suffixes' => [
    'workflow' => 'Workflow',
    'action'  => 'Action',
],
```

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

### Static run() Method Migration from v2.x to v3.0

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Shows the change from dispatchSync() to the new static run() method in v3.0. The old dispatchSync() still works but run() is recommended for synchronous execution.

```php
// v2.x
CreateUser::dispatchSync($payload);
RegisterUser::dispatchSync($payload);

// v3.0
CreateUser::run($payload);
RegisterUser::run($payload);
```

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

### Run tests with Composer

Source: https://github.com/r2luna/brain/blob/main/README.md

Executes the project's test suite using Composer. Run this command from the project root to verify code changes.

```bash
composer test
```

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

### Create an Action with Artisan

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Generate a new Action class at app/Brain/Actions/RegisterUser.php.

```bash
php artisan make:action RegisterUser
```

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

### Automatic Migration Commands for v3.0

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Commands to preview and apply the automatic migration to v3.0. The --dry-run flag previews changes first, then the second command applies the migration.

```bash
php artisan brain:migrate --dry-run   # preview changes first
php artisan brain:migrate             # apply the migration
```

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

### Example usage of OnQueue attribute

Source: https://github.com/r2luna/brain/blob/main/_autodocs/api-reference/attributes.md

Shows applying #[OnQueue('strava')] to a workflow class. Child actions without their own queue inherit the parent queue, while those with their own queue take precedence.

```php
use Brain\Attributes\OnQueue;
use Brain\Workflow;
use Illuminate\Contracts\Queue\ShouldQueue;

#[OnQueue('strava')]
class SyncActivitiesWorkflow extends Workflow implements ShouldQueue
{
    protected array $actions = [
        FetchActivitiesAction::class, // ShouldQueue, no own queue → runs on "strava"
        NotifyUserAction::class,      // #[OnQueue('emails')] → runs on "emails" (own queue wins)
    ];
}
```

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

### Merging action-level and workflow-level sensitive keys

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Keys declared by any action apply to the whole workflow, so they are redacted from the start, including in events of earlier, skipped, and cancelled actions. Here, 'password' from the workflow and 'cvv' from ChargeCustomer are both redacted.

```php
#[Sensitive('password')]
class CreateUser extends Workflow
{
    protected array $actions = [
        ValidateInput::class,  // password and cvv redacted
        ChargeCustomer::class, // has #[Sensitive('cvv')]
    ];
}
```

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

### Execution Pattern: All actions on the same queue

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Flowchart showing the workflow and every queued action running on the 'strava' queue.

```mermaid
flowchart LR
    D((Dispatch)) --> Q[strava queue]

    subgraph Q[strava queue]
        direction LR
        P[SyncActivities] --> T1[FetchActivities]
        T1 --> T2[TransformData]
        T2 --> T3[SaveActivities]
    end
```

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

### Sensitive usage example with workflow inheritance

Source: https://github.com/r2luna/brain/blob/main/_autodocs/api-reference/attributes.md

Shows applying #[Sensitive] to an Action and a Workflow. Children inherit keys even without declaring the attribute. Demonstrates keysFor and keysForAll calls.

```php
use Brain\Action;
use Brain\Attributes\Sensitive;
use Brain\Workflow;

/**
 * @property-read string $email
 */
#[Sensitive('password', 'credit_card')]
class CreateUserAction extends Action
{
    public function handle(): self
    {
        // $this->password — real value (redacted everywhere else)
        return $this;
    }
}

// Workflow-level inheritance: children inherit even without declaring it.
#[Sensitive('password', 'credit_card')]
class CreateUserWorkflow extends Workflow
{
    protected array $actions = [
        ValidateInputAction::class,   // password & credit_card are sensitive here too
        ChargeCustomerAction::class,
    ];
}

// In code:
$keys = Sensitive::keysFor(CreateUserAction::class);          // ['password', 'credit_card']
$keys = Sensitive::keysForAll(CreateUserWorkflow::$actions); // includes nested workflow actions
```

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

### Enable Domain Organization

Source: https://github.com/r2luna/brain/blob/main/README.md

Organize code into domain-specific subdirectories. When enabled, creates structure like 'app/Brain/Users/Processes'. Default is false.

```bash
# .env
BRAIN_USE_DOMAINS=false
```

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

### Republish config file

Source: https://github.com/r2luna/brain/blob/main/README.md

Run this command to republish the configuration file with the new v2.0 structure. Use --force to overwrite the existing config.

```bash
php artisan vendor:publish --provider="Brain\BrainServiceProvider" --force
```

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

### Mark payload properties as sensitive with #[Sensitive]

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Use #[Sensitive] on an Action class to redact listed properties in logs, JSON, debug output, and error messages. Inside handle(), $this->password returns the real value, while $this->payload->password returns a SensitiveValue object; call ->value() to get the real value.

```php
use Brain\Attributes\Sensitive;
use Brain\Action;

/**
 * @property-read string $email
 * @property string $password
 * @property string $credit_card
 */
#[Sensitive('password', 'credit_card')]
class CreateUser extends Action
{
    public function handle(): self
    {
        // $this->password returns the real value inside handle()
        // but logs, JSON, and debug output show "**********"
        return $this;
    }
}
```

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

### Full Brain Config File

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

PHP configuration file with all options, using environment variables with defaults.

```php
<?php

return [
    'root'        => env('BRAIN_ROOT', 'Brain'),
    'use_domains' => env('BRAIN_USE_DOMAINS', false),
    'use_suffix'  => env('BRAIN_USE_SUFFIX', false),
    'suffixes'    => [
        'workflow' => env('BRAIN_WORKFLOW_SUFFIX', 'Workflow'),
        'action'  => env('BRAIN_ACTION_SUFFIX', 'Action'),
        'query'   => env('BRAIN_QUERY_SUFFIX', 'Query'),
    ],
    'log'         => env('BRAIN_LOG_ENABLED', false),
];
```

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

### Legacy v2 Process and Task Example

Source: https://github.com/r2luna/brain/blob/main/_autodocs/api-reference/process-task.md

Shows the legacy v2 pattern using Process and Task classes. CreateUserProcess::run() executes synchronously, while dispatch() sends to the queue. Inside a task, $this->cancelProcess() cancels the process. Use php artisan brain:migrate to rewrite this code to Workflow/Action automatically.

```php
use App\Brain\Users\CreateUserProcess;
use Brain\Task;

/**
 * @property-read string $email
 */
class RegisterUserTask extends Task
{
    public function handle(): self
    {
        // ...
        return $this;
    }
}

class CreateUserProcess extends Process
{
    protected array $tasks = [
        RegisterUserTask::class,
    ];
}

CreateUserProcess::run(['email' => 'john@example.com']); // sync
CreateUserProcess::dispatch(['email' => 'john@example.com']); // queue

// Cancelling from inside a task:
if ($anyReason) {
    $this->cancelProcess();
}
```

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

### Create a Workflow with Artisan

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Generate a new Workflow class at app/Brain/Workflows/CreateUser.php.

```bash
php artisan make:workflow CreateUser
```

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

### Create a Query with Artisan

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Use the artisan command to generate a new Query class. Optionally specify a model when prompted.

```bash
php artisan make:query GetUserByEmail
```

```bash
php artisan make:query GetUserByEmail
# When prompted, enter: User
```

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

### Basic Action Structure

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Shows the minimal structure of an action class, including the handle() method and property annotations.

```php
<?php

namespace App\Brain\Actions;

use Brain\Action;

/**
 * @property-read string $name
 * @property-read string $email
 */
class RegisterUser extends Action
{
    public function handle(): self
    {
        $user = User::create([
            'name'  => $this->name,
            'email' => $this->email,
        ]);

        // Pass data to subsequent actions
        $this->userId = $user->id;

        return $this;
    }
}
```

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

### Composer lint and test commands

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Use these commands to check code style, run the full test suite, perform static analysis, and run unit tests with coverage. The comments indicate what each command does.

```bash
composer lint          # Fix code style
composer test          # Run full test suite
composer test:types    # Static analysis
composer test:unit     # Unit tests with coverage
```

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

### Execution Pattern: Mixed sync and queued

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Flowchart showing some actions run inside the workflow, others are dispatched to queues.

```mermaid
flowchart LR
    D((Dispatch)) --> Q

    subgraph Q[strava queue]
        subgraph P[SyncActivities]
            direction LR
            T1[FetchActivities] --> T2[TransformData]
        end
        T2 --> T3[SaveActivities]
    end

    T3 -.-> E[emails queue]

    subgraph E[emails queue]
        T4[NotifyUser]
    end
```

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

### Domain organization behavior comparison

Source: https://github.com/r2luna/brain/blob/main/README.md

Shows the file paths for v1.x automatic domains, v2.0 default flat structure, and v2.0 with BRAIN_USE_DOMAINS=true. The v2.0 default is flat; enabling the env var restores v1.x behavior.

```php
// v1.x behavior (automatic domains)
app/Brain/Users/Processes/CreateUserProcess.php

// v2.0 default behavior (flat structure)
app/Brain/Processes/CreateUserProcess.php

// v2.0 with BRAIN_USE_DOMAINS=true (same as v1.x)
app/Brain/Users/Processes/CreateUserProcess.php
```

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

### Run unit tests with composer test:unit

Source: https://github.com/r2luna/brain/blob/main/CONTRIBUTING.md

Executes the unit test suite.

```bash
composer test:unit
```

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

### Enable Logging

Source: https://github.com/r2luna/brain/blob/main/README.md

Enables logging for all processes and tasks. See Logging section for details. Default is false.

```bash
# .env
BRAIN_LOG_ENABLED=false
```

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

### Running a Workflow Synchronously and Asynchronously

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Shows how to run a workflow synchronously (within a transaction) using `run()` or asynchronously (queued) using `dispatch()`. Both methods accept the same payload array.

```php
// Synchronous (within a transaction)
CreateUser::run([
    'name'  => 'John Doe',
    'email' => 'john@example.com',
]);

// Asynchronous (queued)
CreateUser::dispatch([
    'name'  => 'John Doe',
    'email' => 'john@example.com',
]);
```

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

### run() static method signature

Source: https://github.com/r2luna/brain/blob/main/_autodocs/api-reference/query.md

Executes the query by creating a new instance of the concrete class with the provided arguments and invoking handle().

```php
public static function run(mixed ...$arguments): mixed
```

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

### Listen to events with closures

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Use Event::listen with a closure to handle the Processed event, logging action completion details.

```php
use Brain\Actions\Events\Processed;

Event::listen(Processed::class, function ($event) {
    logger()->info('Action completed', [
        'task'    => $event->task,
        'process' => $event->process,
    ]);
});
```

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

### Show verbosity levels with brain:show -v and -vv

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Use -v to show sub-actions inside workflows, and -vv to also show action properties. The output includes input (→) and output (←) properties.

```bash
php artisan brain:show -v              # show sub-actions inside workflows
php artisan brain:show -vv             # also show action properties
```

```text
WKFL    PaymentSucceededWorkflow ······························· chained
        ├── 1. A SavePaymentAction ······················ queued
        └── 2. A InviteUserAction ······························
ACTN    CreateCommentAction ····································
           → user_id: int
           ← comment: \Comment|null
QERY    ExampleQuery ···········································
```

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

### Standalone Usage of an Action

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Shows how to run an action independently using the run() method.

```php
RegisterUser::run([
    'name'  => 'John Doe',
    'email' => 'john@example.com',
]);
```

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

### Flexible Root Directory Configuration in v2.0

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Sets the root directory for Brain components to 'Domain' instead of the default 'Brain'.

```bash
BRAIN_ROOT=Domain  # app/Domain instead of app/Brain
```

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

### Invoke a Query with run()

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Queries are invoked using the static run() method with named arguments.

```php
$user = GetUserByEmail::run(email: 'john@example.com');
```

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

### Domain Organization Changes from v1.x to v2.0

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Shows the change in default directory structure from automatic domain organization in v1.x to flat structure in v2.0, with opt-in domains via BRAIN_USE_DOMAINS=true.

```php
// v1.x (automatic domains)
app/Brain/Users/Processes/CreateUser.php

// v2.0 default (flat structure)
app/Brain/Processes/CreateUser.php

// v2.0 with BRAIN_USE_DOMAINS=true
app/Brain/Users/Processes/CreateUser.php
```

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

### Passing Data Between Actions

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Shows how to set properties on an action to pass data to subsequent actions in a workflow.

```php
class RegisterUser extends Action
{
    public function handle(): self
    {
        $user = User::create([...]);
        $this->userId = $user->id; // available in next action
        return $this;
    }
}

class SendWelcomeEmail extends Action
{
    public function handle(): self
    {
        $userId = $this->userId; // set by RegisterUser
        // ...
        return $this;
    }
}
```

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

### handleTestCreation method

Source: https://github.com/r2luna/brain/blob/main/_autodocs/api-reference/console-classes.md

Delegates test creation to brain:make:test. Returns false when no test options are set, otherwise calls the inner command and returns true on exit status 0.

```php
protected function handleTestCreation($path): bool
```

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

### Adding Actions Dynamically with addAction()

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Shows how to conditionally add an action in the constructor using `addAction()`. The action is added only when the `send_welcome` payload flag is true.

```php
class CreateUser extends Workflow
{
    protected array $actions = [
        RegisterUser::class,
    ];

    public function __construct(array $payload = [])
    {
        parent::__construct($payload);

        if ($payload['send_welcome'] ?? false) {
            $this->addAction(SendWelcomeEmail::class);
        }
    }
}
```

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

### Execution Pattern: Workflow queued, actions synchronous

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Flowchart showing the workflow queued, but actions run synchronously inside the job.

```mermaid
flowchart LR
    D((Dispatch)) --> Q

    subgraph Q[strava queue]
        subgraph P[SyncActivities]
            direction LR
            T1[FetchActivities] --> T2[TransformData] --> T3[SaveActivities]
        end
    end
```

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

### Publishing config via artisan vendor:publish

Source: https://github.com/r2luna/brain/blob/main/_autodocs/api-reference/service-provider.md

Commands to publish the package configuration. Use the provider or the tag 'brain:config'. The publish tag is brain:config.

```bash
php artisan vendor:publish --provider="Brain\BrainServiceProvider"
# or by tag
php artisan vendor:publish --tag=brain:config
```

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

### Setting a Queue with #[OnQueue]

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Use the #[OnQueue] attribute to assign a specific queue. Do not declare public string $queue on an Action; it causes a PHP fatal error. Always use #[OnQueue] instead.

```php
use Brain\Attributes\OnQueue;
use Brain\Action;
use Illuminate\Contracts\Queue\ShouldQueue;

#[OnQueue('emails')]
class SendWelcomeEmail extends Action implements ShouldQueue
{
    public function handle(): self
    {
        return $this;
    }
}
```

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

### Enable Class Name Suffixes

Source: https://github.com/r2luna/brain/blob/main/README.md

Automatically appends suffixes to class names (e.g., 'CreateUser' becomes 'CreateUserProcess'). Default is false.

```bash
# .env
BRAIN_USE_SUFFIX=false
```

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

### Helper Method toArray()

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Shows how to use the toArray() helper method to return the action payload as an array.

```php
$action = RegisterUser::run(['name' => 'John', 'email' => 'john@example.com']);
$action->toArray(); // ['name' => 'John', 'email' => 'john@example.com']
```

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

### runIn method signature with docblock

Source: https://github.com/r2luna/brain/blob/main/_autodocs/api-reference/action.md

Protected method to set when the action needs to run for the first time in the future. Default returns null (no delay). Override to return seconds (int) or a Carbon future date; the constructor then calls $this->delay($runIn).

```php
/**
 * This method will set when the action needs to
 * run for the first time in the future
 *
 * @return int|Carbon|null Return seconds or carbon instance in future date
 */
protected function runIn(): int|Carbon|null
```

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

### Brain\BrainServiceProvider::boot

Source: https://github.com/r2luna/brain/blob/main/_autodocs/api-reference/service-provider.md

Boot method for the service provider. Empty in the package itself, but subclasses of the ejected copy may extend it.

```APIDOC
## Brain\BrainServiceProvider::boot

### Description
Boot method for the service provider. Empty in the package itself, but subclasses of the ejected copy may extend it.

### Method
boot

### Signature
public function boot(): void

### Parameters
None

### Return Value
void

### Usage Example
```php
// The boot method is called automatically by Laravel during service provider boot.
// No direct call is needed.
```
```

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

### Set Brain Root Directory

Source: https://github.com/r2luna/brain/blob/main/README.md

Define the main directory where processes, tasks, and queries are created. Default is 'Brain'.

```bash
# .env
BRAIN_ROOT=Brain
```

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

### Migrate Process/Task to Workflow/Action with brain:migrate

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Automatically migrates codebase from Process/Task naming to Workflow/Action naming. Applies changes to imports, class inheritance, task arrays, namespaces, file suffixes, class references, and directories. All replacements are case-insensitive.

```bash
php artisan brain:migrate
```

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

### Filter brain:show by type

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Use flags -w, -a, -Q to show only workflows, actions, or queries respectively. Combine flags to show multiple types.

```bash
php artisan brain:show -w              # only workflows
php artisan brain:show -a              # only actions
php artisan brain:show -Q              # only queries
php artisan brain:show -w -a           # workflows and actions
```

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

### possibleDomains method signature

Source: https://github.com/r2luna/brain/blob/main/_autodocs/api-reference/console-classes.md

Returns an array of directory names under app_path('Brain'), creating the directory if missing. Used for interactive domain argument suggestions.

```php
public function possibleDomains(): array
```

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

### Queueable Action: SendWelcomeEmail implements ShouldQueue

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Implement ShouldQueue on an Action to dispatch it to the queue. The handle() method runs on the queue.

```php
use Brain\Action;
use Illuminate\Contracts\Queue\ShouldQueue;

class SendWelcomeEmail extends Action implements ShouldQueue
{
    public function handle(): self
    {
        // runs on the queue
        return $this;
    }
}
```

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

### Set BRAIN_USE_DOMAINS Environment Variable

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Organizes code into domain-specific subdirectories. When enabled, paths include domain names; when disabled (default), they do not.

```bash
BRAIN_USE_DOMAINS=false
```

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

### Visualize Brain structure with brain:show

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Displays the entire Brain structure in the terminal, listing workflows, actions, and queries with their statuses.

```bash
php artisan brain:show
```

```text
WKFL    CreateUserWorkflow ······································
WKFL    PaymentSucceededWorkflow ······························· chained
ACTN    NotifyStaffAction ································ queued
ACTN    RegisterUserAction ·····································
ACTN    SendWelcomeEmailAction ·································
QERY    GetPaymentQuery ········································
QERY    GetUserByEmailQuery ····································
```

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

### runIn

Source: https://github.com/r2luna/brain/blob/main/_autodocs/api-reference/action.md

Sets when the action needs to run for the first time in the future. Override to return seconds or a Carbon future date.

```APIDOC
## runIn

### Description
This method will set when the action needs to run for the first time in the future. Default returns `null` (no delay). Override to return seconds (int) or a `Carbon` future date; the constructor then calls `$this->delay($runIn)`.

### Method
`runIn`

### Signature
```php
protected function runIn(): int|Carbon|null
```

### Returns
`int|Carbon|null` — Return seconds or carbon instance in future date.
```

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

### Bash: brain:show filtering by type

Source: https://github.com/r2luna/brain/blob/main/README.md

Shows how to filter brain:show output by type using flags -p (processes), -t (tasks), -Q (queries), and combinations.

```bash
php artisan brain:show -p              # only processes
php artisan brain:show -t              # only tasks
php artisan brain:show -Q              # only queries
php artisan brain:show -p -t           # processes and tasks
```

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

### Composer commands for testing and code quality

Source: https://github.com/r2luna/brain/blob/main/CLAUDE.md

Lists the composer scripts for running tests, static analysis, linting, refactoring, and typo checks.

```bash
composer test          # Run full test suite (debug, refactor, lint, types, typos, unit)
composer test:unit     # Run Pest tests with coverage (min 100%)
composer test:types    # Run PHPStan static analysis
composer test:lint     # Run Pint code style check
composer test:refactor # Run Rector dry-run
composer test:typos    # Run Peck typo check
composer lint          # Fix code style with Pint
composer refactor      # Apply Rector refactorings
```

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

### Optional Class Suffixes in v2.0

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Enables the use of class suffixes for generated workflows. With this setting, 'make:workflow CreateUser' generates 'CreateUserWorkflow.php'.

```bash
BRAIN_USE_SUFFIX=true
# php artisan make:workflow CreateUser → CreateUserWorkflow.php
```

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

### afterPromptingForMissingArguments method override

Source: https://github.com/r2luna/brain/blob/main/_autodocs/api-reference/console-classes.md

Provides interactive suggestions for missing arguments: model, domain, and a Pest test prompt. Skips when name is reserved or options were passed explicitly.

```php
protected function afterPromptingForMissingArguments(InputInterface $input, OutputInterface $output): void
```

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

### Basic synchronous run of an Action

Source: https://github.com/r2luna/brain/blob/main/_autodocs/api-reference/action.md

Defines an Action class with a handle() method that sets a token via magic __set, then runs it synchronously with run() and accesses the resulting payload property.

```php
use App\Brain\Users\RegisterUserAction;
use Brain\Action;

/**
 * @property-read string $email
 * @property string $token
 */
class RegisterUserAction extends Action
{
    public function handle(): self
    {
        $this->token = Str::random(40); // magic __set

        return $this;
    }
}

$payload = RegisterUserAction::run(['email' => 'john@example.com']);
echo $payload->token; // real value assigned in handle()
```

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

### getMap method

Source: https://github.com/r2luna/brain/blob/main/_autodocs/api-reference/console-classes.md

Builds the map collection from directories. Each directory becomes an entry keyed by basename, with metadata for workflows, actions, processes, tasks, and queries.

```php
public function getMap(array $directories): Collection
```

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

### Enable logging with BRAIN_LOG_ENABLED

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Set the environment variable to enable logging. The default is true when using the config file.

```plaintext
BRAIN_LOG_ENABLED=true
```

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

### Enable Brain Logging via Environment Variable

Source: https://github.com/r2luna/brain/blob/main/README.md

Set `BRAIN_LOG_ENABLED=true` in the `.env` file to enable logging. Logging is disabled by default.

```bash
# .env
BRAIN_LOG_ENABLED=true
```

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

### Lint code with composer lint

Source: https://github.com/r2luna/brain/blob/main/CONTRIBUTING.md

Ensures the coding style is consistent. Run this before submitting a pull request.

```bash
composer lint
```

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

### Multiple arguments with error handling

Source: https://github.com/r2luna/brain/blob/main/_autodocs/api-reference/query.md

Shows how to catch exceptions thrown by handle(); Query::run does not intercept exceptions.

```php
use App\Brain\Payments\GetPaymentQuery;
use Illuminate\Database\Eloquent\ModelNotFoundException;

try {
    $payment = GetPaymentQuery::run(paymentId: 42);
} catch (ModelNotFoundException $e) {
    // handle() threw; Query::run does not intercept exceptions
}
```

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

### register() method signature

Source: https://github.com/r2luna/brain/blob/main/_autodocs/api-reference/service-provider.md

Public method signature for register(). It registers console commands, event listeners (only when config('brain.log') is truthy), and offers publishing.

```php
public function register(): void
```

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

### Enable class suffixes

Source: https://github.com/r2luna/brain/blob/main/README.md

Set BRAIN_USE_SUFFIX=true in .env to automatically append 'Process' to generated class names. Then use the make:process command without the suffix.

```bash
# .env
BRAIN_USE_SUFFIX=true

# Now you can write:
php artisan make:process CreateUser
# Creates: CreateUserProcess.php
```

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

### Process on queue with synchronous tasks

Source: https://github.com/r2luna/brain/blob/main/README.md

Defines a queued process where tasks run synchronously inside the process job. Tasks do not implement ShouldQueue, so they execute sequentially within the same job.

```php
#[OnQueue('strava')]
class SyncActivitiesProcess extends Process implements ShouldQueue
{
    protected array $tasks = [
        FetchActivities::class,    // sync (no ShouldQueue)
        TransformData::class,      // sync
        SaveActivities::class,     // sync
    ];
}
```

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

### Project structure tree

Source: https://github.com/r2luna/brain/blob/main/CLAUDE.md

Shows the directory layout of the Brain package, including source and test directories.

```text
src/
├── Workflow.php         # Base Workflow class
├── Action.php           # Base Action class
├── Query.php            # Base Query class
├── Process.php          # (deprecated) Alias for Workflow
├── Task.php             # (deprecated) Alias for Action
├── BrainServiceProvider.php
├── Attributes/          # PHP attributes (e.g., Sensitive, OnQueue)
├── Console/             # Artisan commands (make:workflow, make:action, make:query, brain:show, brain:run)
├── Exceptions/          # InvalidPayload, etc.
├── Facades/
├── Workflows/           # Workflow infrastructure (Events, Listeners)
├── Actions/             # Action infrastructure (Events, Listeners, Middleware)
├── Processes/           # (deprecated) Process infrastructure
├── Tasks/               # (deprecated) Task infrastructure
├── Queries/             # Query infrastructure (Events, Listeners)
└── Tests/               # Test stubs
tests/
├── Feature/             # Feature tests (Pest)
│   ├── Fixtures/        # Test fixture classes
│   ├── Console/         # Command tests
│   └── *Test.php        # Workflow, Action, Query, etc.
├── TestCase.php         # Base test case (Orchestra Testbench)
└── Pest.php
```

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

### BrainServiceProvider class definition

Source: https://github.com/r2luna/brain/blob/main/_autodocs/api-reference/service-provider.md

The service provider class with register() and boot() methods. register() calls private wiring methods for commands, listeners, and publishing; boot() is empty in the package.

```php
class BrainServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->registerCommands();
        $this->registerListeners();
        $this->offerPublishing();
    }

    public function boot(): void {}
}
```

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

### Basic Workflow Structure

Source: https://github.com/r2luna/brain/blob/main/docs/index.html

Defines a workflow class with an array of actions. Actions are executed in order within a database transaction.

```php
<?php

namespace App\Brain\Workflows;

use Brain\Workflow;

class CreateUser extends Workflow
{
    protected array $actions = [
        RegisterUser::class,
        SendWelcomeEmail::class,
        NotifyStaff::class,
    ];
}
```
Tokens:
Raw