laravel

Laravel PHP framework — Eloquent ORM, Blade templates, middleware, queues, and Sanctum auth.

SKILL.md

GitHub

Laravel Patterns & Best Practices

Purpose

Provide expert guidance on Laravel application architecture, Eloquent ORM patterns, queue management, API development, and production-grade configuration. Covers Laravel 11+ with its streamlined application structure.

Key Patterns

Project Structure (Laravel 11+)

Laravel 11 simplifies the directory structure:

app/
├── Http/
│   ├── Controllers/
│   ├── Middleware/
│   └── Requests/          # Form request validation
├── Models/
├── Services/              # Business logic (custom)
├── Actions/               # Single-purpose action classes (custom)
├── Events/
├── Listeners/
├── Jobs/
├── Policies/
├── Enums/
└── Providers/
database/
├── migrations/
├── seeders/
└── factories/
routes/
├── api.php
└── web.php

Eloquent Models

Model with relationships, scopes, and casts:

class Order extends Model
{
    use HasFactory, SoftDeletes;

    protected $fillable = [
        'user_id',
        'status',
        'notes',
        'total_cents',
    ];

    protected function casts(): array
    {
        return [
            'status' => OrderStatus::class,      // Backed enum
            'total_cents' => 'integer',
            'shipped_at' => 'immutable_datetime',
        ];
    }

    // Relationships
    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }

    public function items(): HasMany
    {
        return $this->hasMany(OrderItem::class);
    }

    public function tags(): BelongsToMany
    {
        return $this->belongsToMany(Tag::class)->withTimestamps();
    }

    // Scopes
    public function scopeCompleted(Builder $query): Builder
    {
        return $query->where('status', OrderStatus::Completed);
    }

    public function scopeRecent(Builder $query, int $days = 30): Builder
    {
        return $query->where('created_at', '>=', now()->subDays($days));
    }

    // Accessors
    protected function totalFormatted(): Attribute
    {
        return Attribute::make(
            get: fn () => number_format($this->total_cents / 100, 2),
        );
    }
}

Backed enum for status fields:

enum OrderStatus: string
{
    case Draft = 'draft';
    case Pending = 'pending';
    case Processing = 'processing';
    case Completed = 'completed';
    case Cancelled = 'cancelled';

    public function label(): string
    {
        return match ($this) {
            self::Draft => 'Draft',
            self::Pending => 'Pending Payment',
            self::Processing => 'Processing',
            self::Completed => 'Completed',
            self::Cancelled => 'Cancelled',
        };
    }

    public function canTransitionTo(self $next): bool
    {
        return match ($this) {
            self::Draft => in_array($next, [self::Pending, self::Cancelled]),
            self::Pending => in_array($next, [self::Processing, self::Cancelled]),
            self::Processing => in_array($next, [self::Completed, self::Cancelled]),
            default => false,
        };
    }
}

Controllers

API Resource Controller with Form Requests:

class OrderController extends Controller
{
    public function __construct(
        private readonly OrderService $orderService,
    ) {}

    public function index(Request $request): AnonymousResourceCollection
    {
        $orders = Order::query()
            ->with(['user:id,name', 'items.product:id,name,price_cents'])
            ->when($request->status, fn ($q, $status) => $q->where('status', $status))
            ->when($request->search, fn ($q, $search) => $q->whereHas('user', fn ($q) =>
                $q->where('name', 'ilike', "%{$search}%")
            ))
            ->latest()
            ->paginate($request->integer('per_page', 20));

        return OrderResource::collection($orders);
    }

    public function store(StoreOrderRequest $request): JsonResponse
    {
        $order = $this->orderService->create($request->validated());

        return OrderResource::make($order)
            ->response()
            ->setStatusCode(201);
    }

    public function show(Order $order): OrderResource
    {
        $order->load(['items.product', 'user']);
        return OrderResource::make($order);
    }

    public function update(UpdateOrderRequest $request, Order $order): OrderResource
    {
        $order = $this->orderService->update($order, $request->validated());
        return OrderResource::make($order);
    }

    public function destroy(Order $order): Response
    {
        $this->authorize('delete', $order);
        $order->delete();
        return response()->noContent();
    }
}

Form Request Validation:

class StoreOrderRequest extends FormRequest
{
    public function authorize(): bool
    {
        return true;
    }

    public function rules(): array
    {
        return [
            'items' => ['required', 'array', 'min:1'],
            'items.*.product_id' => ['required', 'exists:products,id'],
            'items.*.quantity' => ['required', 'integer', 'min:1', 'max:100'],
            'notes' => ['nullable', 'string', 'max:1000'],
            'shipping_address_id' => ['required', 'exists:addresses,id'],
        ];
    }

    public function messages(): array
    {
        return [
            'items.required' => 'At least one item is required.',
            'items.*.product_id.exists' => 'Product not found.',
        ];
    }
}

