# Laravel Idioms and Patterns

URL: https://mechcrate.dev/docs/corpus/patterns/appendix-laravel/
Source: docs/development/appendix-laravel.md

---

Appendix B: Laravel Idioms and Patterns

Purpose
Laravel with a functional bias: pure domain, explicit ports, Eloquent at the edge.

B1. Project Shape
	•	app/Domain/* for value objects, DTOs, services, ports (interfaces).
	•	app/Infra/* for Eloquent repositories, HTTP clients, mappers.
	•	app/App/* for controllers, jobs, events, listeners.

B2. Domain Modeling
	•	Backed enums for finite states; value objects for constrained primitives.
	•	DTOs are immutable transport within the domain layer.
	•	No Eloquent models inside Domain.

B3. Ports and Adapters
	•	Define ports in Domain/Ports.
	•	Implement with Eloquent or external clients in Infra.
	•	Keep mappers translating between DB/HTTP payloads and domain DTOs.

B4. Error and Result Handling
	•	Prefer Result-like wrappers or explicit return objects instead of throwing internally.
	•	Convert exceptions at edges (controllers, jobs) into HTTP responses or retries.

B5. Validation & Decoding
	•	Form Requests validate and map inputs to simple DTO arrays.
	•	Edge decoders only; domain receives already-validated values.

B6. Testing
	•	Feature tests for controllers and routes.
	•	Unit tests for domain services and value objects.
	•	Contract tests for adapters using fakes or sqlite/in-memory strategies.
	•	Property tests for core invariants where practical.

B7. Quality Gates
	•	Static analysis (Larastan), formatter (Pint), security advisories.
	•	CI runs: analyze, format check, tests with coverage, migration check.

B8. Observability
	•	Structured logging for transitions and domain events.
	•	Metrics via counters and timers; include queue latency and retries.
	•	Correlation IDs threaded through requests and jobs.

B9. File Map (placeholders to fill later)
	•	app/Domain/Value/*
	•	app/Domain/Dto/*
	•	app/Domain/Services/*
	•	app/Domain/Ports/*
	•	app/Infra/Repos/*
	•	app/Infra/Clients/*
	•	app/Http/Controllers/*
	•	app/Http/Requests/*
	•	tests/Unit/*, tests/Feature/*

B10. When to add code
	•	After a brief transition table or ADR exists for the workflow.
	•	Keep all code demonstrations here under clear headings when you’re ready.

B11. Design Principles Ctd
        •       Modular monolith with bounded contexts (modules/packages); queues with outbox table (DB or Kafka); Horizon + idempotency middleware; Temporal via PHP SDK or run worker services in another lang and call via gRPC; events for projections; policy classes backed by OPA/Cedar if you need ABAC.