Maintainable, checked PHP code

PHP Quality

Follow the codebase

• Read composer.json for the PHP version constraint; use only features it allows (enums, readonly, match, named arguments).
• Use the repo's style tool and config (PHP-CS-Fixer, PHPCS, Pint, ECS). Fall back to PSR-12 / PER only when none exists.
• Add declare(strict_types=1); to new files when existing files have it. Do not add it to legacy files as a drive-by: it changes runtime behavior.

Types

• Type every new parameter, return value and property: void, never, nullable ?T and union types where the version allows.
• Avoid mixed and loose arrays at boundaries; document shapes in PHPDoc (list<User>, array<string, int>, array{id: int}) when native types cannot.
• Prefer value objects, enums and readonly properties over magic strings and associative arrays.
• Never use @var or casts to silence the analyzer; fix the type.

Structure

• One class per file, PSR-4 namespaces matching composer.json autoload. No manual require of class files; run composer dump-autoload after changing autoload config.
• Constructor injection for dependencies; depend on interfaces where the repo does. No new-ing services inside methods, no service locators, globals or static state.
• Small single-purpose classes and methods; early returns over deep nesting; final classes if the repo does it.
• Add packages with composer require (or --dev) so composer.lock updates; never edit vendor/.

Errors

• Throw specific exceptions (domain-specific or SPL: InvalidArgumentException, RuntimeException, DomainException) instead of returning false or null for failures.
• No @ error suppression and no empty catch blocks. Catch only what you can handle; rethrow or wrap with the previous exception.
• Check functions that return false on failure; use JSON_THROW_ON_ERROR with json_decode and json_encode.
• Strict comparisons: ===, in_array( ..., true ).

Static analysis

• Run PHPStan or Psalm at the level configured in the repo; your code must add no new errors.
• Do not grow the baseline, add ignoreErrors entries or inline ignore comments to pass. Fix the cause.

Tests

• Use the repo's framework, PHPUnit or Pest, with its structure (tests/Unit, tests/Feature), base classes and helpers.
• Unit-test logic with fakes or mocks only at boundaries; use data providers or datasets for input variations.
• Run vendor/bin/phpunit or vendor/bin/pest (or the composer script) and report the output.

PHP pitfalls

• No eval, extract() on input, variable variables from input, or unserialize() on untrusted data.
• Use password_hash / password_verify, random_bytes / random_int and PDO prepared statements.
• Handle dates with DateTimeImmutable and explicit time zones.

Before you finish

• Types on all new parameters, returns and properties; strict_types consistent with the repo.
• The repo's style tool passes on changed files.
• PHPStan or Psalm reports no new errors, with no new ignores.
• No suppressed errors or silent failures.
• Dependencies injected; autoload updated if needed.
• PHPUnit or Pest tests added and run.