Development Best Practices

Coding Standards

All code must follow the Laravel coding style, which is based on PSR-12 with Laravel-specific conventions. We enforce these standards through automated tooling in CI/CD pipelines.

• PSR-12: Follow PSR-12 extended coding style guide as the baseline for all PHP code.
• Laravel Naming Conventions: Use camelCase for methods and variables, PascalCase for classes, snake_case for database columns and configuration keys.
• Type Hints: Use PHP type hints for all function parameters and return types. Leverage PHP 8.1+ features like enums, readonly properties, and first-class callables.
• Docblocks: Use PHPDoc only where necessary to describe non-obvious behavior. Prefer expressive code and type hints over documentation.
• Static Analysis: All code must pass PHPStan at level 6 or higher without errors. Larastan is the preferred static analysis tool.

Architecture Guidelines

We follow Laravel's intended architecture patterns to keep applications maintainable and testable.

• Fat Models, Skinny Controllers: Keep controllers thin. Business logic belongs in models, actions, services, or form requests.
• Service Layer: Extract complex business logic into dedicated service classes. Keep them stateless and inject dependencies via constructor.
• Action Classes: For single-purpose operations, use invokable action classes. This keeps each unit of work focused and testable.
• Repository Pattern: Use repositories only when you need to abstract data access for testing or multi-storage scenarios. For most CRUD, use Eloquent directly.
• Dependency Injection: Rely on Laravel's service container. Avoid facades and the app() helper in constructors; use proper constructor injection.
• DTOs & Data Objects: Use typed data transfer objects for passing data between layers. Prefer readonly properties and named arguments.

Testing Standards

Every feature must be covered by automated tests. We use Pest PHP as our primary testing framework.

• Test Coverage: Aim for at least 90% code coverage. Critical paths (auth, payments, data integrity) must have 100% coverage.
• Feature Tests: Write feature tests for every HTTP endpoint covering success, validation, authorization, and failure scenarios.
• Unit Tests: Unit test all service classes, actions, and DTOs. Mock external dependencies to keep tests fast and isolated.
• Database Tests: Use SQLite in-memory for fast test execution. Seed only the data needed for each test case.
• Browser Tests: Use Laravel Dusk for testing critical user journeys that involve JavaScript, such as checkout flows and file uploads.

Database Best Practices

• Migrations: Write reversible migrations. Never modify published migrations; create a new one for schema changes.
• Indexing: Add database indexes for all columns used in WHERE, JOIN, ORDER BY, and GROUP BY clauses. Use compound indexes for multi-column queries.
• N+1 Prevention: Eager-load relationships with with(). Use lazy loading only when explicitly needed. Monitor query logs in development.
• Raw SQL: Avoid raw SQL in application code. Use Eloquent and the query builder. If raw SQL is unavoidable, use prepared statements.
• Soft Deletes: Use soft deletes by default unless data retention policies require hard deletion. Always index the deleted_at column.

Security Guidelines

• Input Validation: Always validate incoming data using Form Requests. Never trust user input even if it comes from authenticated sources.
• Authorization: Use gates and policies for all authorization checks. Apply them in controllers, not in views or routes.
• SQL Injection: Never concatenate user input into SQL queries. Eloquent and the query builder handle parameter binding automatically.
• XSS Prevention: Use Blade's {{ }} syntax which automatically escapes output. Use {!! !!} only when deliberately rendering trusted HTML.
• CSRF: All state-changing requests must include CSRF tokens. Use @csrf in Blade forms and include X-XSRF-TOKEN headers in API requests.
• Rate Limiting: Apply rate limiting to all public API routes and authentication endpoints to prevent abuse.

Code Review Process

All code changes must go through peer review before being merged into the main branch.

1. Create a Pull Request: Open a PR with a descriptive title and summary of changes. Reference the related issue or ticket.
2. Automated Checks: CI must pass all checks including tests, static analysis (PHPStan), linting (Pint), and type checking before review.
3. Peer Review: At least one senior developer must review the code. Reviewers check for correctness, security, performance, test coverage, and adherence to these guidelines.
4. Address Feedback: The author should address all review comments. Use fixup commits during review and squash before merge.
5. Merge: Squash-merge all commits into main with a clean commit message. Delete the feature branch after merging.

Deployment Guidelines

• CI/CD Pipeline: All deployments go through automated CI/CD pipelines. Manual deployments are strictly prohibited for production environments.
• Environment Separation: Maintain separate environments for development, staging, and production. Each must have its own database and configuration.
• Deploy Script: Run migrations before releasing new code. Use Laravel's deployment commands: php artisan up / down, php artisan optimize, and cache clearing.
• Health Checks: Implement health check endpoints that verify database connectivity, queue workers, cache, and third-party service availability.
• Monitoring: Set up application monitoring (error tracking, performance metrics, log aggregation) before the first production deployment.
• Rollback Plan: Every deployment must have a documented rollback strategy. Keep the previous release artifact available for at least 48 hours.