onstruct( private readonly PDO $connection ) {}

public function findByEmail(string $email): ?array
{
    $statement = $this->connection->prepare(
        'SELECT id, email, password_hash, status FROM users WHERE email = :email'
    );
    
    $statement->execute(['email' => $email]);
    $result = $statement->fetch(PDO::FETCH_ASSOC);
    
    return $result === false ? null : $result;
}

}

**Why this works:** PDO with named placeholders eliminates SQL injection vectors. Wrapping database access in a repository isolates infrastructure concerns from domain logic. AI must be explicitly prohibited from generating raw string interpolation in queries, `mysql_*`/`mysqli_*` procedural calls, or direct PDO usage in controllers. Password hashing must default to `PASSWORD_ARGON2ID`, and all output rendering must enforce `htmlspecialchars` with `ENT_QUOTES` and `UTF-8` encoding.

## Pitfall Guide

Even with constraint files, AI can drift into anti-patterns if rules are ambiguous or incomplete. The following pitfalls represent the most frequent failure modes observed in production environments.

### 1. `mixed` Type Leakage at Boundaries
**Explanation:** Developers allow AI to use `mixed` for API payloads or serialization inputs, assuming it simplifies handling. This defeats PHP's type system and pushes validation downstream.
**Fix:** Define explicit DTOs or typed arrays with validation layers. Use `array{key: type}` syntax for structured payloads. Reserve `mixed` only for true serialization boundaries where structure is unknown.

### 2. Mocking Internal Implementation Details
**Explanation:** AI generates tests that mock internal methods or private properties, creating fragile test suites that break during refactoring.
**Fix:** Constrain AI to mock only external boundaries (databases, HTTP clients, filesystem, third-party APIs). Internal logic should be tested through public interfaces using real implementations.

### 3. Mutable Date/Time Objects
**Explanation:** AI defaults to `\DateTime` because it appears frequently in legacy code. Mutable date objects cause subtle bugs when passed by reference across services.
**Fix:** Enforce `\DateTimeImmutable` exclusively. Any date manipulation must return a new instance, preserving referential transparency.

### 4. Static State Masquerading as Utility
**Explanation:** AI generates static methods for business logic, claiming they are "stateless utilities." These methods create hidden coupling and prevent dependency injection.
**Fix:** Restrict `static` to pure mathematical or string manipulation functions with zero side effects. All domain logic must reside in instantiable classes with explicit dependencies.

### 5. Security Assumption Gaps
**Explanation:** AI assumes frameworks handle CSRF, escaping, and session management automatically. In custom or lightweight setups, this leaves critical vulnerabilities exposed.
**Fix:** Explicitly mandate CSRF token validation on all state-mutating routes, server-side MIME validation for uploads, and session ID regeneration after authentication events.

### 6. Dependency Rot & Unvetted Packages
**Explanation:** AI suggests packages based on popularity rather than maintenance status, introducing abandoned or vulnerable dependencies.
**Fix:** Integrate `composer audit` into CI pipelines. Require AI to verify package maintenance status on Packagist before suggesting new dependencies. Lock PHP version constraints in `composer.json`.

### 7. Unstructured Logging & Sensitive Data Exposure
**Explanation:** AI generates `error_log()` calls or concatenates variables into log messages, creating unsearchable logs and potential data leaks.
**Fix:** Enforce PSR-3 logger interfaces with context arrays. Implement automatic masking for PII, tokens, and financial data before logging. Prefer JSON-structured output for aggregation platforms.

## Production Bundle

### Action Checklist
- [ ] Initialize project constraint file: Create `AI_CODING_STANDARDS.md` at repository root with explicit PHP 8.2+ requirements
- [ ] Enforce strict typing: Mandate `declare(strict_types=1);` in all generated files, including tests and scripts
- [ ] Configure type boundaries: Replace `mixed` with explicit DTOs, union types, or typed array syntax
- [ ] Isolate database access: Require PDO prepared statements wrapped in repository classes; prohibit raw interpolation
- [ ] Implement constructor injection: Ban static business logic, service locators, and `new` instantiation inside methods
- [ ] Harden security defaults: Enforce `htmlspecialchars`, `PASSWORD_ARGON2ID`, CSRF validation, and session regeneration
- [ ] Standardize observability: Require PSR-3 logging with context arrays, structured JSON output, and PII masking
- [ ] Validate dependencies: Run `composer audit` in CI; lock PHP version; separate `require` and `require-dev`

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Greenfield PHP 8.2+ project | Full constraint manifest with strict typing, readonly DTOs, constructor DI | Prevents legacy drift from day one; maximizes testability and refactoring velocity | Low initial setup; high long-term ROI |
| Legacy PHP 7.x migration | Gradual constraint rollout; prioritize strict types and PDO migration first | Reduces risk of breaking existing workflows while modernizing critical paths | Medium setup; phased cost distribution |
| High-security financial system | Enforce immutable value objects, PSR-3 context logging, explicit CSRF/escaping, `composer audit` gates | Minimizes attack surface; ensures auditability and compliance | Higher initial overhead; prevents catastrophic breach costs |
| Internal tooling / MVP | Relaxed typing with union types, basic repository pattern, standard PHPUnit | Accelerates delivery while maintaining testability and security baselines | Low setup; acceptable technical debt for speed |

