README

Laravel implementation of Utilitarian Architecture — a pragmatic approach to organizing applications around business operations (use cases) rather than technical layers.

What's Included

• CQRS-style Query, Command, and Action operations with buses, middleware, and boot-time dependency injection
• Eloquent-backed state storage and enum transition rules
• Lightweight DTO/data mapping helpers
• JSON, cache key, alert, reflection, route metadata, and debug utilities

Requirements

• PHP 8.3+
• Laravel 11+

Installation

composer require utilitarian-dev/utilitarian-laravel-toolkit

The service provider is registered automatically via Laravel's package discovery.

Optionally, publish the configuration:

php artisan vendor:publish --tag=utilitarian-config

Core Components

Query

Read-only operations. Execute via QueryBus or dispatch().

class GetUserQuery extends Query
{
    public function __construct(
        private readonly int $userId,
    ) {}

    public function execute(): ?User
    {
        return User::query()->find($this->userId);
    }
}

// Execute
$user = GetUserQuery::make(userId: 1)->dispatch();
// or
$user = QueryBus::execute(GetUserQuery::make(userId: 1));

Command

Write-only operations. Execute via CommandBus or dispatch().

class CreateUserCommand extends Command
{
    public function __construct(
        private readonly string $email,
        private readonly string $name,
    ) {}

    public function execute(): User
    {
        return User::query()->create([
            'email' => $this->email,
            'name' => $this->name,
        ]);
    }
}

// Execute
$user = CreateUserCommand::make(email: '...', name: '...')->dispatch();

Action

Business logic and orchestration. Execute via ActionBus or dispatch().

class RegisterUserAction extends Action
{
    public function __construct(
        private readonly string $email,
        private readonly string $name,
    ) {}

    public function execute(): User
    {
        $user = CreateUserCommand::make(
            email: $this->email,
            name: $this->name
        )->dispatch();

        SendWelcomeEmailCommand::make(userId: $user->id)->dispatch();

        return $user;
    }
}

// Execute
$user = RegisterUserAction::make(email: '...', name: '...')->dispatch();
// or
$user = ActionBus::execute(RegisterUserAction::make(email: '...', name: '...'));

Dependency Injection

Pass business parameters to the constructor. Inject runtime dependencies in a public boot() method.

class SyncProductToSearchIndexCommand extends Command
{
    private SearchIndexClient $search;

    public function __construct(
        private readonly Product $product,
    ) {}

    public function boot(SearchIndexClient $search): void
    {
        $this->search = $search;
    }

    public function execute(): void
    {
        $this->search->index('products', [
            'id' => $this->product->id,
            'name' => $this->product->name,
        ]);
    }
}

Middleware

Configure middleware in config/utilitarian.php:

return [
    'cqrs' => [
        'query_middleware' => [
            \Utilitarian\Cqrs\Middleware\CachingMiddleware::class,
        ],
        'command_middleware' => [
            \Utilitarian\Cqrs\Middleware\TransactionMiddleware::class,
        ],
        'action_middleware' => [
            \Utilitarian\Cqrs\Middleware\AuthorizationMiddleware::class,
        ],
    ],
];

Per-operation middleware:

class MyQuery extends Query
{
    public function middleware(): array
    {
        return [CustomMiddleware::class];
    }

    public function excludeMiddleware(): array
    {
        return [UnwantedMiddleware::class];
    }
}

Built-in middleware:

• TransactionMiddleware — wraps execution in database transaction
• CachingMiddleware — caches query results
• ValidationMiddleware — validates operation data
• AuthorizationMiddleware — checks access permissions

Optional Utilities

The package also registers helpers and facades for JSON handling, cache key generation, alerts, reflection, route metadata, and debug output.

Debugging works with Laravel's built-in dump/logging drivers by default. LaraDumps support is optional:

composer require laradumps/laradumps --dev

State Machine

Manage state for Eloquent models with three levels of complexity:

use Utilitarian\StateMachine\Traits\HasStateMachine;

class Order extends Model
{
    use HasStateMachine;
}

Key-Value Storage

$order->state()->set('notes', 'Special handling');
$order->state()->get('notes');
$order->state()->has('notes');
$order->state()->forget('notes');

Enum States (no rules)

$order->state()->transitionTo(OrderState::Paid);
$order->state()->current(); // OrderState::Paid
$order->state()->is(OrderState::Paid); // true

Enum States (with transition rules)

enum OrderState: string implements FlowHandler
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';

    public function canTransitionTo(UnitEnum $target): bool
    {
        return match ($this) {
            self::Pending => $target === self::Paid,
            self::Paid => $target === self::Shipped,
            self::Shipped => false,
        };
    }
}

$order->state()->transitionTo(OrderState::Paid); // OK
$order->state()->transitionTo(OrderState::Shipped); // throws InvalidTransitionException

Database Setup:

Migrations are loaded automatically. Run:

php artisan migrate

Data Mapping

Lightweight DTOs with automatic property mapping:

use Utilitarian\Data\Data;

class UserData extends Data
{
    public function __construct(
        public readonly int $id,
        public readonly string $email,
        public readonly string $name,
    ) {}
}

// Create from array
$userData = UserData::from([
    'id' => 1,
    'email' => 'user@example.com',
    'name' => 'John Doe',
]);

// Convert back to array
$array = $userData->toArray();

Custom field mapping:

use Utilitarian\Data\Attributes\MapField;

class UserData extends Data
{
    public function __construct(
        public readonly int $id,
        #[MapField('email_address')]
        public readonly string $email,
    ) {}
}

Testing

composer test                      # Run tests
composer test:coverage            # Run with coverage
vendor/bin/pest --filter TestName # Run specific test

Code Quality

composer lint                     # Fix code style
composer lint:test               # Check code style

License

Licensed under the Apache License 2.0. See LICENSE for details.

Credits

Created by Vasilii Shvakin