Escapepage/README.md

EscapePage — Online Escape Room

This repository contains a Symfony 7.3 (PHP >= 8.2) application for a collaborative online escape room experience.

• Start here: doc/FILES.md — quick file index.
• Development standards and workflows: doc/CONTRIBUTING.md
• All documentation is located under the doc/ directory.

Getting Started (brief)

• Local machine (no Docker):

  1. Copy .env to .env.local and set database and APP_SECRET.
  2. Install PHP deps: composer install
  3. Create database and run migrations (when present): php bin/console doctrine:database:create --if-not-exists && php bin/console doctrine:migrations:migrate -n
  4. Install/import JS deps: php bin/console importmap:install
  5. Run the server: symfony server:start -d (or your preferred web server)
  6. Run tests: vendor/bin/phpunit

• With Docker:

  1. From docker/: docker compose up -d
  2. Install vendors inside the PHP container:
     • docker compose exec php bash
     • composer install
  3. Initialize DB:
     • php bin/console doctrine:database:create --if-not-exists
     • php bin/console doctrine:migrations:migrate -n
  4. App is at http://localhost:8080

Email (Mailpit in dev, SendGrid for prod)

• Dev: a mailer service (Mailpit) runs in Docker.
  • SMTP DSN in .env: MAILER_DSN=smtp://mailer:1025
  • Mailpit UI: http://localhost:8025
  • Send a test mail: php bin/console app:mail:test you@example.com
• Staging/Prod: use SendGrid.
  • Require package (already in composer): symfony/sendgrid-mailer.
  • Set environment variables (do NOT commit secrets):
    • MAILER_DSN=sendgrid+api://%env(SENDGRID_API_KEY)%
    • SENDGRID_API_KEY=YOUR_REAL_KEY
    • Optional: MAILER_FROM=no-reply@your-domain.tld
  • Alternatively via SMTP (no extra package):
    • MAILER_DSN="smtp://apikey:%env(SENDGRID_API_KEY)%@smtp.sendgrid.net:587?encryption=tls"

Troubleshooting:

• If emails don’t appear in dev, open Mailpit at http://localhost:8025 and verify messages.
• In prod, check logs for HTTP 2xx responses from SendGrid and verify sender domain is verified in SendGrid.

Frontend assets with Webpack Encore

We use Webpack Encore to build and minify JS/CSS from the assets/ directory into public/build/.

Install Node dependencies (on your host machine):

npm install

Common commands:

# One-time dev build
npm run dev

# Watch & rebuild on changes
npm run watch

# Production build (minified, versioned filenames)
npm run build

How it’s wired:

• Entry file: assets/app.js (imports assets/styles/app.css).
• Webpack config: webpack.config.js outputs to public/build/.
• Twig template includes built assets via Encore:
  • In templates/base.html.twig:
    • {{ encore_entry_link_tags('app') }} (CSS)
    • {{ encore_entry_script_tags('app') }} (JS)

Notes:

• The PHP Docker image does not include Node. Run the build commands on your host, or ask to add a Node build container if you prefer fully containerized builds.
• Built files are ignored by git except for public/build/.gitignore to keep the directory.

See doc/CONTRIBUTING.md for code style and more details.