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
• json-resource-use-when-helper - Use $this->when() for conditional keys in JsonResource::toArray()
• laravel-coding-standards-naming - PSR-12, PascalCase classes, snake_case columns, kebab-case route names
• no-unleash-facade-direct - Use FeatureFlag and route middleware, not Unleash facades directly
• 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, add @group, and control FeatureFlag::fake() per scenario
• 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