PHP — Concepts clés du projet GSB

Les 3 rôles

Le flux d'une requête

// 1. L'utilisateur visite : index.php?uc=validerFiche&action=chargerFiche

// 2. index.php (routeur) lit le paramètre "uc" et inclut le bon contrôleur :
switch ($uc) {
    case 'validerFiche':
        include PATH_CTRLS . 'c_validerFiche.php';  // → inclut le contrôleur
        break;
}

// 3. Le contrôleur appelle le modèle :
$lesFrais = $pdo->getLesFraisForfait($idVisiteur, $mois);

// 4. Le contrôleur passe les données à la vue :
include PATH_VIEWS . 'v_validerFiche.php';

// 5. La vue lit $lesFrais et génère le HTML.
PHP

Qui fait quoi ?

En PHP — changer l'état d'une fiche

// La constante ETAT_VA vaut 'VA' (définie dans config/define.php).
// Toujours préférer une constante à une chaîne en dur :

// ❌ Éviter
$pdo->majEtatFicheFrais($idVisiteur, $mois, 'VA');

// ✅ Préférer
$pdo->majEtatFicheFrais($idVisiteur, $mois, ETAT_VA);

// Pourquoi ? Si demain l'état s'appelle "VALIDE" au lieu de "VA",
// on change une seule ligne dans define.php, pas 10 fichiers.
PHP

Les filtres les plus utilisés en GSB

Exemple complet — lire plusieurs champs POST

// Un formulaire HTML envoie : visiteur, mois, lesFrais[]

// Champ texte simple → FILTER_SANITIZE_FULL_SPECIAL_CHARS
$idVisiteur = filter_input(INPUT_POST, 'visiteur', FILTER_SANITIZE_FULL_SPECIAL_CHARS);
$mois       = filter_input(INPUT_POST, 'mois',     FILTER_SANITIZE_FULL_SPECIAL_CHARS);

// Tableau de champs → FILTER_DEFAULT + FILTER_FORCE_ARRAY
// Résultat : $lesFrais = ['ETP' => '12', 'KM' => '560', ...]
$lesFrais = filter_input(INPUT_POST, 'lesFrais', FILTER_DEFAULT, FILTER_FORCE_ARRAY);
PHP

Comment ça fonctionne

$nom = '<script>alert("hacked")</script>';

// ❌ Sans protection — le script s'exécute dans le navigateur
echo $nom;
// Sortie HTML : <script>alert("hacked")</script>  ← EXÉCUTÉ !

// ✅ Avec htmlspecialchars() — affiché comme texte, non exécuté
echo htmlspecialchars($nom);
// Sortie HTML : &lt;script&gt;alert("hacked")&lt;/script&gt;  ← INOFFENSIF
PHP

Table de conversion

Les 3 étapes d'une requête préparée

// ÉTAPE 1 : préparer — on envoie la structure SQL au serveur.
// Les :paramètres sont des emplacements vides, pas encore des valeurs.
$req = $this->connexion->prepare(
    'SELECT * FROM fichefrais '
    . 'WHERE idvisiteur = :unIdVisiteur '
    . 'AND mois = :unMois'
);

// ÉTAPE 2 : lier — on associe chaque :paramètre à une variable PHP.
// PDO_PARAM_STR indique que c'est une chaîne (PARAM_INT pour entier).
// PDO JAMAIS d'injection possible ici : la valeur est séparée du SQL.
$req->bindParam(':unIdVisiteur', $idVisiteur, PDO::PARAM_STR);
$req->bindParam(':unMois',       $mois,       PDO::PARAM_STR);

// ÉTAPE 3 : exécuter, puis récupérer les résultats.
$req->execute();
$resultat = $req->fetchAll();  // tableau de toutes les lignes
$uneSeule = $req->fetch();      // une seule ligne
PHP

Structure de base

$action = filter_input(INPUT_GET, 'action', FILTER_SANITIZE_FULL_SPECIAL_CHARS);

// On donne une valeur par défaut si $action est null (paramètre absent de l'URL)
if (!$action) {
    $action = 'afficher';
}

switch ($action) {

    case 'chargerFiche':
        // Exécuté quand ?action=chargerFiche est dans l'URL
        $data = $pdo->getLesFraisForfait($id, $mois);
        include 'v_validerFiche.php';
        break;  // ← OBLIGATOIRE pour ne pas tomber dans le case suivant

    case 'valider':
        $pdo->majEtatFicheFrais($id, $mois, ETAT_VA);
        include 'v_validerFiche.php';
        break;

    case 'afficher':
    default:  // ← capte tout ce qui ne correspond à aucun case
        include 'v_validerFiche.php';
        break;
}
PHP

isset() — La variable existe-t-elle ?

// isset() retourne true si la variable existe ET n'est pas null.
// false si la variable n'est pas définie, ou si elle vaut null.

if (isset($lesFraisForfait)) {
    // On sait que $lesFraisForfait existe
    foreach ($lesFraisForfait as $f) { ... }
}

// ❌ Sans isset() → PHP_WARNING "Undefined variable" si la variable n'existe pas
foreach ($lesFraisForfait as $f) { ... }
PHP

is_array() — Peut-on itérer dessus ?

// Un fetch() PDO peut retourner false si aucune ligne trouvée.
// Un fetchAll() retourne toujours un tableau (vide si aucun résultat).
// is_array() protège le foreach si la valeur peut ne pas être un tableau.

if (isset($tousVisiteurs) && is_array($tousVisiteurs)) {
    foreach ($tousVisiteurs as $v) {
        echo htmlspecialchars($v['nom']);
    }
}

// count() sur un tableau vide retourne 0 (pas d'erreur).
// Utile pour afficher un message "Aucun résultat" :
if (count($lesMois) === 0) {
    echo 'Aucun mois disponible';
}
PHP

Côté HTML — les champs du formulaire

<!-- name="lesFrais[ETP]" → crée $_POST['lesFrais']['ETP'] -->
<input type="text" name="lesFrais[ETP]" value="12">
<input type="text" name="lesFrais[KM]"  value="560">
<input type="text" name="lesFrais[NUI]" value="6">
<input type="text" name="lesFrais[REP]" value="25">
HTML

Côté PHP — ce que reçoit le contrôleur

