Lootopia - Backend Symfony

Backend API et backoffice pour le projet Lootopia. Ce projet utilise Symfony 8 avec PHP 8.4, MySQL et Docker pour l'environnement de développement.

🚀 Démarrage rapide

Prérequis

• Docker Desktop installé et lancé
• Git

Installation

1. Cloner le projet

git clone <url-du-repo>
cd lootopia

2. Lancer l'environnement de développement

make up

3. Accéder à l'application

• Application principale : http://localhost:8080
• API (documentation interactive) : http://localhost:8080/api
• Mailhog (emails de test) : http://localhost:8025

📁 Structure du projet

lootopia/
├── docker/                     # Configuration Docker
│   ├── Dockerfile              # Image PHP-FPM multi-stage (dev/prod)
│   ├── nginx/                  # Configuration Nginx
│   └── php/                    # Configuration PHP (dev/prod)
├── src/
│   ├── ApiResource/            # Ressources API Platform
│   ├── Controller/             # Contrôleurs Symfony
│   ├── Entity/                 # Entités Doctrine
│   ├── Repository/             # Repositories Doctrine
│   └── Service/                # Services métier
├── docker-compose.yml          # Configuration dev (php, nginx, mysql, mailhog)
└── docker-compose.prod.yml     # Configuration prod (à adapter)

🛠️ Commandes utiles

Commandes Makefile (recommandé)

Pour simplifier l'utilisation du projet, un Makefile est disponible avec les commandes les plus courantes :

# Démarrer l'environnement
make up

# Arrêter l'environnement
make down

# Redémarrer les conteneurs
make restart

# Voir l'état des conteneurs
make ps

# Voir les logs en temps réel
make logs

# Voir les logs d'un service spécifique
make logs-php
make logs-db
make logs-nginx

# Vider le cache
make cache-clear

# Exécuter les migrations
make db-migrate

# Créer la base de données
make db-create

# Bash dans le conteneur PHP
make php

# Installation initiale (cache + migrations)
make install

# Lancer les tests
make test

# Afficher l'aide des commandes disponibles
make help

Utilisez make help pour voir toutes les commandes disponibles avec leurs descriptions.

Gestion des conteneurs (sans Makefile)

# Démarrer l'environnement
docker compose up -d

# Arrêter l'environnement
docker compose down

# Voir les logs
docker compose logs -f

# Voir les logs d'un service spécifique
docker compose logs -f php

Commandes Symfony

# Exécuter des commandes Symfony
docker compose exec php bin/console <commande>

# Exemples :
docker compose exec php bin/console cache:clear
docker compose exec php bin/console debug:router
docker compose exec php bin/console list

Doctrine (Base de données)

# Créer la base de données (si elle n'existe pas)
docker compose exec php bin/console doctrine:database:create

# Créer une entité
docker compose exec php bin/console make:entity

# Générer une migration
docker compose exec php bin/console make:migration

# Exécuter les migrations
docker compose exec php bin/console doctrine:migrations:migrate

# Afficher le statut des migrations
docker compose exec php bin/console doctrine:migrations:status

Maker Bundle (Génération de code)

# Créer un contrôleur
docker compose exec php bin/console make:controller

# Créer une API Resource
docker compose exec php bin/console make:entity --api-resource

# Créer un formulaire
docker compose exec php bin/console make:form

# Créer un service
docker compose exec php bin/console make:service

# Voir toutes les commandes disponibles
docker compose exec php bin/console list make

Composer

# Installer une dépendance
docker compose exec php composer require <package>

# Installer une dépendance de dev
docker compose exec php composer require <package> --dev

# Mettre à jour les dépendances
docker compose exec php composer update

🗄️ Base de données

Configuration

