# PHP Rules

PHP development rules for portable, maintainable code.

## Code Style

- Follow PSR-12 coding standard
- Use PHP-CS-Fixer or Laravel Pint for formatting
- All new files must have `<?php` opening tag (no short tags `<?`)
- Use typed properties where possible: `private string $name;`
- Use strict types: `declare(strict_types=1);`

## Naming

- Classes: `PascalCase`
- Methods/functions: `camelCase`
- Constants: `SCREAMING_SNAKE_CASE`
- Database tables: `snake_case`
- Columns: `snake_case`

## Functions and Methods

- Maximum function length: ~40 lines
- Maximum parameters: ~4 (use DTOs for more)
- Never use `extract()` — security risk
- Never use `eval()` — security risk
- Never use `global` — use dependency injection

## Type Safety

- Declare return types on all public methods
- Use nullable types intentionally: `?string $name`
- Use `void` return type for methods that don't return
- Prefer `string` over `String`, `int` over `Integer` (lowercase scalar types)

## Error Handling

- Never suppress errors: `@`
- Use exceptions for exceptional cases
- Catch specific exceptions: `catch (InvalidArgumentException $e)`
- Never expose stack traces or internal errors to end users

## SQL and Database

- Use parameterized queries exclusively (never string interpolation)
- Use transactions for multi-step operations
- All SQL must be portable: works on SQLite, MariaDB, PostgreSQL
- See `database.md` for full portability rules

## Composer

- Run `composer validate` before committing `composer.json`
- Lock versions in `composer.lock` (commit it)
- No dev dependencies in production deployment

## Testing

- PHPUnit or Pest for unit/integration tests
- Test one thing per test method
- Use data providers for multiple test cases
- Mock external dependencies (database, APIs)

## Files

- One class per file
- File name matches class name: `UserRepository.php` contains `class UserRepository`
- No code outside of classes/functions (except config/bootstrap)