// filter_input avec FILTER_FORCE_ARRAY reconstruit le tableau :
$lesFrais = filter_input(INPUT_POST, 'lesFrais', FILTER_DEFAULT, FILTER_FORCE_ARRAY);

// $lesFrais est maintenant :
// [
//   'ETP' => '12',
//   'KM'  => '560',
//   'NUI' => '6',
//   'REP' => '25'
// ]

// On peut ensuite itérer dessus :
foreach ($lesFrais as $idFrais => $quantite) {
    echo "$idFrais : $quantite";  // "ETP : 12", "KM : 560"...
}
PHP

Comment la vue génère ces champs dynamiquement

<?php foreach ($lesFraisForfait as $unFrais): ?>
    <label>
        <?php echo htmlspecialchars($unFrais['libelle']); ?>
    </label>
    <input
        type="text"
        name="lesFrais[<?php echo htmlspecialchars($unFrais['idfrais']); ?>]"
        value="<?php echo htmlspecialchars($unFrais['quantite']); ?>"
    >
<?php endforeach; ?>

<!--
    Pour chaque frais de la BDD, la boucle génère un champ input.
    Son name change dynamiquement : lesFrais[ETP], lesFrais[KM]...
    C'est ce qui permet au contrôleur de reconstituer le tableau.
-->
PHP + HTML

Définir et utiliser une constante

// Dans config/define.php — définies UNE SEULE FOIS
define('PATH_VIEWS', '../src/Vues/');
define('PATH_CTRLS', '../src/Controleurs/');
define('ETAT_CR',   'CR');
define('ETAT_VA',   'VA');
define('ETAT_RB',   'RB');

// Dans n'importe quel autre fichier — pas de $ devant une constante !
include PATH_VIEWS . 'v_validerFiche.php';
$pdo->majEtatFicheFrais($id, $mois, ETAT_VA);
PHP

Signature et exemples

// number_format(nombre, décimales, séparateur_décimal, séparateur_milliers)

echo number_format(1234.5, 2, ',', ' ');
// Affiche : "1 234,50"   ← format français (virgule + espace)

echo number_format(1234.5, 2, '.', '');
// Affiche : "1234.50"    ← format tableau (point, pas de séparateur milliers)

// Cast (float) important : la BDD retourne parfois des chaînes
echo number_format((float)$hf['montant'], 2, '.', '');
PHP

Exemple

<!--
    L'utilisateur ne voit pas ce champ.
    Mais il est bien envoyé lors de la soumission du formulaire.
    Sans lui, le contrôleur ne saurait pas quelle fiche valider.
-->
<form method="post" action="index.php?uc=validerFiche&action=valider">

    <input type="hidden" name="visiteur" value="a131">
    <input type="hidden" name="mois"     value="202403">

    <!-- Champs visibles pour les quantités -->
    <input type="text" name="lesFrais[ETP]" value="12">

    <button type="submit">Valider</button>
</form>
HTML

Exemple — rechargement automatique au changement de visiteur

<!--
    Quand l'utilisateur choisit un visiteur dans le menu déroulant,
    le formulaire est immédiatement soumis.
    Le contrôleur reçoit la sélection et recharge la bonne fiche.
    this = l'élément select lui-même
    this.form = le formulaire qui contient ce select
    this.form.submit() = soumet ce formulaire
-->
<select name="visiteur" onchange="this.form.submit()">
    <option value="a131">BEDOS Sophie</option>
    <option value="a17">CADIC Alexis</option>
</select>
HTML

confirm() — Demander une confirmation avant une action

<!--
    onclick="return confirm(...)" :
    - Affiche une boîte de dialogue native du navigateur.
    - Si l'utilisateur clique "OK" → return true → la navigation continue.
    - Si l'utilisateur clique "Annuler" → return false → rien ne se passe.
    Utile avant toute action irréversible (refuser, supprimer...).
-->
<a
    href="index.php?uc=validerFiche&action=refuserHF&idFrais=42"
    onclick="return confirm('Confirmer le refus de ce frais ?')"
>
    Refuser
</a>
HTML

Fallthrough intentionnel

switch ($action) {

    case 'payer':
        $pdo->rembourserFiche($idVisiteur, $mois);
        $message = 'Fiche remboursée !';
        // ↓ PAS de break → tombe dans 'lister' automatiquement

    case 'lister':
    case 'afficher':  // deux cases pour une même action : si vide, PHP passe au suivant
    default:
        $fichesValidees = $pdo->getFichesValidees();
        include 'v_suiviPaiement.php';
        break;  // ← break ici, à la fin du bloc partagé
}
PHP

Le formulaire de filtre avec GET

<!--
    method="get" : les données apparaissent dans l'URL.
    ?uc=suiviPaiement&action=lister&visiteur=a17
                                         ↑ filtre visible dans l'URL
    Avantages :
      - Bookmarkable : on peut sauvegarder le lien filtré
      - Partageable  : envoyer le lien à un collègue
      - Historique   : le bouton "Précédent" fonctionne correctement

    Avec POST, l'URL resterait "?uc=suiviPaiement" sans le filtre.
    Un F5 (rafraîchissement) demanderait à renvoyer les données → mauvaise UX.
-->
<form method="get" action="index.php">
    <!-- Avec GET, uc et action doivent être des champs cachés -->
    <input type="hidden" name="uc"     value="suiviPaiement">
    <input type="hidden" name="action" value="lister">

    <select name="visiteur" onchange="this.form.submit()">
        <option value="">Tous</option>
        <option value="a17">CADIC Alexis</option>
    </select>
</form>
<!-- URL générée : index.php?uc=suiviPaiement&action=lister&visiteur=a17 -->
HTML

Côté PHP — lire le filtre et l'utiliser

// Le filtre vient de l'URL → INPUT_GET
$filtreVisiteur = filter_input(INPUT_GET, 'visiteur', FILTER_SANITIZE_FULL_SPECIAL_CHARS);

// Opérateur ternaire : version condensée du if/else
// condition ? valeur_si_vrai : valeur_si_faux
$fichesValidees = $filtreVisiteur
    ? $pdo->getFichesValidees($filtreVisiteur)  // filtre actif
    : $pdo->getFichesValidees();                  // tous les visiteurs

