Padrões de Desenvolvimento Laravel

Padrões de arquitetura Laravel de nível de produção para aplicações escaláveis e de fácil manutenção.

Quando Usar

• Construindo aplicações web ou APIs Laravel
• Estruturando controllers, services e lógica de domínio
• Trabalhando com modelos e relacionamentos Eloquent
• Projetando APIs com resources e paginação
• Adicionando filas, eventos, cache e jobs em segundo plano

Como Funciona

• Estruture a aplicação em torno de limites claros (controllers -> services/actions -> models).
• Use explicit bindings e scoped bindings para manter o roteamento previsível; ainda assim, reforce a autorização para controle de acesso.
• Prefira modelos tipados, casts e scopes para manter a lógica de domínio consistente.
• Mantenha o trabalho intensivo de IO em filas e cacheie leituras caras.
• Centralize a configuração em config/* e mantenha os ambientes explícitos.

Exemplos

Estrutura do Projeto

Use um layout Laravel convencional com limites de camada claros (HTTP, services/actions, models).

Layout Recomendado

app/
├── Actions/            # Single-purpose use cases
├── Console/
├── Events/
├── Exceptions/
├── Http/
│   ├── Controllers/
│   ├── Middleware/
│   ├── Requests/       # Form request validation
│   └── Resources/      # API resources
├── Jobs/
├── Models/
├── Policies/
├── Providers/
├── Services/           # Coordinating domain services
└── Support/
config/
database/
├── factories/
├── migrations/
└── seeders/
resources/
├── views/
└── lang/
routes/
├── api.php
├── web.php
└── console.php

Controllers -> Services -> Actions

Mantenha os controllers enxutos. Coloque a orquestração em services e a lógica de propósito único em actions.

final class CreateOrderAction
{
    public function __construct(private OrderRepository $orders) {}

    public function handle(CreateOrderData $data): Order
    {
        return $this->orders->create($data);
    }
}

final class OrdersController extends Controller
{
    public function __construct(private CreateOrderAction $createOrder) {}

    public function store(StoreOrderRequest $request): JsonResponse
    {
        $order = $this->createOrder->handle($request->toDto());

        return response()->json([
            'success' => true,
            'data' => OrderResource::make($order),
            'error' => null,
            'meta' => null,
        ], 201);
    }
}

Roteamento e Controllers

Prefira route-model binding e resource controllers para clareza.

use Illuminate\Support\Facades\Route;

Route::middleware('auth:sanctum')->group(function () {
    Route::apiResource('projects', ProjectController::class);
});

Route Model Binding (Escopo)

Use bindings com escopo para prevenir acesso entre tenants.

Route::scopeBindings()->group(function () {
    Route::get('/accounts/{account}/projects/{project}', [ProjectController::class, 'show']);
});

Rotas Aninhadas e Nomes de Binding

• Mantenha prefixos e caminhos consistentes para evitar aninhamento duplo (por exemplo, conversation vs conversations).
• Use um único nome de parâmetro que corresponda ao modelo vinculado (por exemplo, {conversation} para Conversation).
• Prefira bindings com escopo ao aninhar para reforçar relacionamentos pai-filho.

use App\Http\Controllers\Api\ConversationController;
use App\Http\Controllers\Api\MessageController;
use Illuminate\Support\Facades\Route;

Route::middleware('auth:sanctum')->prefix('conversations')->group(function () {
    Route::post('/', [ConversationController::class, 'store'])->name('conversations.store');

    Route::scopeBindings()->group(function () {
        Route::get('/{conversation}', [ConversationController::class, 'show'])
            ->name('conversations.show');

        Route::post('/{conversation}/messages', [MessageController::class, 'store'])
            ->name('conversation-messages.store');

        Route::get('/{conversation}/messages/{message}', [MessageController::class, 'show'])
            ->name('conversation-messages.show');
    });
});

Se você quiser que um parâmetro resolva para uma classe de modelo diferente, defina um binding explícito. Para lógica de binding personalizada, use Route::bind() ou implemente resolveRouteBinding() no modelo.

use App\Models\AiConversation;
use Illuminate\Support\Facades\Route;

Route::model('conversation', AiConversation::class);

Bindings do Service Container

Vincule interfaces a implementações em um service provider para uma ligação de dependência clara.

use App\Repositories\EloquentOrderRepository;
use App\Repositories\OrderRepository;
use Illuminate\Support\ServiceProvider;


…