• Host : db (dans Docker) ou localhost:3307 (depuis l'hôte)
• Database : lootopia
• User : symfony
• Password : symfony

Connexion depuis l'hôte (DBeaver, MySQL Workbench, etc.)

Host: localhost
Port: 3307
Database: lootopia
User: symfony
Password: symfony

Acces base de donnees en production (Azure)

L'infrastructure Azure deploie une application Container Apps dediee a l'administration de la base avec phpMyAdmin (lootopia-db-admin).

• URL d'administration : sortie Bicep dbAdminUrl
• Serveur MySQL : sortie Bicep mysqlFqdn
• Authentification : chaque developpeur utilise son compte MySQL (identifiant/mot de passe)

Workflow equipe :

1. Ouvrir l'URL de sortie dbAdminUrl.
2. Renseigner le serveur MySQL avec mysqlFqdn et le port 3306.
3. Se connecter avec un compte MySQL personnel.
4. Utiliser un compte lecture seule pour les consultations, et un compte ecriture uniquement si necessaire.

En cas d'incident, l'application d'admin peut etre stoppee temporairement depuis Azure (Portal ou CLI) sans impact sur l'application principale.

📧 Emails de développement

Tous les emails envoyés par l'application sont interceptés par Mailhog.

Accéder à l'interface : http://localhost:8025

Configuration dans .env :

MAILER_DSN=smtp://mailhog:1025

🐛 Debug avec Xdebug

Xdebug est activé dans l'environnement de développement sur le port 9003.

Configuration VS Code

Ajouter dans .vscode/launch.json :

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html": "${workspaceFolder}"
      }
    }
  ]
}

Configuration PhpStorm

1. File > Settings > PHP > Servers
2. Créer un nouveau serveur :
   • Name: lootopia
   • Host: localhost
   • Port: 8080
   • Debugger: Xdebug
   • Use path mappings: cocher
   • Mapper le dossier du projet vers /var/www/html

🌐 Routes disponibles

Route	Description
/	Landing page publique
/admin	Backoffice administrateur (Twig)
/partners	Tableau de bord partenaires (Twig)
/api	API REST pour l'application React Native

📡 Documentation API Platform

L'API est construite avec API Platform 4.2 et expose une documentation interactive accessible sur :

• Swagger UI : http://localhost:8080/api
• GraphQL : http://localhost:8080/graphql
• Redoc : http://localhost:8080/api/docs

Authentification JWT

À implémenter - Actuellement les routes User sont publiques.

# Inscription (création de compte)
POST /api/users
Content-Type: application/json

{
  "email": "user@example.com",
  "username": "john_doe",
  "password": "SecurePassword123"
}

# Réponse (201 Created)
{
  "id": 1,
  "email": "user@example.com",
  "username": "john_doe",
  "avatarUrl": null,
  "city": null,
  "totalPoints": 0,
  "completedHunts": 0,
  "completedSteps": 0,
  "loginStreak": 0,
  "level": "BRONZE",
  "createdAt": "2026-03-06T10:30:00Z",
  "updatedAt": "2026-03-06T10:30:00Z"
}

Endpoints Utilisateurs (/api/users)

📋 Lister tous les utilisateurs

GET /api/users
GET /api/users.json   # Format explicite
GET /api/users.jsonld # JSON-LD

Filtres disponibles (à implémenter) :

• city : Filtrer par ville
• level : Filtrer par niveau (BRONZE, SILVER, GOLD, PLATINUM)
• search : Recherche par username ou email

Pagination (à implémenter) :

GET /api/users?page=1&itemsPerPage=50

Tri (à implémenter) :

GET /api/users?order[totalPoints]=desc
GET /api/users?order[completedHunts]=desc
GET /api/users?order[createdAt]=asc

---

👤 Obtenir le profil d'un utilisateur

GET /api/users/{id}
GET /api/users/1.json

Réponse 200 :

{
  "id": 1,
  "email": "user@example.com",
  "username": "john_doe",
  "avatarUrl": "https://...",
  "city": "Paris",
  "totalPoints": 1250,
  "completedHunts": 5,
  "completedSteps": 42,
  "loginStreak": 12,
  "level": "SILVER",
  "createdAt": "2026-02-20T14:00:00Z",
  "updatedAt": "2026-03-05T18:45:00Z"
}

