Escapepage/doc/CONTRIBUTING.md

# Contribution & Code Style Guide

This document is for Junie (and humans) to keep our code style consistent and to quickly find the files we’ll reference during development of the Online Escape Room platform.

Project type: Symfony 7.3, PHP >= 8.5.1, Doctrine ORM 3, Twig, Stimulus (UX), Importmap/Asset Mapper, PHPUnit 11.


## 1. Repository Conventions
- PHP version: 8.5.1+ (composer.json enforces ">=8.5.1").
- Framework: Symfony 7.3.* (see composer.json).
- Architecture: MVC with Controllers in `src/Controller`, Entities in `src/Entity`, Repositories in `src/Repository`, Templates in `templates`.
- Env files: `.env`, `.env.local` (ignored), and environment overrides like `.env.test.local`.
- Routes: annotation/attributes in controllers or YAML/PHP in `config/routes`.
- Documentation location: All documentation must live under the `doc/` directory. New docs requested by the team will be added there.


## 2. Coding Standards

### 2.1 PHP
- Standard: PSR-12 (line length soft cap 120; prefer multi-line for long signatures/arrays).
- Strict types at top of new files: `declare(strict_types=1);`
- Type-hint everything (params, returns, properties). Prefer readonly where applicable.
- Visibility: declare on all properties and methods.
- Exceptions: throw domain-specific exceptions for game logic; do not return null where an exception is appropriate.
- Controllers: keep thin; delegate to services. Use DTOs/Form types to validate input.
- Dependency Injection: constructor injection; avoid container-aware services.
- Naming: Services suffixed with `...Service`, commands with `...Command`, event listeners with `...Listener`/`...Subscriber`.
- Logging: use `Psr\Log\LoggerInterface` where meaningful.

### 2.2 Twig
- Keep templates lean; no heavy logic. Use filters/functions and view models if needed.
- Use `trans` for strings that will be localized.
- Partial templates/components: place in `templates/_partials` or `templates/components`.

### 2.3 JavaScript (Stimulus / vanilla)
- Use ES modules via Importmap/Asset Mapper.
- Controllers in `assets/controllers`. Name as `something_controller.js` following Stimulus conventions.
- Prefer small, focused controllers. Keep DOM queries scoped to controller element.
- Avoid global state; communicate via events or Turbo streams when appropriate.

### 2.4 Styles (CSS/SCSS)
- Keep styles in `assets/styles`. Use BEM naming for classes.
- Prefer CSS variables for theme colors, spacing scale, z-index scale.

### 2.5 YAML / Config
- 2-space indentation, no tabs.
- Use parameters and env vars (`env()`) instead of hardcoding secrets.

### 2.6 Git & Commits
- Branch naming: `feature/<short-name>`, `fix/<short-name>`, `chore/<short-name>`.
- Commit messages:
  - Conventional commits style: `feat: ...`, `fix: ...`, `chore: ...`, `docs: ...`, `test: ...`, `refactor: ...`.
  - First line ≤ 72 chars; add body when needed with rationale.


## 3. Linting, Tests, and Quality

### 3.1 PHP
- Use PHP-CS-Fixer or PHP_CodeSniffer (PHPCS) with PSR-12. If not yet installed, proposed composer scripts (to add later):
  - `composer require --dev friendsofphp/php-cs-fixer`
  - Script: `php-cs-fixer fix --allow-risky=yes`
- Static analysis: PHPStan level 6–8 recommended:
  - `composer require --dev phpstan/phpstan`
  - Run: `vendor/bin/phpstan analyse src tests` (configure `phpstan.neon` later)

### 3.2 Symfony
- Cache and debug:
  - `php bin/console cache:clear`
  - `php bin/console debug:router`
  - `php bin/console debug:container`

### 3.3 Tests
- PHPUnit (already required):
  - Run tests: `vendor/bin/phpunit`
  - Tests location: `tests/`
  - Config: `phpunit.dist.xml`

### 3.4 Frontend
- Stimulus/UX: controllers auto-registered via `symfony/stimulus-bundle`.
- Asset Mapper/Importmap:
  - Install deps: `php bin/console importmap:install`
  - Dev server (if using symfony local server): `symfony server:start -d`


## 4. Project File Map (Quick Reference)
- App kernel: `src/Kernel.php`
- Controllers: `src/Controller/`
- Domain entities: `src/Entity/`
- Repositories: `src/Repository/`
- Migrations: `migrations/`
- Templates: `templates/`
- Translations: `translations/`
- Assets entry: `assets/app.js`, styles in `assets/styles/`
- Stimulus controllers: `assets/controllers/`
- Routes: `config/routes/`
- Packages config: `config/packages/`
- Env vars: `.env` (base), `.env.local` (local overrides)
- Public web root: `public/`
- Tests: `tests/`


## 5. How We Build Features (Checklist)
1) Create branch: `feature/<name>`.
2) Describe the task in an issue with acceptance criteria.
3) Implement backend (entities/services/controllers) with tests.
4) Implement templates and Stimulus controller if interactive.
5) Add/adjust routes and translations.
6) Run: linters, phpstan, phpunit; ensure green.
7) Open PR; request review.


## 6. Escape Room Domain Notes (early)
- Core concepts likely: Game, Room, Puzzle, Session, Player, Team, Hint, Timer.
- Consider events (Domain Events) for puzzle solved, hint requested, time warnings.
- Real-time collaboration options: Symfony Mercure, WebSockets, or Turbo Streams.
- Persist immutable audit trail for gameplay.


## 7. Editor Configuration
- Recommend EditorConfig. If we add `.editorconfig` later, set:
  - Indent 4 spaces for PHP, 2 for YAML/Twig/JS/CSS.
  - LF line endings, UTF-8, insert final newline, trim trailing whitespace.


## 8. Security & Secrets
- Never commit secrets. Use environment variables or Symfony Vault.
- Review `APP_ENV`, `APP_SECRET`, database DSN in `.env` and `.env.local`.


## 9. Release & Environments
- Envs: `dev`, `test`, `prod`.
- Build steps: run migrations, warmup cache, compile assets if using.


## 10. References
- Symfony Best Practices: https://symfony.com/doc/current/best_practices.html
- Doctrine ORM 3 Docs: https://www.doctrine-project.org/projects/doctrine-orm/en/current/
- Stimulus: https://stimulus.hotwired.dev/