geo/api/docs/TECHBOOK.md

# Documentation Technique API RESTful PHP 8.3

## Table des matières

1. [Structure du projet](#structure-du-projet)
2. [Configuration du serveur](#configuration-du-serveur)
3. [Flux d'une requête](#flux-dune-requête)
4. [Architecture des composants](#architecture-des-composants)
5. [Base de données](#base-de-données)
6. [Sécurité](#sécurité)
7. [Endpoints API](#endpoints-api)

## Structure du projet

```plaintext
/api/
├── docs/
│   └── TECHBOOK.md
├── src/
│   ├── Controllers/
│   │   └── UserController.php
│   ├── Core/
│   │   ├── Router.php
│   │   ├── Request.php
│   │   ├── Response.php
│   │   ├── Session.php
│   │   └── Database.php
│   └── Config/
│       └── config.php
├── index.php
└── .htaccess
```

## Configuration du serveur

### Prérequis

- Debian 12
- NGINX
- PHP 8.3-FPM
- MariaDB 10.11

### Configuration NGINX

Le serveur NGINX est configuré pour rediriger toutes les requêtes vers le point d'entrée `index.php` de l'API.

### Configuration PHP-FPM

PHP-FPM est configuré pour gérer les processus PHP avec des paramètres optimisés pour une API.

## Flux d'une requête

Exemple détaillé du parcours d'une requête POST /api/users :

1. **Entrée de la requête**

   - La requête arrive sur le serveur NGINX
   - NGINX redirige vers PHP-FPM via le socket unix
   - Le fichier .htaccess redirige vers index.php

2. **Initialisation (index.php)**

   - Chargement des dépendances
   - Initialisation de la configuration
   - Démarrage de la session
   - Configuration des headers CORS
   - Initialisation du routeur

3. **Routage**

   - Le Router analyse la méthode HTTP (POST)
   - Analyse de l'URI (/api/users)
   - Correspondance avec les routes enregistrées
   - Instanciation du Controller approprié

4. **Traitement (UserController)**

   - Vérification de l'authentification
   - Récupération des données JSON
   - Validation des données reçues
   - Traitement métier
   - Interaction avec la base de données
   - Préparation de la réponse

5. **Réponse**
   - Formatage de la réponse en JSON
   - Configuration des headers de réponse
   - Envoi au client

## Architecture des composants

### Core Components

#### Router

- Gère le routage des requêtes
- Associe les URLs aux Controllers
- Gère les paramètres d'URL
- Dispatch vers les méthodes appropriées

#### Request

- Parse les données entrantes
- Gère les différents types de contenu
- Nettoie et valide les entrées
- Fournit une interface unifiée pour accéder aux données

#### Response

- Formate les réponses en JSON
- Gère les codes HTTP
- Configure les headers de réponse
- Assure la cohérence des réponses

#### Session

- Gère l'état des sessions
- Stocke les données d'authentification
- Vérifie les permissions
- Sécurise les données de session

#### Database

- Gère la connexion à MariaDB
- Fournit une interface PDO
- Gère le pool de connexions
- Assure la sécurité des requêtes

## Sécurité

### Mesures implémentées

- Validation stricte des entrées
- Protection contre les injections SQL (PDO)
- Hachage sécurisé des mots de passe
- Headers de sécurité HTTP
- Gestion des CORS
- Session sécurisée
- Authentification requise

## Endpoints API

### Routes Publiques vs Privées

L'API distingue deux types de routes :

#### Routes Publiques

- POST /api/login
- POST /api/register
- GET /api/health

#### Routes Privées (Nécessitent une session authentifiée)

- Toutes les autres routes

### Authentification

L'authentification utilise le système de session PHP natif.

#### Login

```http
POST /api/login
Content-Type: application/json

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

**Réponse réussie :**

```json
{
  "message": "Connecté avec succès",
  "user": {
    "id": 123,
    "email": "user@example.com"
  }
}
```

**Notes importantes :**

- Un cookie de session PHP sécurisé est automatiquement créé
- Le cookie est httpOnly, secure et SameSite=Strict
- L'ID de session est régénéré à chaque login réussi

#### Logout

```http
POST /api/logout
```

**Réponse réussie :**

```json
{
  "message": "Déconnecté avec succès"
}
```

### Sécurité des Sessions

La configuration des sessions inclut :

- Sessions PHP natives sécurisées
- Protection contre la fixation de session
- Cookies httpOnly (protection XSS)
- Mode strict pour les cookies
- Validation côté serveur à chaque requête

- use_strict_mode = 1
- cookie_httponly = 1
- cookie_secure = 1
- cookie_samesite = Strict
- Régénération de l'ID de session après login
- Destruction complète de la session au logout

### Users

#### Création d'utilisateur

```http
POST /api/users
Content-Type: application/json

{
    "name": "John Doe",
    "email": "john@example.com",
    "password": "SecurePassword123"
}
```

**Réponse réussie :**

```json
{
  "message": "Utilisateur créé",
  "id": "123"
}
```

**Codes de statut :**

- 201: Création réussie
- 400: Données invalides
- 401: Non authentifié
- 500: Erreur serveur

#### Autres endpoints

- GET /api/users
- GET /api/users/{id}
- PUT /api/users/{id}
- DELETE /api/users/{id}

## Intégration Frontend

### Configuration des Requêtes

Toutes les requêtes API depuis le frontend doivent inclure :

```javascript
fetch('/api/endpoint', {
  credentials: 'include', // Important pour les cookies de session
  // ... autres options
});
```

### Gestion des Sessions

- Les cookies de session sont automatiquement gérés par le navigateur
- Pas besoin de stocker ou gérer des tokens manuellement
- Redirection vers /login si session expirée (401)

## Maintenance et Déploiement

### Logs

- Logs d'accès NGINX : /var/log/nginx/api-access.log
- Logs d'erreur NGINX : /var/log/nginx/api-error.log
- Logs PHP : /var/log/php/php-error.log

### Déploiement

1. Pull du repository
2. Vérification des permissions
3. Configuration de l'environnement
4. Tests des endpoints
5. Redémarrage des services

### Surveillance

- Monitoring des processus PHP-FPM
- Surveillance de la base de données
- Monitoring des performances
- Alertes sur erreurs critiques