// Équivalent avec if/else (plus lisible pour débuter) :
if ($filtreVisiteur) {
    $fichesValidees = $pdo->getFichesValidees($filtreVisiteur);
} else {
    $fichesValidees = $pdo->getFichesValidees();
}
PHP

substr() — Extraire une partie d'une chaîne

// substr(chaîne, position_début, longueur)
// Les positions commencent à 0 (comme les tableaux).

$mois = '202403';   // format stocké en BDD : aaaamm

$annee = substr($mois, 0, 4);  // → "2024" (4 caractères depuis le début)
$numM  = substr($mois, 4, 2);  // → "03"   (2 caractères à partir du 5ème)

// Affichage lisible : "03/2024"
echo $numM . '/' . $annee;

// Autres exemples utiles :
substr('Bonjour', 0, 3);   // → "Bon"
substr('Bonjour', 3);       // → "jour" (jusqu'à la fin)
substr('Bonjour', -4);      // → "jour" (4 caractères depuis la fin)
PHP

date() — Obtenir la date/heure actuelle

// date(format) retourne la date courante selon le format donné.

date('Y');          // → "2026"        (année sur 4 chiffres)
date('m');          // → "04"          (mois avec zéro : 01 à 12)
date('d');          // → "28"          (jour avec zéro : 01 à 31)
date('Y-m-d');      // → "2026-04-28"  (format SQL)
date('d/m/Y');      // → "28/04/2026"  (format français)
date('Ym');         // → "202604"      (format mois GSB)

// Dans le contrôleur, on l'utilise pour les stats de l'année en cours :
$annee = date('Y');  // pas besoin d'écrire 2026 en dur !
PHP

Principe

<tbody>
    <?php foreach ($fichesValidees as $f): ?>
    <tr>
        <td><?php echo htmlspecialchars($f['nom']); ?></td>
        <td><?php echo htmlspecialchars($f['mois']); ?></td>
        <td>
            <!--
                Chaque ligne a SON propre formulaire avec SES propres
                champs cachés. Le bouton "Payer" soumet uniquement
                les données de cette ligne, pas de toutes les autres.
            -->
            <form method="post" action="index.php?uc=suiviPaiement&action=payer">
                <input type="hidden" name="idVisiteur" value="<?= htmlspecialchars($f['idvisiteur']) ?>">
                <input type="hidden" name="mois"       value="<?= htmlspecialchars($f['mois']) ?>">
                <button type="submit">Payer</button>
            </form>
        </td>
    </tr>
    <?php endforeach; ?>
</tbody>
HTML + PHP

Le problème