### Configuration Template

```markdown
# AI Coding Standards — PHP 8.2+

## Language & Type System
- All files must begin with `declare(strict_types=1);`
- Every function parameter, return type, and class property requires explicit type declarations
- Use union types (`int|string`) and intersection types where applicable
- Avoid `mixed` except at serialization boundaries; prefer typed DTOs or `array{key: type}` syntax
- Use `void` for methods without meaningful returns; use `never` for functions that always throw/exit

## Architecture & Dependencies
- Constructor injection only; no `new` instantiation inside business methods
- No static methods for domain logic; restrict `static` to pure utilities
- No service locators or global state access
- Follow PSR-4 autoloading; one class per file; namespace matches directory structure
- Use Composer for all dependency management; lock PHP version in `composer.json`

## Database & Security
- PDO with prepared statements only; no `mysql_*` or `mysqli_*` procedural APIs
- Never interpolate variables into SQL; use `?` or `:param` placeholders
- Wrap database access in repository classes; controllers must not interact with PDO directly
- Escape all output: `htmlspecialchars($var, ENT_QUOTES, 'UTF-8')`
- Passwords: `password_hash($pass, PASSWORD_ARGON2ID)` + `password_verify()`
- Regenerate session ID after login: `session_regenerate_id(true)`
- Validate file MIME types server-side; never trust client-provided headers
- Require CSRF tokens on all state-mutating routes (POST, PUT, PATCH, DELETE)

## Error Handling & Observability
- Throw domain-specific exceptions extending `\RuntimeException` or `\LogicException`
- No `or die()`, `exit()` for flow control, or `@` error suppression
- Use PSR-3 logger with context arrays; prefer structured JSON output
- Mask sensitive data (tokens, card numbers, passwords) before logging
- Log levels: debug (dev only), info (normal), warning (degraded), error (failure), critical (system down)

## Data Integrity & Immutability
- Use `readonly` classes/properties for value objects and DTOs
- Prefer `\DateTimeImmutable` over mutable `\DateTime`
- Represent monetary values as integer cents; never use floats
- Use `match` expressions over `switch`; leverage nullsafe operator (`?->`)
- Prefer functional array operations (`array_map`, `filter`, `reduce`) over manual loops

## Testing Conventions
- PHPUnit for unit and integration tests
- Mock only external boundaries (database, HTTP, filesystem, third-party APIs)
- Test names must describe behavior: `test_rejects_invalid_email_format()`
- Use data providers for edge cases; avoid copy-pasted test methods
- Assert observable outcomes; never mock internal implementation details

Quick Start Guide

1. Create the constraint file: Place the configuration template above into AI_CODING_STANDARDS.md at your project root. Ensure your AI assistant is configured to read this file before every session.
2. Initialize strict typing: Run a repository-wide search to verify declare(strict_types=1); exists in all PHP files. Configure your IDE or linter to enforce this automatically.
3. Audit dependencies: Execute composer audit and composer validate. Update composer.json to lock "php": "^8.2" and separate production from development dependencies.
4. Validate architecture: Run static analysis (PHPStan/Psalm) at level 5+. Fix any violations related to missing types, static state, or untyped parameters. Iterate until the baseline is clean.
5. Generate & review: Prompt your AI assistant to scaffold a new feature. Review the output against the constraint file. Commit only code that passes type checking, security validation, and test coverage requirements.

By treating AI alignment as an engineering discipline rather than a prompt engineering exercise, teams transform code generation from a source of technical debt into a scalable production multiplier. The constraint file becomes the single source of truth, ensuring every generated line adheres to modern PHP standards without manual intervention.