Coding standards

​

Language & tooling

• PHP 8.3 (composer.json requires ^8.3). Use modern language features: native backed enums, readonly properties, constructor promotion, first-class attributes.
• Add declare(strict_types=1); at the top of every new file. The codebase is mid-migration (not all legacy files have it yet), so new code should always opt in.
• Quality gates run in CI; the per-file diff scripts let you check only what you changed:
  • bin/phpstan-diff.sh — PHPStan on changed files
  • bin/phpcs-diff.sh — code style on changed files
  • bin/static.sh — combined static analysis

​

Coding style

• Follow PSR-12 plus the Symfony (risky) ruleset.
• Style is enforced by PHP-CS-Fixer (.php-cs-fixer.dist.php) and Easy Coding Standard (ECS). Auto-fix before committing:
  vendor/bin/ecs check src --fix
  
• House conventions baked into the fixer config: short array syntax ([]), ordered class elements, strict comparison (===), Yoda style for equality checks, and no arrow functions. Don’t hand-format — let the fixer decide.

​

Static analysis

• We run PHPStan (with phpstan-symfony + bleeding-edge rules) on every PR; config is phpstan.neon.
• Newer files must pass at PHPStan level 4 as a hard minimum. Level 8 is the project goal — the config targets it — so aim as high as you can and raise the level on a file as it’s cleaned up. Never lower the bar on a file that already passes higher.
• Migrations, the Kernel, and third-party bundles are excluded from analysis.

​

Project structure & conventions

• Keep controllers thin; put business logic in services.
• TODO: namespacing and naming conventions.

​

Modules

src/
  Raffle/
    config/
      services.yaml      # services for this module
      packages.yaml      # package config for this module
    Controller/
    Entity/
    Service/
    ...

• Don’t depend on another module’s entities, repositories, or internal services directly — go through its facade where one makes sense.
• A facade is the seam we can keep stable while a module’s internals change.

​

Services & dependency injection

• Prefer constructor injection and autowiring.
• TODO: conventions for service naming, tags, and configuration.

​

Doctrine: connections, entities & migrations

​

Entity conventions

• Put a new entity in the directory for the database it belongs to, matching the mapping prefix above — that determines which entity manager and connection it uses.
• Mapping is attribute-based with the underscore naming strategy.
• An entity belongs to exactly one connection. Do not query across connections in a single query / join across databases — coordinate at the service layer (or via a module facade) instead.
• When injecting an entity manager or repository, make sure you get the one for the right connection (the draw EM is the default).

​

Migrations

bin/db_diff      # generate migrations for all four DBs (one per namespace)
bin/db_migrate   # apply pending migrations across all four DBs

• Never edit a committed migration; create a new one.
• Clean up generated migrations: remove the auto-generated boilerplate Doctrine leaves behind — the // this up()/down() migration is auto-generated... comments, leftover @todo placeholders, and any empty down() scaffolding — and keep only the SQL you actually mean to run.
• Always provide a meaningful getDescription() so the migration is self-documenting in the migrations list.
• Migrations use a custom factory (App\Doctrine\Migrations\DoctrineAwareMigrationFactory), so migrations can be services and use dependency injection where needed.

​

API conventions

• Routing & docs: declare routes with the #[Route] attribute and document endpoints with Nelmio / OpenAPI attributes (#[OA\Get], #[OA\Parameter], #[OA\Response], #[Security]). Keep the OpenAPI annotations accurate — they are the published API docs.
• Serialization: new modules use the Symfony Serializer (with serialization groups / #[Groups] to control exposed fields). JMS Serializer is legacy — only use it in existing endpoints that already depend on it, and only when there’s a concrete reason to (e.g. matching the existing behaviour of that endpoint). Don’t reach for JMS in new code.
• Validation: validate input with the Symfony Validator (constraints on request DTOs/models in src/App/Model) or Symfony Form types for complex requests.
• Errors: throw from the App\Exception hierarchy (ApiException, ApiFormException, ApiDetailedException, …); ApiExceptionSubscriber turns them into the standard JSON shape — {"message": "...", "apiCode": "...", "quantity": ...} (or {"errors": {...}} for form errors). Don’t build error responses ad hoc.
• Auth: session-based authentication is the default; OAuth (HWIOAuthBundle) for social login; JWT (Authorization: Bearer …) is used by the iGaming module. Guard endpoints with #[IsGranted] / voters.
• Caching: mark cacheable endpoints with the custom #[CachedEndpoint] attribute (ttl, includeUserContext, warmup).

​

Encryption of sensitive data

• Store PII / secrets with the custom encrypted_data Doctrine type, which encrypts on write and decrypts on read via the App\Security\Crypto service. Use it for sensitive columns instead of storing plaintext.

​

Testing

• Cover the meaningful branches and edge cases (zero, negative, empty, boundary values), not just the happy path.
• Keep unit tests fast and free of I/O; use functional tests for HTTP/database integration.

• Tests live in tests/ (module-scoped suites also exist, e.g. src/IGaming/tests, src/Rng/tests). Name test classes *Test.php and data-provider methods provider*.
• Tag tests with @group unit / @group integration.
• Build test state with Zenstruck Foundry factories (tests/Factory) and Stories (tests/Story) rather than hand-rolled fixtures.
• The DAMA Doctrine Test Bundle wraps each test in a transaction for isolation — don’t rely on leftover data between tests.

​

Async & messaging

• Asynchronous work currently runs through RabbitMQ via OldSoundRabbitMqBundle (producers publish, consumer classes handle messages). We do not use Symfony Messenger yet.
• Run consumers with the bin/run_consumers_* scripts; scheduled work runs through the cron runner (php bin/console app:cron:run).
• For high-volume work, prefer batch consumers over one-message-at-a-time processing.

​

Design principles & good practices

• SOLID — single responsibility, open/closed, Liskov substitution, interface segregation, dependency inversion.
• PHP-FIG PSRs — follow the relevant standards, especially PSR-1 / PSR-12 (coding style), PSR-4 (autoloading), and PSR-3 (logging).
• HTTP semantics — follow RFC 9110 for methods and status codes, and return errors as RFC 9457 Problem Details.
• Dates & times — serialize and store using ISO 8601; store in UTC.
• Prefer composition over inheritance, keep functions small and single-purpose, and avoid premature abstraction (YAGNI / DRY in moderation).

​

Code hygiene

• Remove unnecessary comments. Code should be self-explanatory; comment the why, not the what. Delete commented-out code and auto-generated placeholder comments.
• Use early returns / guard clauses instead of deep nesting — handle edge cases up front and let the happy path read top to bottom.
• Leave it nicer than you found it. Aim for clean, readable code: clear names, small methods, and a sensible shape. If a change makes a file harder to read, rethink it.