Réponse 404 :

{
  "@context": "/api/contexts/Error",
  "@type": "hydra:Error",
  "hydra:title": "An error occurred",
  "hydra:description": "Not Found",
  "trace": [...]
}

---

✏️ Modifier son profil (PATCH)

Sécurité : Utilisateur authentifié + être le propriétaire du compte

PATCH /api/users/{id}
Authorization: Bearer <JWT_TOKEN>
Content-Type: application/merge-patch+json

{
  "avatarUrl": "https://example.com/avatar.jpg",
  "city": "Lyon",
  "username": "john_doe_updated"
}

Champs patchables :

• email
• username
• password
• avatarUrl
• city

---

❌ Supprimer un utilisateur

Sécurité : Admin uniquement

DELETE /api/users/{id}
Authorization: Bearer <JWT_TOKEN>

Réponse 204 : No Content (succès)

---

Sérialisation et Groupes

L'API expose deux groupes de sérialisation :

Groupe	Usage	Champs
user:read	GET, List	id, email, username, avatarUrl, city, totalPoints, completedHunts, completedSteps, loginStreak, level, createdAt, updatedAt
user:write	POST, PATCH	email, username, password, avatarUrl, city

Champs exclus en lecture : password, roles
Champs exclus en écriture : id, totalPoints, completedHunts, completedSteps, loginStreak, level, createdAt, updatedAt

---

Codes HTTP

Code	Signification
200 OK	Succès - GET réussi
201 Created	Ressource créée avec succès (POST)
204 No Content	Succès - DELETE, réponse sans contenu
400 Bad Request	Erreur de validation (données invalides)
401 Unauthorized	Authentification requise
403 Forbidden	Accès refusé (Permission insuffisante)
404 Not Found	Ressource introuvable
409 Conflict	Contrainte unique violée (email/username déjà existant)
422 Unprocessable Entity	Erreur de validation métier
500 Internal Server Error	Erreur serveur

---

⚙️ Tester l'API

Avec cURL

# Lister les utilisateurs
curl http://localhost:8080/api/users -H "Accept: application/json"

# Créer un utilisateur
curl -X POST http://localhost:8080/api/users \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "username": "testuser",
    "password": "YourPassword123"
  }'

# Obtenir un utilisateur
curl http://localhost:8080/api/users/1 -H "Accept: application/json"

# Modifier un utilisateur
curl -X PATCH http://localhost:8080/api/users/1 \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"city": "Marseille"}'

Avec Postman / Insomnia

Importer la collection depuis : http://localhost:8080/api/docs.json

Avec Swagger UI (interface web)

Accès direct : http://localhost:8080/api

📦 Déploiement en production

1. Build de l'image de production

docker build -f docker/Dockerfile --target=prod -t your-registry/lootopia-php:TAG .

2. Push vers le registry

docker push your-registry/lootopia-php:TAG

3. Déploiement

Utiliser docker-compose.prod.yml ou les manifests de votre plateforme d'orchestration (Kubernetes, ECS, etc.).

Important : En production, configurer les variables d'environnement :

• APP_ENV=prod
• APP_SECRET=<secret-généré>
• DATABASE_URL=<url-de-la-base-prod>

🆘 Dépannage

Les conteneurs ne démarrent pas

docker compose down
docker compose up -d --build

Problèmes de permissions (Windows)

Vérifier que Docker Desktop utilise WSL2 comme backend.

L'application retourne une erreur 500

# Vérifier les logs
docker compose logs php

# Vider le cache
docker compose exec php bin/console cache:clear

La base de données est inaccessible

# Vérifier que le conteneur MySQL est lancé
docker compose ps

# Tester la connexion
docker compose exec php bin/console doctrine:query:sql "SELECT 1"

📚 Documentation

• Symfony Documentation
• API Platform Documentation
• Doctrine Documentation

👥 Équipe

Backend Symfony développé pour le projet Lootopia.