Frank/Escapepage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Startup

Browse Source
This commit is contained in:
Frank
2026-01-02 20:27:56 +01:00
parent 534175efb3
commit 0d6628e7c9
45 changed files with 12279 additions and 2911 deletions
Download Patch File Download Diff File Expand all files Collapse all files

138
doc/CONTRIBUTING.md Normal file
View File

@@ -0,0 +1,138 @@
# 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.2, Doctrine ORM 3, Twig, Stimulus (UX), Importmap/Asset Mapper, PHPUnit 11.
## 1. Repository Conventions
- PHP version: 8.2+ (composer.json enforces ">=8.2").
- 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/

51
doc/FILES.md Normal file
View File

@@ -0,0 +1,51 @@
# Project File Index (Quick Reference)
Use this index to quickly locate files and directories during development and in discussions.
## Top-Level
- docker/compose.yaml / docker/compose.override.yaml — Docker services.
- docker/ — Docker build contexts and configs (php Dockerfile, nginx vhost, compose files).
- composer.json / composer.lock — Dependencies and scripts.
- importmap.php — Importmap configuration for JS dependencies.
- phpunit.dist.xml — PHPUnit configuration.
- public/ — Web root (index.php, assets, static files).
- var/ — Cache and logs.
- vendor/ — Composer dependencies.
## Application Source (src/)
- src/Kernel.php — Symfony Kernel bootstrapping.
- src/Website/ — Marketing/public website area (controllers, templates under templates/website/).
- src/Game/ — Game area (controllers, templates under templates/game/).
- src/Entity/ — Doctrine ORM entities.
- src/Repository/ — Doctrine repositories.
## Configuration (config/)
- config/packages/ — Symfony bundles configuration (framework.yaml, cache.yaml, etc.).
- config/routes/ — Routing configuration files.
- config/routes/app.yaml — Imports attribute routes for both sites (Website and Game).
## Data & DB
- migrations/ — Doctrine migrations.
## Presentation
- templates/ — Twig templates.
- templates/website — Views for the public website.
- templates/game — Views for the game area.
- translations/ — i18n message files.
## Frontend Assets
- assets/app.js — Main JS entry (imports Stimulus, styles, etc.).
- assets/controllers/ — Stimulus controllers.
- assets/styles/ — Global styles.
- assets/vendor/ — Vendor frontend assets if any.
## Tests
- tests/ — Test suites for PHPUnit.
## Environment
- .env — Base environment configuration.
- .env.local — Local overrides (ignored).
## Notes
- Follow doc/CONTRIBUTING.md for code style and workflows.
- Email setup: see doc/email.md for dev Mailpit and production SendGrid configuration.

10
doc/README.md Normal file
View File

@@ -0,0 +1,10 @@
# Project Documentation
This directory contains all project documentation for EscapePage.
- Code Style & Contribution Guide: CONTRIBUTING.md
- Project File Index: FILES.md
Policy: All new and existing documentation must be placed in this doc/ directory. If you ask Junie to add docs in the future, they will be created under doc/.
Additional docs can be added here as the project grows (architecture decisions, API docs, gameplay design, onboarding, etc.).

60
doc/docker.md Normal file
View File

@@ -0,0 +1,60 @@
# Docker Setup
This app can run fully in Docker using docker compose with PHP-FPM, Nginx and MySQL.
## Services
- php: PHP 8.2 FPM with required extensions and Composer
- nginx: Serves the Symfony app from public/ and proxies PHP to php-fpm
- database: MySQL 8.0 (data persisted in a volume)
- mailer (dev only via compose.override.yaml): Mailpit (SMTP/UI)
## Prerequisites
- Docker and Docker Compose (v2)
## Usage
### 1) Build and start
```
./docker/setup.sh
```
App will be served at http://localhost:8080
Alternatively (manual):
```
docker compose -f docker/compose.yaml -f docker/compose.override.yaml up -d --build
```
### 2) Install dependencies
The setup script already runs composer install. To run manually:
```
docker compose -f docker/compose.yaml -f docker/compose.override.yaml exec php composer install
```
### 3) Prepare DB
The setup script already prepares the DB. To run manually:
```
docker compose -f docker/compose.yaml -f docker/compose.override.yaml exec php php bin/console doctrine:database:create --if-not-exists
docker compose -f docker/compose.yaml -f docker/compose.override.yaml exec php php bin/console doctrine:migrations:migrate -n
```
### 4) Run tests
```
docker compose -f docker/compose.yaml -f docker/compose.override.yaml exec php vendor/bin/phpunit
```
### 5) Logs
```
docker compose -f docker/compose.yaml -f docker/compose.override.yaml logs -f nginx
docker compose -f docker/compose.yaml -f docker/compose.override.yaml logs -f php
```
### 6) Stop
```
docker compose -f docker/compose.yaml -f docker/compose.override.yaml down
```
## Notes
- .env already points DATABASE_URL to the `database` service hostname.
- Nginx listens on port 8080 (mapped from container 80) to avoid conflicts.
- Source is bind-mounted; changes on host reflect inside containers.
- For production images, create a separate Dockerfile with build steps (composer install --no-dev, cache warmup) and avoid bind mounts.

45
doc/email.md Normal file
View File

@@ -0,0 +1,45 @@
# Email Delivery: Dev Mailcatcher & Production SendGrid
This application uses Symfony Mailer. We separate development and production delivery:
- Development: Mailpit (mailcatcher) via SMTP in Docker.
- Production: SendGrid via API transport.
## Development (Mailpit)
- Service is defined in `compose.override.yaml` as `mailer` (axllent/mailpit).
- Ports:
- SMTP: 1025 (mapped to host 1025)
- Web UI: 8025 (mapped to host 8025)
- Default DSN for dev is set in `.env`:
```
MAILER_DSN=smtp://mailer:1025
```
- Usage:
1. Start stack: `docker compose up -d`
2. Send an email from the app.
3. Open http://localhost:8025 to view captured emails.
## Production (SendGrid)
Use the SendGrid API transport. Do not commit secrets.
- Example configuration is in `.env.prod`:
```
MAILER_DSN=sendgrid+api://%env(resolve:SENDGRID_API_KEY)%@default
```
- Provide `SENDGRID_API_KEY` via:
- Real environment variable on the server/container, or
- Symfony secrets: `php bin/console secrets:set SENDGRID_API_KEY` (and dump for prod), or
- Orchestration secret stores (e.g., Docker/K8s).
### Notes
- No Mailpit container is defined in the base `compose.yaml`, only in `compose.override.yaml`. This ensures it is used in development only.
- To test email locally without Docker, you can:
- Run Mailpit on your host (ports 1025/8025) and set `MAILER_DSN=smtp://127.0.0.1:1025` in `.env.local`.
- If you need to use SendGrid SMTP instead of API, a DSN example:
`smtp://apikey:YOUR_SENDGRID_API_KEY@smtp.sendgrid.net:587`.