<!-- Si $nom contient une apostrophe (O'Brien), la chaîne JS est cassée : -->
<button onclick="return confirm('Payer O'Brien ?')">   <!-- ❌ CASSÉ -->

<!-- La protection combinée : -->
<button onclick="return confirm('')">   <!-- ✅ OK -->
HTML + PHP

Les deux fonctions sont complémentaires

Pattern accumulateur

// TOUJOURS initialiser AVANT la boucle
// Si on oublie : PHP_WARNING "Undefined variable" à la 1ère addition
$totalAnnee = 0.0;  // 0.0 (float) et non 0 (int) car les montants ont des décimales

foreach ($statsRemboursements as $stat) {
    // (float) cast : convertit en nombre flottant.
    // La BDD retourne parfois les résultats de SUM() en chaîne ("1234.50").
    // Sans cast, PHP peut faire une addition de chaînes au lieu de nombres.
    $montant = (float)$stat['total'];

    // += est un raccourci pour : $totalAnnee = $totalAnnee + $montant
    $totalAnnee += $montant;
}

// Après la boucle, $totalAnnee contient la somme de tous les mois
echo number_format($totalAnnee, 2, ',', ' ') . ' €';
PHP

Opérateurs d'assignation composés

Structure d'un bloc PHPDoc

/**                                          ← Commence par /**  (deux étoiles)
 * Courte description sur une ligne.
 *
 * Description longue optionnelle sur
 * plusieurs lignes si besoin.
 *
 * @tag1  valeur                             ← Tags : métadonnées structurées
 * @tag2  valeur
 */
public function maFonction(): void
{
    // ...
}
PHP

Exemple réel — méthode de PdoGsb

/**
 * Retourne les frais forfaitisés d'un visiteur pour un mois donné.
 *
 * Effectue une jointure entre lignefraisforfait et fraisforfait
 * pour obtenir le libellé et le montant unitaire de chaque frais.
 *
 * @param string $idVisiteur Identifiant du visiteur (ex: "a131")
 * @param string $mois       Mois au format aaaamm (ex: "202403")
 *
 * @return array Tableau associatif avec les clés :
 *               idfrais, libelle, montant, quantite
 */
public function getLesFraisForfait($idVisiteur, $mois): array
{
    // ...
}
PHP

Tags courants

Documenter une classe complète

/**
 * Classe d'accès aux données GSB.
 *
 * Utilise PDO pour toutes les interactions avec la base MariaDB.
 * Implémente le patron Singleton : une seule instance par requête HTTP.
 *
 * @package   GSB
 * @author    Jean Dupont <jean@example.com>
 * @version   1.0.0
 * @see       https://www.php.net/manual/fr/book.pdo.php
 */
class PdoGsb
{
    /**
     * Instance unique de la connexion PDO.
     *
     * @var PDO
     */
    protected $connexion;

    /**
     * Seule instance de la classe (Singleton).
     *
     * @var PdoGsb|null
     */
    private static $instance = null;
}
PHP

phpdoc.xml expliqué ligne par ligne

<?xml version="1.0" encoding="UTF-8" ?>
<phpdocumentor configVersion="3"
    xmlns="https://www.phpdoc.org">

    <!-- Titre affiché en haut de la documentation générée -->
    <title>GSB — Application de gestion de frais</title>

    <paths>
        <!-- Où écrire la documentation HTML -->
        <output>docs/</output>
        <!-- Dossier de cache interne (ne pas versionner) -->
        <cache>.phpdoc/cache</cache>
    </paths>

    <version number="1.0.0">
        <api>
            <!-- dsn="." = depuis le dossier courant (racine du projet) -->
            <source dsn=".">
                <!-- Dossiers à analyser -->
                <path>src/</path>
                <path>resources/Outils/</path>
            </source>

            <ignore hidden="true">
                <!-- Dossiers exclus — les libs tierces ne nous appartiennent pas -->
                <path>vendor/</path>
                <path>docs/</path>
            </ignore>

            <!-- Visibilité des membres documentés -->
            <visibility>public</visibility>
            <visibility>protected</visibility>
        </api>
    </version>

    <!-- Thème visuel : "default" = thème officiel responsive de phpDoc v3 -->
    <template name="default"/>

</phpdocumentor>
XML

Commandes à connaître

# Depuis la racine du projet GSB (là où se trouve phpDocumentor.phar)

# Génération avec le fichier de config
php phpDocumentor.phar -c phpdoc.xml

# Ou avec le script shell fourni (plus pratique)
./generer-doc.sh

# Vérifier la version de phpDocumentor installée
php phpDocumentor.phar --version

# Afficher toutes les options disponibles
php phpDocumentor.phar --help

Ce que génère phpDocumentor

Pourquoi ce choix de conception ?

Les 3 endroits où le REFUSE est géré

// 1. MODÈLE — Marquer comme refusé (PdoGsb::refuserFraisHorsForfait)
// CONCAT() ajoute le préfixe. La condition NOT LIKE évite de doubler le préfixe.
"UPDATE lignefraishorsforfait
 SET libelle = CONCAT('REFUSE ', libelle)
 WHERE id = :unIdFrais
 AND libelle NOT LIKE 'REFUSE %'"

// 2. MODÈLE — Exclure du calcul (PdoGsb::calculerMontantFiche)
// Les lignes REFUSE ne sont pas comptées dans le montant remboursé.
"SELECT SUM(montant) FROM lignefraishorsforfait
 WHERE idvisiteur = :v AND mois = :m
 AND libelle NOT LIKE 'REFUSE %'"
// ↑ Cette clause SQL exclut toutes les lignes dont le libellé commence par "REFUSE "

// 3. VUE VISITEUR — Affichage distinct (v_etatFrais.php)
// strpos() détecte le préfixe, la vue affiche badge rouge + texte barré.
$estRefuse = (strpos($libelle, 'REFUSE ') === 0);
PHP + SQL

Le comportement de strpos()

// strpos(chaîne, sous-chaîne) → position (int) ou false

strpos('REFUSE Taxi', 'REFUSE ');   // → 0     (trouvé à la position 0)
strpos('Taxi REFUSE', 'REFUSE ');   // → 5     (trouvé à la position 5)
strpos('Taxi / VTC',  'REFUSE ');   // → false (absent)
PHP

== vs === — La règle à retenir

Règle pratique : toujours utiliser === avec strpos(), array_search() et toute fonction qui peut retourner 0 ou false.

Différences clés

Pattern : détecter puis nettoyer

$libelle = 'REFUSE Taxi / VTC';

// ÉTAPE 1 : détecter
$estRefuse = (strpos($libelle, 'REFUSE ') === 0);  // true

// ÉTAPE 2 : retirer le préfixe pour l'affichage
// strlen('REFUSE ') = 7 → on saute les 7 premiers caractères
// On pourrait aussi écrire strlen('REFUSE ') à la place de 7
// pour que le code s'adapte automatiquement si le préfixe change.
$prefixe        = 'REFUSE ';
$libelleAffiche = $estRefuse
    ? substr($libelle, strlen($prefixe))  // → "Taxi / VTC"
    : $libelle;                               // → libellé inchangé

// ÉTAPE 3 : afficher avec style conditionnel
if ($estRefuse) {
    echo '<s class="text-muted">' . htmlspecialchars($libelleAffiche) . '</s>';
    echo '<span class="badge bg-danger">Refusé</span>';
} else {
    echo htmlspecialchars($libelleAffiche);
    echo '<span class="badge bg-success">Accepté</span>';
}
PHP

Fonctions de chaînes utiles — récap

Le problème : stocker les mots de passe en clair

Imaginez que la base de données soit volée (dump SQL exfiltré). Si les mots de passe sont en clair :

• L'attaquant a accès à TOUS les comptes instantanément.
• Comme la plupart des gens réutilisent leurs mots de passe, les comptes Gmail, bancaires, etc. sont aussi compromis.
• L'entreprise est responsable légalement (RGPD art. 32 : obligation de sécuriser les données personnelles).

La solution : le hachage (hashing)

Le hachage transforme un mot de passe en une empreinte de longueur fixe, de façon irréversible :

"azerty" → $2y$10$abc...xyz (60 caractères bcrypt)
"azerty" → $2y$10$def...uvw (hash DIFFÉRENT, car sel différent)
CONCEPT

• Irréversible : on ne peut pas retrouver "azerty" depuis le hash.
• Déterministe : le même algorithme + le même sel → le même hash.
• Avec sel : deux utilisateurs avec le même mot de passe ont des hashes différents.

Hachage ≠ Chiffrement

On ne CHIFFRE pas un mot de passe, car si la clé fuit, tous les mots de passe sont récupérables. On les HACHE.

Tableau comparatif

Pourquoi MD5 et SHA-1 sont-ils interdits ?

Pourquoi SHA-256 est insuffisant pour les mots de passe

// SHA-256 est RAPIDE — c'est son problème pour les mots de passe
$hash = hash('sha256', $mdp);
// Un GPU récent → 2 MILLIARDS de SHA-256/seconde
// "azerty" + 2 milliards d'essais = trouvé en quelques secondes

// Avec sel manuel — mieux, mais toujours trop rapide
$sel = bin2hex(random_bytes(32)); // sel aléatoire
$hash = hash('sha256', $sel . $mdp);
// Problème : doit stocker le sel séparément, et toujours trop rapide
PHP

SHA-256 n'a pas de "cost factor" : on ne peut pas le rendre plus lent quand les GPUs progressent. bcrypt, lui, peut être recalibré.

Pourquoi bcrypt est le choix standard

// bcrypt est LENT — c'est voulu
// cost factor 10 → 2^10 = 1024 itérations internes → ~80ms par hash

// Pour l'utilisateur qui se connecte UNE FOIS : imperceptible (80ms)
// Pour un attaquant qui teste 10 millions de mots de passe :
// 10 000 000 × 80ms = 800 000 secondes ≈ 9 JOURS (sans GPU dédié)

// bcrypt génère un hash qui CONTIENT le sel :
// $2y$10$SSSSSSSSSSSSSSSSSSSSS.HHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH
// ^^^^ ^^  ^^^^^^^^^^^^^^^^^^^^^^  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
// algo cost  sel (22 chars base64)   hash (31 chars base64)
CONCEPT

Hacher un mot de passe lors de l'inscription

// ── LORS DE L'INSCRIPTION ou de la modification du mot de passe ──

$mdpBrut = filter_input(INPUT_POST, 'mdp', FILTER_SANITIZE_FULL_SPECIAL_CHARS);

// PASSWORD_BCRYPT  → force l'algorithme bcrypt ($2y$)
// PASSWORD_DEFAULT → meilleur algo disponible dans cette version de PHP
// PASSWORD_ARGON2ID → Argon2id (PHP 7.3+, recommandé si disponible)
$hash = password_hash($mdpBrut, PASSWORD_BCRYPT);

// $hash ressemble à : $2y$10$randomSalt22chars.hashValue31chars
// longueur fixe : 60 caractères → colonne BDD CHAR(60) ou VARCHAR(255)

// Enregistrement en BDD avec requête préparée
$stmt = $pdo->prepare('UPDATE visiteur SET mdp = :hash WHERE id = :id');
$stmt->execute([':hash' => $hash, ':id' => $id]);
PHP

Vérifier un mot de passe lors de la connexion

// ── LORS DE LA CONNEXION ──

$mdpSaisi   = filter_input(INPUT_POST, 'mdp', FILTER_SANITIZE_FULL_SPECIAL_CHARS);
$hashStocke = $pdo->getMdpVisiteur($login);  // retourne le $2y$10$... depuis BDD

// password_verify() :
// 1. Extrait le sel des 22 premiers chars du hash stocké
// 2. Recalcule bcrypt(mdpSaisi, sel) avec le même cost factor
// 3. Compare byte par byte en temps constant (anti-timing attack)
// 4. Retourne true ou false
if (!$hashStocke || !password_verify($mdpSaisi, $hashStocke)) {
    // Message vague intentionnellement : ne pas révéler si c'est le login
    // ou le mot de passe qui est incorrect (évite l'énumération de comptes)
    Utilitaires::ajouterErreur('Login ou mot de passe incorrect');
} else {
    // Connexion réussie → charger les infos et ouvrir la session
    $visiteur = $pdo->getInfosVisiteur($login);
    Utilitaires::connecter($visiteur['id'], $visiteur['nom'], $visiteur['prenom']);
    header('Location: index.php');
    exit; // toujours exit après un header Location
}
PHP

password_needs_rehash() — rehachage transparent

Si PHP passe de bcrypt (cost 10) à Argon2id comme PASSWORD_DEFAULT, les anciens hashes restent valides. Mais on peut les mettre à niveau automatiquement lors de la prochaine connexion :

if (password_verify($mdp, $hashStocke)) {
    // Connexion OK. L'algo ou le cost factor a-t-il évolué ?
    if (password_needs_rehash($hashStocke, PASSWORD_DEFAULT)) {
        // Oui → on rehache avec le nouvel algo et on met à jour la BDD
        $nouveauHash = password_hash($mdp, PASSWORD_DEFAULT);
        // UPDATE visiteur SET mdp = $nouveauHash WHERE id = $id
    }
    // Dans tous les cas on ouvre la session
}
PHP

C'est la migration "sans downtime" : les utilisateurs ne voient rien, leurs hashes sont mis à niveau en silence lors des connexions.

Le scénario : une BDD avec des mots de passe en clair

Un projet existant stockait les mots de passe en clair (ou en MD5). Il faut migrer sans obliger les utilisateurs à se reconnecter.

Le script resources/bdd/uptMdp.php fait cette migration en CLI :

Structure du script de migration

// 1. Lire tous les enregistrements
$rows = $pdo->query('SELECT id, mdp FROM visiteur')->fetchAll();

// 2. Détecter si un hash est déjà en bcrypt
function estDejaHache(string $s): bool {
    // Les hashes bcrypt commencent par $2y$, $2a$ ou $2b$
    // Les hashes Argon2 commencent par $argon2
    return (bool) preg_match('/^\$(2y|2a|2b)\$|^\$argon2/i', $s);
}

// 3. Transaction — atomicité
$pdo->beginTransaction();

foreach ($rows as $row) {
    if (estDejaHache($row['mdp'])) continue; // déjà ok

    $hash = password_hash($row['mdp'], PASSWORD_BCRYPT);
    $stmt->execute([':hash' => $hash, ':id' => $row['id']]);
}

$pdo->commit(); // ou rollBack() si erreur
PHP

Concept clé : la transaction PDO

Principe d'atomicité : soit TOUT réussit, soit RIEN n'est enregistré. La BDD ne peut pas se retrouver dans un état intermédiaire incohérent.

Exécution du script de migration

# Depuis la racine du projet, en ligne de commande
php resources/bdd/uptMdp.php

# Résultat attendu :
#  [IGNORÉ]  id=a118y — déjà haché en bcrypt/Argon2.
#  [HACHÉ]   id=xyz   — hash bcrypt enregistré.
#  ...
#  ✓  Transaction validée.
#  Total lu        : 150
#  Hashés (bcrypt) : 0    ← si déjà tous migrés
#  Ignorés         : 150
BASH

Le script est idempotent : l'exécuter plusieurs fois ne cause aucun dommage — il ignore les hashes déjà en bcrypt.

Pourquoi un barème différencié ?

Un véhicule plus puissant consomme plus. L'État (via l'URSSAF) fixe chaque année un barème qui rembourse les frais kilométriques en fonction de :