API Resources

class OrderResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'status' => $this->status->value,
            'status_label' => $this->status->label(),
            'total_formatted' => $this->total_formatted,
            'notes' => $this->notes,
            'items' => OrderItemResource::collection($this->whenLoaded('items')),
            'user' => UserResource::make($this->whenLoaded('user')),
            'created_at' => $this->created_at->toISOString(),
            'updated_at' => $this->updated_at->toISOString(),
        ];
    }
}

Queue Jobs

class ProcessOrderJob implements ShouldQueue
{
    use Queueable;

    public int $tries = 3;
    public int $backoff = 60; // seconds
    public int $timeout = 120;

    public function __construct(
        public readonly Order $order,
    ) {}

    public function handle(PaymentGateway $gateway, InventoryService $inventory): void
    {
        DB::transaction(function () use ($gateway, $inventory) {
            $gateway->charge($this->order);
            $inventory->reserve($this->order->items);
            $this->order->update(['status' => OrderStatus::Processing]);
        });

        OrderProcessed::dispatch($this->order);
    }

    public function failed(\Throwable $exception): void
    {
        Log::error('Order processing failed', [
            'order_id' => $this->order->id,
            'error' => $exception->getMessage(),
        ]);

        $this->order->update(['status' => OrderStatus::Draft]);
        Notification::send($this->order->user, new OrderFailedNotification($this->order));
    }

    public function retryUntil(): DateTime
    {
        return now()->addHours(1);
    }
}

Middleware

// Custom rate limiter in AppServiceProvider
RateLimiter::for('api', function (Request $request) {
    return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
});

// Custom middleware
class EnsureJsonResponse
{
    public function handle(Request $request, Closure $next): Response
    {
        $request->headers->set('Accept', 'application/json');
        return $next($request);
    }
}

Migrations

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('orders', function (Blueprint $table) {
            $table->id();
            $table->foreignId('user_id')->constrained()->cascadeOnDelete();
            $table->string('status', 20)->default('draft')->index();
            $table->integer('total_cents')->default(0);
            $table->text('notes')->nullable();
            $table->timestamp('shipped_at')->nullable();
            $table->timestamps();
            $table->softDeletes();

            $table->index(['user_id', 'status']);
            $table->index('created_at');
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('orders');
    }
};

Action Classes

Single-responsibility action classes for complex operations:

class CreateOrderAction
{
    public function __construct(
        private readonly InventoryService $inventory,
    ) {}

    public function execute(User $user, array $data): Order
    {
        return DB::transaction(function () use ($user, $data) {
            $order = $user->orders()->create([
                'status' => OrderStatus::Draft,
                'notes' => $data['notes'] ?? null,
            ]);

            foreach ($data['items'] as $item) {
                $product = Product::findOrFail($item['product_id']);
                $this->inventory->checkAvailability($product, $item['quantity']);

                $order->items()->create([
                    'product_id' => $product->id,
                    'quantity' => $item['quantity'],
                    'price_cents' => $product->price_cents,
                ]);
            }

            $order->update(['total_cents' => $order->items->sum(fn ($i) =>
                $i->price_cents * $i->quantity
            )]);

            return $order->load('items.product');
        });
    }
}

Best Practices

  1. Always eager load relationships — Use with() to prevent N+1 queries. Run DB::enableQueryLog() in development to catch them.
  2. Use Form Requests for validation — Keep controllers thin by extracting validation to dedicated request classes.
  3. Use API Resources for responses — Never return Eloquent models directly. Resources give you a stable API contract.
  4. Use backed enums for status fields — Type-safe, castable, and self-documenting.
  5. Use action classes for complex operations — Single-purpose, testable, reusable business logic.
  6. Queue heavy operations — Email, PDF generation, payment processing, and third-party API calls belong in jobs.
  7. Use database transactions — Wrap multi-step writes in DB::transaction().
  8. Index foreign keys and frequently filtered columns — Laravel does not auto-index foreignId columns in all cases.
  9. Use chunk() or lazy() for large datasets — Never load thousands of models into memory at once.
  10. Cache configuration in production — Run php artisan config:cache, route:cache, and view:cache on deploy.

Common Pitfalls

Pitfall Problem Fix
N+1 queries Accessing relationships in loops without eager loading Use with() or load()
Mass assignment vulnerability Filling unguarded attributes Define $fillable or $guarded
Missing queue worker restart Workers cache old code after deploy Use php artisan queue:restart in deploy script
Fat controllers Business logic in controllers Extract to service/action classes
No transaction wrapping Partial writes on failure Wrap in DB::transaction()
Returning models from API Exposing internal structure, passwords Use API Resources
Synchronous heavy tasks Slow response times Dispatch to queues
Missing database indexes Slow queries at scale Add composite indexes for common query patterns