Laravel Knowledge Base

Quick reference for Laravel framework patterns, DDD integration strategies, and PHP 8.4 best practices for building scalable Laravel applications.

Core Principles

Service Providers

Service Providers are the central place to configure and bootstrap the application. All bindings, event listeners, middleware, and routes are registered through providers.

Facades

Facades provide a static-like interface to classes in the service container. Prefer dependency injection over Facades in Domain and Application layers; Facades are acceptable in Presentation and Infrastructure layers.

Directory Structure

Default Laravel:                DDD-Aligned Laravel:
app/                            app/
├── Http/Controllers/           src/
├── Models/                     ├── Domain/
├── Providers/                  │   ├── Order/
├── Services/                   │   │   ├── Entity/
├── Events/                     │   │   ├── ValueObject/
├── Listeners/                  │   │   ├── Repository/
├── Jobs/                       │   │   └── Event/
├── Mail/                       │   └── Customer/
└── Exceptions/                 ├── Application/
                                │   ├── Order/UseCase/
                                │   └── Customer/UseCase/
                                └── Infrastructure/
                                    ├── Persistence/
                                    ├── Http/
                                    └── Provider/

Quick Checklists

DDD-Compatible Laravel Project

• Domain layer has zero Laravel imports
• Eloquent Models live in Infrastructure, not Domain
• Repository interfaces in Domain, Eloquent implementations in Infrastructure
• Service Providers wire interfaces to implementations
• Domain Events decoupled from Laravel Event system
• Value Objects used instead of primitive types
• Controllers are thin, delegate to Use Cases
• Authorization uses Policies delegating to domain Specifications
• Queued jobs have retry strategy, failed() method, and concurrency protection
• Domain defines its own EventDispatcherInterface (not Laravel Event facade)
• Infrastructure components (Cache, HTTP Client) accessed via domain ports

Clean Architecture Checks

• No use Illuminate\... in Domain layer
• No business logic in Controllers or Middleware
• FormRequest used for input validation
• API Resources used for response transformation
• Single-action controllers for complex endpoints
• No direct DB queries in Controllers

Common Violations Quick Reference

PHP 8.4 Laravel Patterns

Single-Action Controller

<?php

declare(strict_types=1);

namespace App\Http\Controllers\Order;

use App\Application\Order\UseCase\CreateOrderUseCase;
use App\Http\Requests\Order\CreateOrderRequest;
use App\Http\Resources\Order\OrderResource;
use Illuminate\Http\JsonResponse;
use Symfony\Component\HttpFoundation\Response;

final readonly class CreateOrderController
{
    public function __construct(
        private CreateOrderUseCase $createOrder,
    ) {}

    public function __invoke(CreateOrderRequest $request): JsonResponse
    {
        $orderId = $this->createOrder->execute($request->toCommand());

        return OrderResource::make($orderId)
            ->response()
            ->setStatusCode(Response::HTTP_CREATED);
    }
}

FormRequest

<?php

declare(strict_types=1);

namespace App\Http\Requests\Order;

use App\Application\Order\Command\CreateOrderCommand;
use App\Domain\Order\ValueObject\CustomerId;
use Illuminate\Foundation\Http\FormRequest;

final class CreateOrderRequest extends FormRequest
{
    /** @return array<string, mixed> */
    public function rules(): array
    {
        return [
            'customer_id' => ['required', 'uuid'],
            'lines' => ['required', 'array', 'min:1'],
            'lines.*.product_id' => ['required', 'uuid'],
            'lines.*.quantity' => ['required', 'integer', 'min:1'],
        ];
    }

    public function toCommand(): CreateOrderCommand
    {
        return new CreateOrderCommand(
            customerId: new CustomerId($this->validated('customer_id')),
            lines: $this->validated('lines'),
        );
    }
}

Application Service (Use Case)

<?php

declare(strict_types=1);

namespace App\Application\Order\UseCase;

use App\Domain\Order\Entity\Order;
use App\Domain\Order\Repository\OrderRepositoryInterface;
use App\Domain\Order\ValueObject\OrderId;

final readonly class CreateOrderUseCase
{
    public function __construct(
        private OrderRepositoryInterface $orders,
    ) {}

    public function execute(CreateOrderCommand $command): OrderId
    {
        $order = Order::create(
            id: OrderId::generate(),
            customerId: $command->customerId,
            lines: $command->lines,
        );

        $this->orders->save($order);

        return $order->id();
    }
}

References

For detailed information, load these reference files:

• references/architecture.md -- Service Providers, Facades, directory structure, module patterns
• references/ddd-integration.md -- Extracting Domain from app/, Eloquent separation, Domain Events
• references/routing-http.md -- Controllers, middleware, FormRequest, API Resources, policies
• references/persistence.md -- Eloquent ORM, migrations, transactions, read/write splitting
• references/dependency-injection.md -- Service Container, contextual binding, interface binding
• references/testing.md -- Feature/Unit tests, Pest, factories, mocking, database testing
• references/security.md -- Gates, Policies with Specifications, password hashing, Sanctum, User model separation
• references/queues-advanced.md -- Job middleware, batching, chaining, retry/DLQ, Horizon, unique jobs, CQRS
• references/event-system.md -- Event discovery, queued listeners, subscribers, domain event bridge, testing
• references/infrastructure-components.md -- Cache, HTTP Client, Rate Limiting, Task Scheduling, Locks with DDD ports
• references/antipatterns.md -- God Model, fat controller, Facade abuse, N+1 detection