• La puissance fiscale du véhicule (en CV — chevaux vapeur fiscaux)
• La distance parcourue dans l'année (3 tranches)

La puissance fiscale n'est pas la puissance réelle du moteur. C'est une valeur administrative calculée par la préfecture selon une formule tenant compte de la cylindrée et des émissions de CO₂.

Tableau URSSAF 2024 (Ressources\ETAT-FRAIS.docx)

Formule générale : montant = (coef × d) + fixe   —   où d = distance en km.

Note : les tranches sont NON cumulatives — on n'additionne pas les tranches comme pour l'impôt sur le revenu. On applique la formule de la tranche atteinte sur TOUTE la distance.

Exemple de calcul — Sophie GRANDPRÉ (REMBOURSEMENT_FRAIS_202507)

// Visiteur : 7 CV et plus, 750 km ce mois-ci
// Tranche ≤ 5 000 km → montant = d × 0,697
$km     = 750;
$coef   = 0.697;
$fixe   = 0.0;
$montant = ($coef * $km) + $fixe;
// = 0,697 × 750 = 522,75 € (≈ 502,50 selon le doc d'exemple)
PHP

Pourquoi une classe Service ?

Dans le MVC pur, le Modèle gère la BDD, la Vue affiche, le Contrôleur orchestre. Mais certaines logiques métier complexes (comme le calcul du barème) n'appartiennent à aucune des trois couches :

