README

Brain is an elegant Laravel Package that helps you organize your Laravel application using Domain-Driven Design principles through a simple command-line interface.

Features

🎯 Domain-Driven Structure: Easily create new domains with proper architecture
🔄 Process Management: Generate process classes for complex business operations
🔍 Query Objects: Create dedicated query classes for database operations
⚡ Task Management: Generate task classes for background jobs and queue operations

Gains

♻️ Code Reusability: By using tasks, you can easily reuse code across different processes, reducing duplication and enhancing maintainability.
🧩 Clear Domain Understanding: The structured approach provides a better understanding of each domain's processes, making it easier to manage and scale your application.
🔧 Improved Maintainability: With well-defined domains and processes, maintaining and updating your application becomes more straightforward and less error-prone.

Installation

You can install the package via composer:

composer require r2luna/brain

Usage

Creating a Process

php artisan make:process
... follow prompt
name: CreateUserProcess
domain: Users

This will create a new process class in app/Brain/Users/Processes/CreateUserProcess.php

Creating a Task

php artisan make:task
... follow prompt
name: SendWelcomeEmailTask
domain: Users

This will create a new task class in app/Brain/Users/Tasks/SendWelcomeEmailTask.php

Queuable Tasks

To send the task to the queue simply implements Laravel Contract ShouldQueue to the class

<?php

namespace App\Brain\User;

use Brain\Task;
use Illuminate\Contracts\Queue\ShouldQueue;

class SendWelcomeNotifications extends Task implements ShouldQueue
{
    public function handle(): self
    {
        //

        return $this;
    }
}

Delay Queueable Tasks

Brain Tasks has a protected function called runIn() that you can use to determine when do you want to run the job if you need to delay.

class SendWelcomeNotifications extends Task implements ShouldQueue
{
    protected function runIn(): int|Carbon|null
    {
        return now()->addDays(2);
    }
    ...
}

Cancel the Process

If you need, by any reason, cancel the process from inside a task. You can call cancelProcess() method to do it.

class AddRoles extends Task
{
    public function handle(): self
    {
        if($anyReason) {
            $this->cancelProcess();
        }

        return $this;
    }
}

Caution

This will not work if the task is setup to run in a queue.

Creating a Query

php artisan make:query
... follow prompt
name: GetUserByEmailQuery
domain: Users
model: User

This will create a new query class in app/Brain/Users/Queries/GetUserByEmailQuery.php

Example Usage

// 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
    ];
}

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

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

Architecture

Brain helps you organize your code into three main concepts:

Processes: Complex business operations that might involve multiple steps
Queries: Database queries and data retrieval operations
Tasks: Sync/Async operations that can be called as part of a process or not

Each concept is organized within its respective domain, promoting clean architecture and separation of concerns.

Testing

composer test

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please email rafael@lunardelli.me instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

r2luna / brain

Maintainers

Details