backend-best-practices

Backend Best Practices

Comprehensive backend development guidelines for API design, database patterns, authentication, error handling, performance, and security. Contains rules prioritized by impact to guide code generation and review.

When to Apply

Reference these guidelines when:

• Writing new API endpoints or controllers
• Designing database schemas or writing queries
• Implementing authentication or authorization logic
• Reviewing backend code for quality or security issues
• Refactoring existing backend code
• Enforcing coding standards across the team

Quick Reference

• artisan-tests-use-command-class - Call $this->artisan(Command::class) instead of string signatures in tests
• console-command-signature-adra-prefix - Artisan command signatures start with adra: and a clear domain segment
• eloquent-eager-load-relationships - Eager load relations with with() / load() to avoid N+1 queries
• eloquent-mass-assignment-protection - Use $fillable / $guarded; never open mass assignment from raw request data
• feature-flag-usage-backend - Gate features behind flags using the correct backend service pattern
• feature-specification-and-tdd-first - Document acceptance criteria, then write failing tests before implementation
• form-request-for-http-validation - Use Form Request classes for non-trivial validation and authorization
• laravel-coding-standards-naming - PSR-12, PascalCase classes, snake_case columns, kebab-case route names
• lean-controller-orchestrates-actions-services - Controllers orchestrate Actions/Services; keep business logic out of HTTP layer for testability
• one-class-per-file - Keep only one class per PHP file for better organization and testability
• openapi-spec-sync-with-api - Update each service’s openapi/openapi.yml when the HTTP contract changes
• phpunit-test-naming-and-groups - Use test_ or @test and stable @group labels for predictable discovery/filtering
• tenant-scoped-test-case-pattern - Extend the service tenant test base (e.g. TenantTestCase) for tenant-bound tests

How to Use

Read individual rule files under rules/ for detailed explanations and code examples (see Quick Reference for slugs).

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Additional context and references