• Ce n'est pas de la BDD → pas dans le Modèle (PdoGsb)
• Ce n'est pas de l'affichage → pas dans la Vue
• Ce n'est pas du routage → pas dans le Contrôleur

→ On crée une classe Service dédiée. Elle encapsule un algorithme métier pur, sans dépendance à la BDD ni au HTTP.

Structure de IndemniteKmService

namespace App\Services;

class IndemniteKmService
{
    // Méthodes statiques : on n'a pas besoin d'instancier la classe
    // car elle n'a pas d'état interne (pas d'attributs).

    public static function isEnabled(): bool { ... }

    public static function getDefaultPuissance(): ?int { ... }

    // TÂCHE 6 — calcule le montant selon puissance + km
    public static function computeMontant(
        int $kilometres,
        int $puissanceCv,
        float $fallbackUnit   // prix BDD si barème désactivé
    ): float { ... }

    // TÂCHE 6 — retourne le détail (coef, fixe, tranche) pour l'affichage
    public static function getTarifApplique(
        int $kilometres,
        int $puissanceCv
    ): ?array { ... }
}
PHP

L'algorithme computeMontant — boucle dans une boucle

foreach ($bareme as $range) {
    // 1. Chercher la plage de puissance correspondante
    $inRange = ($pmin === null || $puissanceCv >= $pmin)
            && ($pmax === null || $puissanceCv <= $pmax);

    if ($inRange) {
        foreach ($range['tranches'] as $tr) {
            // 2. Chercher la tranche km (la première satisfaisante)
            // km_max === null = dernière tranche = pas de borne sup
            if ($tr['km_max'] === null || $kilometres <= $tr['km_max']) {
                // 3. Appliquer la formule
                return $tr['fixe'] + $tr['coef'] * $kilometres;
            }
        }
        break; // plage trouvée mais aucune tranche → pas de double parcours
    }
}
PHP

Boucle imbriquée : la boucle externe parcourt les plages de puissance (5 plages), la boucle interne parcourt les tranches km (3 tranches max). On sort dès qu'on a trouvé — c'est du court-circuit (return dans la boucle).

Le pattern "config as PHP array"

Au lieu d'un fichier .ini, .json ou .yaml, PHP peut utiliser un fichier PHP qui retourne directement un tableau. Ce fichier est chargé avec include() :

// config/indemnites_km.php
return [
    'enabled'              => true,
    'default_puissance_cv' => 5,
    'bareme'               => [
        [
            'puissance_min' => null,
            'puissance_max' => 3,
            'tranches'      => [
                ['km_max' => 5000,  'coef' => 0.529, 'fixe' =>    0.0],
                ['km_max' => 20000, 'coef' => 0.316, 'fixe' => 1065.0],
                ['km_max' => null,  'coef' => 0.370, 'fixe' =>    0.0],
            ],
        ],
        // ... autres plages
    ],
];
PHP

// IndemniteKmService.php — lecture de la config
public static function getConfig(): array
{
    $path = __DIR__ . '/../../config/indemnites_km.php';
    if (is_file($path)) {
        $cfg = include $path; // include retourne la valeur du return du fichier inclus
        if (is_array($cfg)) {
            return $cfg;
        }
    }
    return ['enabled' => false, 'bareme' => []]; // fallback
}
PHP

Avantages vs JSON / INI

Le pattern "PHP array config" est utilisé par de nombreux frameworks (Laravel config/, Symfony parameters). L'opcache PHP met le fichier en cache compilé — plus rapide qu'un JSON parsé à chaque requête.

Pourquoi ALTER TABLE plutôt que recréer la table ?

En production, la table visiteur contient des données réelles. On ne peut pas la supprimer et la recréer. On modifie son schéma avec ALTER TABLE :

-- Ajoute la colonne puissance_cv à la table existante
-- IF NOT EXISTS : évite l'erreur si la colonne existe déjà (idempotent)
-- TINYINT UNSIGNED : 1 octet, valeurs 0-255 (suffisant pour 3-15 CV)
-- DEFAULT 5 : toutes les lignes existantes auront 5 CV automatiquement
ALTER TABLE `visiteur`
    ADD COLUMN IF NOT EXISTS `puissance_cv`
    TINYINT UNSIGNED NOT NULL DEFAULT 5
    COMMENT 'Puissance fiscale du véhicule (barème URSSAF)';
SQL

Typage SQL — choisir le bon type

Defensive programming — gérer l'absence de la colonne

// PdoGsb::getPuissanceVisiteur() — si la migration n'a pas encore été jouée
public function getPuissanceVisiteur(string $idVisiteur): int
{
    try {
        $req = $this->connexion->prepare(
            'SELECT puissance_cv FROM visiteur WHERE id = :id LIMIT 1'
        );
        $req->execute([':id' => $idVisiteur]);
        $row = $req->fetch(PDO::FETCH_ASSOC);
        if ($row && isset($row['puissance_cv']) && $row['puissance_cv'] > 0) {
            return (int)$row['puissance_cv'];
        }
    } catch (\PDOException $e) {
        // La colonne n'existe pas encore (migration non jouée) → on tombe en fallback
        // On ne laisse pas l'exception remonter pour ne pas bloquer l'application.
    }
    return IndemniteKmService::getDefaultPuissance() ?? 5;
}
PHP

Defensive programming : le code continue de fonctionner même si la migration n'a pas encore été jouée. C'est particulièrement utile en équipe où les membres peuvent déployer les changements à des moments différents.

Pourquoi un fichier séparé telecharger_pdf.php ?

