PHPackages utilitarian-dev/utilitarian-laravel-toolkit - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. utilitarian-dev/utilitarian-laravel-toolkit ActiveLibrary[Utility & Helpers](/categories/utility) utilitarian-dev/utilitarian-laravel-toolkit =========================================== Laravel implementation of Utilitarian Architecture: CQRS operations (Query, Command, Action), State Machine, and Data mapping utilities 00PHP Since Feb 6Pushed 3mo agoCompare [ Source](https://github.com/utilitarian-dev/utilitarian-laravel-toolkit)[ Packagist](https://packagist.org/packages/utilitarian-dev/utilitarian-laravel-toolkit)[ RSS](/packages/utilitarian-dev-utilitarian-laravel-toolkit/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependenciesVersions (1)Used By (0) Utilitarian Laravel Toolkit =========================== [](#utilitarian-laravel-toolkit) Laravel implementation of [Utilitarian Architecture](https://github.com/utilitarian-dev/architecture) — a pragmatic approach to organizing applications around business operations (use cases) rather than technical layers. Requirements ------------ [](#requirements) - PHP 8.3+ - Laravel 11+ Installation ------------ [](#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 --------------- [](#core-components) ### Query [](#query) Read-only operations. Execute via `QueryBus` or `dispatch()`. ``` class GetUserQuery extends Query { public function __construct( private readonly int $userId, ) {} protected function boot(UserRepository $repo): void { $this->repository = $repo; } public function execute(): ?User { return $this->repository->find($this->userId); } } // Execute $user = GetUserQuery::make(userId: 1)->dispatch(); // or $user = QueryBus::execute(GetUserQuery::make(userId: 1)); ``` ### Command [](#command) Write-only operations. Execute via `CommandBus` or `dispatch()`. ``` class CreateUserCommand extends Command { public function __construct( private readonly string $email, private readonly string $name, ) {} protected function boot(UserRepository $repo): void { $this->repository = $repo; } public function execute(): User { return $this->repository->create([ 'email' => $this->email, 'name' => $this->name, ]); } } // Execute $user = CreateUserCommand::make(email: '...', name: '...')->dispatch(); ``` ### Action [](#action) Business logic and orchestration. Execute directly via `run()`. ``` 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: '...')->run(); ``` Middleware ---------- [](#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 { protected function middleware(): array { return [CustomMiddleware::class]; } protected 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 State Machine ------------- [](#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 [](#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) [](#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-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 ------------ [](#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 ------- [](#testing) ``` composer test # Run tests composer test:coverage # Run with coverage vendor/bin/pest --filter TestName # Run specific test ``` Code Quality ------------ [](#code-quality) ``` composer lint # Fix code style composer lint:test # Check code style ``` License ------- [](#license) Licensed under the Apache License 2.0. See [LICENSE](LICENSE.txt) for details. Credits ------- [](#credits) Created by [Vasilii Shvakin](mailto:vasilii.shvakin@gmail.com) ### Health Score 18 — LowBetter than 8% of packages Maintenance55 Moderate activity, may be stable Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity12 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://www.gravatar.com/avatar/82ad382058618a119ad83d496329c4a0d15525537ea36518e0561569bb1e4d89?d=identicon)[Vasilii Shvakin](/maintainers/Vasilii%20Shvakin) --- Top Contributors [![vasiliishvakin](https://avatars.githubusercontent.com/u/771328?v=4)](https://github.com/vasiliishvakin "vasiliishvakin (1 commits)") ### Embed Badge ![Health badge](/badges/utilitarian-dev-utilitarian-laravel-toolkit/health.svg) ``` [![Health](https://phpackages.com/badges/utilitarian-dev-utilitarian-laravel-toolkit/health.svg)](https://phpackages.com/packages/utilitarian-dev-utilitarian-laravel-toolkit) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)