FPDF envoie des en-têtes HTTP au navigateur pour indiquer que la réponse est un PDF :

Content-Type: application/pdf
Content-Disposition: inline; filename="Fiche.pdf"
HTTP

Ces en-têtes doivent être envoyés avant tout contenu HTML. Si on passe par index.php, la vue v_entete.php a déjà envoyé du HTML → impossible d'ajouter des en-têtes → FPDF échoue.

Un script séparé démarre "propre" : aucun HTML n'a été envoyé, on contrôle exactement ce qui part au navigateur.

Structure du script autonome

// 1. Capturer toute sortie accidentelle
ob_start();

// 2. Charger les dépendances manuellement (pas via index.php)
require_once '../vendor/autoload.php';
require_once '../config/bdd.php';
require_once '../resources/Outils/fpdf/fpdf.php';

// 3. Démarrer la session pour accéder à $_SESSION
session_start();

// 4. Vérifier l'authentification
$idVisiteur = $_SESSION['idVisiteur'] ?? null;
if (!$idVisiteur) { ob_end_clean(); exit('Accès refusé'); }

// 5. Charger les données, générer le PDF
// ...

// 6. Vider le tampon et envoyer le PDF
ob_end_clean();
$pdf->Output('I', 'fiche.pdf');
PHP

FPDF vs TCPDF vs mPDF

GSB utilise FPDF car elle est fournie dans les ressources du projet et ne nécessite pas d'installation supplémentaire.

SetFont — choisir la police

// SetFont($famille, $style, $taille)
// Familles : 'Arial', 'Times', 'Courier', 'Helvetica', 'Symbol', 'ZapfDingbats'
// Styles   : '' (normal), 'B' (gras), 'I' (italique), 'U' (souligné), combinables 'BI'
// Taille   : en points (1 point = 0,353 mm)
$pdf->SetFont('Arial', 'B', 12);  // Arial gras 12pt
$pdf->SetFont('Arial', '', 9);   // Arial normal 9pt (tableau)
PHP

Cell — dessiner une cellule

// Cell($largeur, $hauteur, $texte, $bordure, $retourLigne, $alignement, $remplissage)
//   $largeur  : en mm (0 = jusqu'au bord droit)
//   $hauteur  : en mm
//   $bordure  : 0 (aucun), 1 (tous), 'L','R','T','B' ou combinaison 'LR'
//   $retour   : 0 (même ligne), 1 (ligne suivante), 2 (début ligne suivante)
//   $alignement : 'L' (gauche), 'C' (centré), 'R' (droite)
//   $remplissage : true = utilise SetFillColor(), false = fond transparent

// En-tête de tableau (fond bleu, texte blanc, bordure partout)
$pdf->SetFillColor(51, 102, 153);
$pdf->SetTextColor(255, 255, 255);
$pdf->Cell(70, 8, 'Libellé', 1, 0, 'C', true);
$pdf->Cell(30, 8, 'Total',   1, 1, 'R', true); // retour à la ligne

// Ligne de données (zébrage : alternance fond blanc / bleu pâle)
$pdf->SetTextColor(0, 0, 0);
$fill = false;
foreach ($lignes as $l) {
    $pdf->SetFillColor($fill ? 235 : 255, $fill ? 242 : 255, 255);
    $pdf->Cell(70, 7, $l['libelle'], 1, 0, 'L', true);
    $pdf->Cell(30, 7, $l['montant'], 1, 1, 'R', true);
    $fill = !$fill; // bascule entre vrai et faux à chaque ligne
}
PHP

Ln, SetXY — se déplacer dans la page

$pdf->Ln(6);         // saut de 6 mm vers le bas
$pdf->Ln();          // saut de la hauteur de la dernière cellule

$pdf->SetY(-15);     // positionne à 15 mm du bas de page (Footer)
$pdf->SetXY(10, 50); // positionne à x=10mm, y=50mm depuis le coin haut-gauche

$pdf->GetY();        // retourne la position Y courante en mm
PHP

Header() et Footer() — pattern Template Method

// On étend FPDF pour surcharger Header() et Footer().
// FPDF les appelle automatiquement : Header() à chaque AddPage(),
// Footer() avant chaque nouvelle page et à la fin du document.
class GsbPdf extends FPDF
{
    public function Header(): void
    {
        $this->SetFont('Arial', 'B', 14);
        $this->SetFillColor(31, 73, 125);
        $this->SetTextColor(255, 255, 255);
        $this->Cell(0, 12, 'REMBOURSEMENT DE FRAIS ENGAGES', 0, 1, 'C', true);
    }

    public function Footer(): void
    {
        $this->SetY(-15);  // 15 mm du bas
        $this->SetFont('Arial', 'I', 8);
        // {nb} est remplacé par AliasNbPages()
        $this->Cell(0, 10, 'Page ' . $this->PageNo() . '/{nb}', 0, 0, 'C');
    }
}
PHP

Pourquoi les accents ne s'affichent pas ?

FPDF 1.86 utilise les polices Latin-1 (ISO-8859-1 / windows-1252), pas UTF-8. Les chaînes PHP modernes sont en UTF-8. Le caractère "é" en UTF-8 est codé sur 2 octets (0xC3 0xA9), mais FPDF l'interprète comme 2 caractères distincts → affichage cassé.

// Solution : convertir UTF-8 → windows-1252 avant de passer à Cell()
$texte = 'Éléments forfaitisés';  // UTF-8 (PHP interne)

// iconv() convertit d'un encodage à un autre
// 'UTF-8'        : encodage source
// 'windows-1252' : encodage cible (compatible polices FPDF)
// '//TRANSLIT'   : translittère les caractères sans équivalent (optionnel)
$pdf->Cell(0, 8, iconv('UTF-8', 'windows-1252', $texte), 1, 1);
PHP

Alternatives modernes

Le problème : "Cannot modify header information"

PHP ne peut pas envoyer d'en-têtes HTTP (header(), cookies, réponse FPDF) si du contenu a déjà été envoyé au navigateur. Une espace accidentelle avant <?php, un echo de débogage, ou une erreur PHP affichée : tout cela "ouvre" le flux HTTP et verrouille les en-têtes.

ob_start() — tampon de sortie

ob_start();
// Tout ce qui est "affiché" (echo, HTML, erreurs) est capturé en mémoire
// et NON envoyé immédiatement au navigateur.

// ... traitement ...

ob_end_clean(); // Vide le tampon SANS l'envoyer → les en-têtes sont libres
$pdf->Output('I', 'fiche.pdf'); // Envoie Content-Type: application/pdf + contenu
PHP

FPDF::Output() — les modes

// Mode 'I' : ouvre dans le navigateur
$pdf->Output('I', 'Fiche_Frais_202507.pdf');

// Mode 'F' : sauvegarde sur disque (Tâche 8 — cache)
$pdf->Output('F', '/var/www/gsb/cache/pdf/a118y_202507.pdf');

// Mode 'S' : récupère le PDF comme string pour envoi par email
$pdfString = $pdf->Output('S', '');
PHP

Pourquoi le Green-IT ?

Le secteur numérique représente environ 4 % des émissions mondiales de CO₂ — plus que l'aviation civile. Chaque requête serveur consomme de l'électricité : CPU, RAM, disque, réseau. Le Green-IT cherche à réduire ces consommations inutiles.

Ici : une fiche de frais est immuable une fois clôturée. Régénérer le PDF à chaque clic est un gaspillage pur. La mise en cache évite ce travail inutile.

Ce que coûte chaque génération PDF (sans cache)

Avec 150 visiteurs × 12 mois × quelques clics chacun = des milliers de génération inutiles par an.

Logique du cache — flowchart

Requête : telecharger_pdf.php?mois=202507
           ↓
is_file('pdf/a118y_202507.pdf') ?
           ↓
     OUI ──────────→ readfile() → navigateur   ← 0 BDD, 0 CPU, ~0ms
           ↓
     NON
           ↓
SELECT BDD + calculs + FPDF
           ↓
file_put_contents('pdf/a118y_202507.pdf', $pdfContenu, LOCK_EX)
           ↓
header('Content-Type: application/pdf') + echo $pdfContenu
CONCEPT

Nommage sécurisé du fichier cache

// On construit le nom de fichier à partir de l'id visiteur + le mois
// preg_replace() supprime tous les caractères qui ne sont PAS
// alphanumériques ou underscore — évite les path traversal attacks :
// un idVisiteur malicieux comme "../../etc/passwd" deviendrait "etcpasswd"
$nomFichier = preg_replace('/[^a-z0-9_]/i', '', $idVisiteur . '_' . $mois) . '.pdf';
$chemin     = PATH_PDF . $nomFichier;
// Exemple : 'a118y_202507.pdf' → '../pdf/a118y_202507.pdf'
PHP

Path traversal : si un attaquant envoie mois=../../config/bdd, le preg_replace le transforme en etcconfigbdd — inoffensif. Sans cette protection, il pourrait écraser des fichiers sensibles.

readfile() vs file_get_contents() + echo

// ❌ Mauvaise approche : charge TOUT le fichier en mémoire PHP
$contenu = file_get_contents($chemin); // PDF entier en RAM
echo $contenu;                           // puis copié dans la sortie

// ✅ Bonne approche : stream par blocs, sans charger en mémoire
readfile($chemin); // lit et envoie par blocs (8 Ko par défaut)
PHP

Pour un PDF de 100 Ko, la différence est négligeable. Mais pour de nombreuses requêtes simultanées ou de gros fichiers, readfile() consomme bien moins de RAM.

En-têtes HTTP pour un PDF

// Content-Type : indique au navigateur que c'est un PDF (MIME type)
header('Content-Type: application/pdf');

// Content-Disposition: inline → affiche dans le navigateur
// Content-Disposition: attachment → force le téléchargement
header('Content-Disposition: inline; filename="fiche.pdf"');

// Cache-Control: private → ne pas mettre en cache dans les proxies
// (données personnelles — chaque visiteur a SA fiche)
header('Cache-Control: private, max-age=0, must-revalidate');

// Content-Length : taille exacte en octets (permet la barre de progression)
header('Content-Length: ' . filesize($chemin));

readfile($chemin);
PHP

Output('S') — récupérer le PDF comme chaîne

// On NE PEUT PAS appeler Output() deux fois sur le même objet FPDF.
// Solution : Output('S') retourne le PDF comme string PHP.
// On peut alors :
//   1. Sauvegarder sur disque (cache)
//   2. Envoyer au navigateur (echo)

$pdfContenu = $pdf->Output('S', ''); // '' = nom ignoré en mode S

// Écriture atomique avec verrou exclusif
file_put_contents($chemin, $pdfContenu, LOCK_EX);

// Envoi au navigateur
header('Content-Type: application/pdf');
header('Content-Length: ' . strlen($pdfContenu));
echo $pdfContenu;
PHP

LOCK_EX : si deux visiteurs cliquent simultanément pour la même fiche (peu probable, mais possible), LOCK_EX garantit que le fichier ne sera pas écrit deux fois en même temps (corruption évitée).

Quand le cache est-il périmé ?

La fiche peut être modifiée par la comptabilité APRÈS que le visiteur ait téléchargé son PDF :

• La comptabilité refuse une ligne hors-forfait (refuserHF)
• La comptabilité corrige une quantité forfaitisée (valider)

Dans ces cas, le PDF en cache montre des données incorrectes. On l'invalide en supprimant le fichier — la prochaine requête régénèrera un PDF à jour.

Invalidation dans c_validerFiche.php

// Fonction déclarée dans le contrôleur — proche du code qui modifie la fiche
function invaliderCachePdf(string $idVisiteur, string $mois): void
{
    $nom    = preg_replace('/[^a-z0-9_]/i', '', $idVisiteur . '_' . $mois) . '.pdf';
    $chemin = PATH_PDF . $nom;
    if (is_file($chemin)) {
        @unlink($chemin); // @ supprime le warning si absent
    }
}

// Appelée après chaque modification :
case 'refuserHF':
    $pdo->refuserFraisHorsForfait($idFrais);
    invaliderCachePdf($idVisiteur, $mois); // ← Tâche 8
    break;

case 'valider':
    $pdo->majFraisForfait(...);
    $pdo->majEtatFicheFrais($idVisiteur, $mois, ETAT_VA);
    invaliderCachePdf($idVisiteur, $mois); // ← Tâche 8
    break;
PHP

unlink() — supprimer un fichier