Exercice de Synthèse : Le jeu du pendu

1. Créer toute l'arborescence du projet. Créer un dossier le-jeu-du-pendu. À l'intérieur, créer un sous-dossier data avec un fichier JSON vide nommé dictionnaire.json. Créer un sous-dossier pendu. Dans pendu, créer quatre fichiers PHP vides : outils.php, gestionDuDictionnaire.php, logiqueDuJeu.php, interface.php.

   
                                   📁 le-jeu-du-pendu/
                                   ├── 📁 data/
                                   │   └── 📄 dictionnaire.json
                                   ├── 📁 pendu/
                                   │   ├── 📄 outils.php
                                   │   ├── 📄 gestionDuDictionnaire.php
                                   │   ├── 📄 logiqueDuJeu.php
                                   │   └── 📄 interface.php
                                   └── 📄 index.php
                               

2. Remplir le dictionnaire. Dans data, ouvrir dictionnaire.json et y coller le contenu fourni ci-dessous.

   
                                   {
                                       "nourriture": [
                                           "pomme", "pain", "fromage", "poisson", "poulet",
                                           "salade", "carotte", "tomate", "chocolat", "yaourt",
                                           "jambon", "soupe", "riz", "pates", "haricots",
                                           "fraise", "banane", "raisin", "aubergine", "oignon"
                                       ],
                                       "animaux": [
                                           "chien", "chat", "oiseau", "lion", "elephant",
                                           "tortue", "souris", "serpent", "abeille", "cheval",
                                           "papillon", "poisson", "poule", "gorille", "crocodile",
                                           "dauphin", "girafe", "hippopotame", "pingouin", "koala"
                                       ],
                                       "professions": [
                                           "medecin", "enseignant", "policier", "avocat", "boulanger",
                                           "coiffeur", "architecte", "infirmier", "plombier", "photographe",
                                           "artiste", "cuisinier", "journaliste", "electricien", "veterinaire",
                                           "facteur", "agriculteur", "musicien", "acteur", "ingenieur"
                                       ],
                                       "sciences": [
                                           "physique", "chimie", "biologie", "mathematiques", "astronomie",
                                           "geologie", "informatique", "medecine", "psychologie", "sociologie",
                                           "anthropologie", "ecologie", "botanique", "zoologie", "economie",
                                           "linguistique", "archeologie", "pharmacologie", "astrophysique", "entomologie"
                                       ]
                                   }
                               

3. Créer index.php à la racine. Ce fichier servira de script de test tout au long du projet. C'est ici qu'on appellera chaque fonction pour vérifier qu'elle fonctionne correctement avant de passer à la suivante.
4. Activer le typage strict. En haut de index.php, après la balise d'ouverture PHP, écrire declare(strict_types=1);. Pourquoi ? Le typage strict empêche PHP de convertir silencieusement les types. Si on envoie un nombre là où une chaîne est attendue, PHP affichera une erreur au lieu de deviner. Cela évite des bugs difficiles à repérer.
5. Ajouter un message de test. Utiliser echo pour afficher "Le projet est prêt." suivi de PHP_EOL (constante de retour à la ligne).
6. Exécuter le script. Dans le terminal, se placer à la racine du projet et lancer php ./index.php. Le message doit s'afficher. Si ce n'est pas le cas, vérifier que PHP est bien installé et que le chemin est correct.

2.1 : Préparer index.php

1. Remplacer le message de test de l'étape 1 par le vrai contenu. Garder la balise d'ouverture PHP et declare(strict_types=1);.
2. Inclure pendu/interface.php avec require_once en utilisant __DIR__ . '/pendu/interface.php'.
3. Appeler lancerJeu en lui passant __DIR__ . '/data/dictionnaire.json'. Ce sera le point d'entrée unique du jeu.

2.2 : Préparer pendu/interface.php

4. Ouvrir pendu/interface.php. Activer le typage strict. Inclure les trois autres fichiers du dossier pendu avec require_once en utilisant __DIR__ : __DIR__ . '/outils.php', __DIR__ . '/gestionDuDictionnaire.php', __DIR__ . '/logiqueDuJeu.php'. Pourquoi require_once et pas require ? Parce que require_once garantit qu'un fichier n'est inclus qu'une seule fois, même si plusieurs fichiers tentent de l'inclure. Cela évite des erreurs de redéclaration de fonctions.
5. Créer la fonction lancerJeu. Elle reçoit un paramètre $cheminDictionnaire de type string et ne retourne rien (void).
6. Écrire uniquement la première ligne du corps : appeler chargerDictionnaire en lui passant $cheminDictionnaire. Stocker le résultat dans $dictionnaire.

1. Ouvrir pendu/gestionDuDictionnaire.php et activer le typage strict.
2. Créer la fonction chargerDictionnaire. Elle reçoit $chemin (string). Elle retourne ?array (soit un tableau, soit null). Le ? devant le type signifie que null est aussi une valeur de retour possible.
3. Vérifier que le fichier existe et est lisible. Appeler file_exists en lui passant $chemin. Appeler aussi is_readable en lui passant $chemin. Si l'une des deux échoue (vérifier avec !), retourner null. Pourquoi les deux ? Un fichier peut exister sans être lisible (par exemple si les permissions du système l'interdisent).
4. Lire le contenu du fichier. Appeler file_get_contents en lui passant $chemin. Stocker le résultat dans $contenu. Cette fonction lit tout le fichier d'un coup et retourne son contenu sous forme de chaîne. Si la lecture échoue, elle retourne false. Vérifier avec === si $contenu vaut false, et si oui, retourner null.
5. Décoder le JSON. Appeler json_decode avec deux arguments : $contenu et true. Le second argument true demande à PHP de créer un tableau associatif plutôt qu'un objet. Stocker le résultat dans $dictionnaire.
6. Vérifier que le résultat est valide. Avec is_array, vérifier que c'est bien un tableau (et pas null si le JSON était malformé). Avec count, vérifier qu'il n'est pas vide. Si l'une des deux vérifications échoue, retourner null.
7. Retourner $dictionnaire.

Compléter et tester lancerJeu

8. Revenir dans lancerJeu (dans pendu/interface.php). Après l'appel à chargerDictionnaire, ajouter la vérification : si $dictionnaire vaut null, arrêter avec exit(1). Le chiffre 1 signale une erreur au système.
9. Ajouter un echo temporaire après la vérification pour afficher le dictionnaire avec print_r($dictionnaire). Cela permet de vérifier que le chargement fonctionne.
10. Exécuter php ./index.php. Les 4 catégories avec leurs mots doivent s'afficher. Tester aussi avec un chemin inexistant dans index.php pour vérifier que le programme s'arrête.
11. Supprimer le echo temporaire une fois le test réussi.

4.1 : obtenirCategories

1. Dans pendu/gestionDuDictionnaire.php, créer la fonction. Elle reçoit $dictionnaire (array), retourne un array.
2. Extraire les clés en appelant array_keys sur $dictionnaire. Retourner directement le résultat. Pourquoi les clés ? Dans notre dictionnaire JSON, les clés du tableau associatif sont les noms de catégories ('nourriture', 'animaux', etc.).
3. Tester dans index.php : charger le dictionnaire, appeler obtenirCategories, afficher avec print_r. On doit obtenir nourriture, animaux, professions, sciences.

4.2 : selectionnerCategorie

Le joueur pourra choisir une catégorie de trois façons : en tapant un numéro (ex. : '2'), en tapant le nom (ex. : 'animaux'), ou en tapant 'hasard' ou '0' pour un choix aléatoire. Cette fonction interprète ce choix et retourne le nom de la catégorie correspondante, ou null si le choix est invalide.

4. Créer la fonction. Elle reçoit $dictionnaire (array) et $choix (string). Elle retourne ?string.
5. Récupérer la liste des catégories en appelant obtenirCategories avec $dictionnaire. Stocker dans $categories.
6. Gérer le choix aléatoire. Si $choix vaut 'hasard' ou '0', appeler array_rand en lui passant $categories pour obtenir un index aléatoire. Retourner l'élément de $categories à cet index.
7. Gérer un numéro. Vérifier avec is_numeric si $choix est un nombre. Si oui, convertir en entier avec (int)$choix et soustraire 1 pour obtenir l'index. Pourquoi soustraire 1 ? Parce que le menu affichera les catégories à partir de 1, mais les index PHP commencent à 0. Stocker dans $index. Si $index est entre 0 et count($categories) - 1, retourner $categories[$index]. Sinon, retourner null.
8. Gérer un nom de catégorie. Appeler in_array en lui passant $choix et $categories. Si trouvé, retourner $choix.
9. Sinon, retourner null.
10. Tester : '1' → nourriture, 'sciences' → sciences, '99' → NULL, 'hasard' → aléatoire, '0' → aléatoire.

4.3 : afficherMenuCategories

11. Dans pendu/interface.php, créer la fonction. Reçoit $categories (array). Retourne void.
12. Afficher un en-tête : une ligne vide, puis === JEU DU PENDU ===, une ligne vide, Choisissez une catégorie :, une ligne vide, puis 0. hasard (catégorie aléatoire).
13. Parcourir $categories avec une boucle for. À chaque tour, afficher le numéro ($i + 1) suivi d'un point et du nom. Ex. : 1. nourriture.
14. Terminer par une ligne vide.

4.4 : Assembler demanderCategorie

15. Dans pendu/interface.php, créer demanderCategorie. Reçoit $dictionnaire (array). Retourne string.
16. Récupérer les catégories avec obtenirCategories($dictionnaire).
17. Créer une boucle while (true) qui tourne jusqu'à un choix valide :
    • Appeler afficherMenuCategories.
    • Afficher Votre choix : (sans retour à la ligne).
    • Lire la saisie avec readline(). Stocker dans $ligne. readline attend que l'utilisateur tape quelque chose et appuie sur Entrée. Si l'utilisateur fait Ctrl+D (ce qui ferme le flux d'entrée du terminal, signalant qu'il veut quitter), readline retourne false. Dans ce cas, afficher Partie interrompue. et arrêter avec exit(0).
    • Nettoyer avec trim. Stocker dans $choix.
    • Appeler selectionnerCategorie avec le dictionnaire et le choix. Stocker dans $categorie.
    • Si $categorie n'est pas null, retourner $categorie.
    • Sinon, afficher un message d'erreur et la boucle recommence.

Compléter et tester lancerJeu

18. Revenir dans lancerJeu. Après le chargement et la vérification du dictionnaire, ajouter : $categorie = demanderCategorie($dictionnaire);.
19. Ajouter un echo temporaire pour afficher la catégorie choisie.
20. Exécuter php ./index.php. Le menu doit s'afficher. Tester : numéro valide, nom, hasard, 0, choix invalide (la boucle redemande).
21. Supprimer le echo temporaire.

tirerMotAuHasard

1. Dans pendu/gestionDuDictionnaire.php, créer la fonction. Reçoit $dictionnaire (array) et $categorie (string). Retourne ?string.
2. Vérifier que la catégorie existe. Appeler isset avec $dictionnaire[$categorie]. Si non, retourner null.
3. Récupérer les mots. Stocker $dictionnaire[$categorie] dans $mots. Vérifier avec is_array et count que c'est un tableau non vide. Sinon, retourner null. Pourquoi ? On ne contrôle pas le contenu du fichier JSON : une catégorie pourrait être vide.
4. Tirer au hasard. Appeler array_rand en lui passant $mots. Retourner le mot à cet index.
5. Tester avec 'animaux' (le mot change) et 'sports' (retourne NULL).

Compléter et tester lancerJeu

6. Revenir dans lancerJeu. Ajouter $mot = tirerMotAuHasard($dictionnaire, $categorie);. Si $mot vaut null, arrêter avec exit(1).
7. Ajouter un echo temporaire pour afficher le mot tiré.
8. Exécuter, vérifier qu'un mot de la catégorie choisie s'affiche, puis supprimer le echo temporaire.

1. Revenir dans lancerJeu. Ajouter la dernière ligne : jouer($mot, $categorie);.
2. Dans pendu/interface.php, créer la fonction jouer. Elle reçoit $mot (string) et $categorie (string). Retourne void.
3. Écrire uniquement la première ligne du corps : appeler initialiserJeu en lui passant $mot et $categorie. Stocker le résultat dans $etat.

Ouvrir pendu/outils.php et activer le typage strict.

7.1 : normaliserLettre

Le joueur peut saisir en majuscule ou minuscule. Pour comparer, on ramène tout en minuscule. C'est la fonction la plus simple du projet, mais elle sera utilisée partout.

1. Créer la fonction. Reçoit $lettre (string), retourne string.
2. Appeler strtolower en lui passant $lettre. Retourner directement le résultat. Cette fonction transforme chaque majuscule en minuscule. Les caractères déjà en minuscule ne sont pas affectés.
3. Tester : 'A' → a, 'z' → z, 'BONJOUR' → bonjour.

7.2 : estLettreValide

Le joueur pourrait taper un chiffre, un symbole ou plusieurs caractères. Il faut vérifier que c'est une seule lettre de a à z.

1. Créer la fonction. Reçoit $input (string), retourne bool.
2. Vérifier la longueur. Appeler strlen en lui passant $input. Si le résultat n'est pas 1, retourner false.
3. Normaliser avec normaliserLettre($input). Stocker dans $lettre.
4. Vérifier entre 'a' et 'z'. Retourner $lettre >= 'a' && $lettre <= 'z'. En PHP, on peut comparer des caractères : cela compare leur position dans la table ASCII.
5. Tester : 'a' → true, 'Z' → true, '3' → false, 'ab' → false, '' → false, '!' → false.

7.3 : lettreDejaProposee

On ne veut pas que le joueur perde une vie en reproposant une lettre déjà tentée.

1. Créer la fonction. Reçoit $lettre (string) et $lettresProposees (array). Retourne bool.
2. Normaliser $lettre avec normaliserLettre. Stocker dans $lettreNormalisee.
3. Parcourir $lettresProposees avec foreach. À chaque tour, normaliser la lettre du tableau. Si elle est identique à $lettreNormalisee, retourner true.
4. Après la boucle, retourner false.
5. Tester avec ['a','b','c'] : 'a' → true, 'A' → true, 'd' → false.

7.4 : compterLettresDifferentes

Compte le nombre de lettres distinctes dans un mot. "banane" contient 4 lettres différentes (b, a, n, e). Servira à adapter le nombre de vies à la difficulté du mot.

1. Créer la fonction. Reçoit $mot (string), retourne int.
2. Créer un tableau vide $lettres. L'astuce : on utilise un tableau associatif où chaque lettre sert de clé et la valeur est true. Si la même lettre apparaît deux fois, elle écrase la précédente sans créer de doublon. Pourquoi ? Un tableau associatif ne peut avoir qu'une seule entrée par clé.
3. Récupérer la longueur avec strlen. Stocker dans $longueur.
4. Parcourir chaque caractère avec une boucle for de 0 à $longueur - 1. Accéder au caractère avec $mot[$i]. Normaliser avec normaliserLettre. Stocker dans $lettre. Ajouter : $lettres[$lettre] = true;.
5. Retourner count($lettres).
6. Tester : 'banane' → 4, 'hippopotame' → 8, 'chat' → 4, 'aaa' → 1.

Ouvrir pendu/logiqueDuJeu.php, activer le typage strict, et inclure outils.php avec require_once __DIR__ . '/outils.php'.

8.1 : calculerVies

1. Créer la fonction. Reçoit $mot (string), retourne int.
2. Récupérer la longueur avec strlen. Stocker dans $longueur.
3. Compter les lettres différentes en appelant compterLettresDifferentes. Stocker dans $lettresDifferentes.
4. Calculer : additionner $longueur et $lettresDifferentes, diviser par 2, convertir en entier avec (int), ajouter 2. Stocker dans $vies.
5. Appliquer plancher et plafond. Si $vies < 5, le mettre à 5. Si > 12, le mettre à 12.
6. Retourner $vies.
7. Tester : 'riz' → 5, 'mathematiques' → 12.

8.2 : initialiserJeu

8. Créer la fonction. Reçoit $mot (string) et $categorie (string). Retourne array.
9. Normaliser le mot avec normaliserLettre($mot). Stocker dans $motNormalise.
10. Calculer les vies avec calculerVies($motNormalise). Stocker dans $vies.
11. Construire et retourner le tableau :
    • 'mot' → $motNormalise
    • 'categorie' → $categorie
    • 'vies' → $vies (diminuera à chaque erreur)
    • 'viesMax' → $vies (valeur initiale, pour l'affichage « 5/8 »)
    • 'lettresProposees' → []
    • 'lettresTrouvees' → []
    • 'tour' → 1
    • 'termine' → false
    • 'victoire' → false
12. Tester : initialiserJeu('ELEPHANT', 'animaux'). Vérifier que 'mot' vaut 'elephant', que les vies sont identiques, que les tableaux sont vides.

Tester dans jouer

13. Revenir dans jouer. Après $etat = initialiserJeu($mot, $categorie);, ajouter un echo temporaire avec print_r($etat).
14. Ajouter le message de début : === DÉBUT DE LA PARTIE ===, la catégorie et le nombre de vies.
15. Exécuter, vérifier que l'état s'affiche correctement, puis supprimer le echo temporaire.

9.1 : afficherMotMasque

Génère une chaîne où les lettres trouvées sont visibles et les autres remplacées par des tirets (ex. : c-a-).

1. Dans pendu/logiqueDuJeu.php, créer la fonction. Reçoit $etat (array), retourne string.
2. Récupérer le mot depuis $etat['mot']. Créer un index avec array_flip($etat['lettresTrouvees']). Stocker dans $index. array_flip inverse clés et valeurs : ['c','a'] devient ['c'=>0, 'a'=>1]. L'intérêt : vérifier l'existence d'une lettre avec isset($index['c']) est très rapide.
3. Construire l'affichage. Créer $affichage vide. Parcourir chaque caractère du mot avec for. Si la lettre est dans l'index, l'ajouter. Sinon, ajouter '-'. On peut utiliser l'opérateur ternaire : $affichage .= isset($index[$mot[$i]]) ? $mot[$i] : '-';
4. Retourner $affichage.

9.2 : afficherEtatJeu

5. Dans pendu/interface.php, créer la fonction. Reçoit $etat (array). Retourne void.
6. Afficher :
   • Une ligne de séparation de 50 signes = avec str_repeat('=', 50).
   • Le tour, la catégorie, les vies restantes (format : 5 / 8).
   • Les lettres proposées : si le tableau n'est pas vide, les joindre avec implode(', ', $etat['lettresProposees']). Sinon, afficher aucune.
   • Le mot masqué : afficherMotMasque($etat).
   • Une ligne de séparation pour fermer.

9.3 : demanderLettre

7. Dans pendu/interface.php, créer la fonction. Reçoit $etat (array). Retourne string.
8. Créer une boucle while (true).
   • Afficher Proposez une lettre : .
   • Lire avec readline(). Si false (Ctrl+D), afficher Partie interrompue. et exit(0).
   • Nettoyer avec trim. Stocker dans $input.
9. Vérifier les erreurs dans l'ordre (à chaque erreur, afficher un message et continue pour relancer la boucle) :
   • Si $input est vide : Erreur : Vous devez saisir une lettre.
   • Si strlen($input) > 1 : Erreur : Veuillez saisir une seule lettre à la fois.
   • Si estLettreValide($input) est false : Erreur : Veuillez saisir uniquement des lettres de a à z.
   • Si lettreDejaProposee($input, $etat['lettresProposees']) est true : Erreur : Vous avez déjà proposé cette lettre.
10. Si tout passe, retourner $input.

Ajouter dans jouer et tester

11. Revenir dans jouer. Après le message de début, écrire while (!$etat['termine']). Dans la boucle, écrire les deux premières lignes : afficherEtatJeu($etat); et $lettre = demanderLettre($etat);. Ajouter un echo temporaire pour afficher la lettre saisie, puis un break; pour sortir de la boucle après un seul tour (temporaire).
12. Exécuter. On doit voir l'état du jeu (avec des tirets), pouvoir taper une lettre, et voir la lettre s'afficher. Tester les cas d'erreur (vide, chiffre, symbole). Supprimer le echo et le break.

10.1 : lettreDansMot

1. Dans pendu/logiqueDuJeu.php, créer la fonction. Reçoit $lettre (string) et $mot (string). Retourne bool.
2. Chercher la lettre. Appeler strpos avec $mot et normaliserLettre($lettre). Retourner strpos(...) !== false. Piège classique : utiliser !== et non !=. Si la lettre est en position 0, strpos retourne 0 et 0 != false vaut false en PHP. Avec !==, PHP vérifie aussi le type : 0 !== false vaut true.
3. Tester : ('c','chat') → true, ('z','chat') → false, ('C','chat') → true.

10.2 : motComplete

4. Créer la fonction. Reçoit $etat (array), retourne bool.
5. Récupérer le mot. Créer un index avec array_flip($etat['lettresTrouvees']).
6. Parcourir chaque caractère avec for. Si une lettre n'est pas dans l'index (!isset), retourner false.
7. Après la boucle, retourner true.

10.3 : traiterProposition

En PHP, un tableau passé en paramètre est une copie. Les modifications dans la fonction n'affectent pas l'original. On retourne donc le tableau modifié.

8. Créer la fonction. Reçoit $etat (array) et $lettre (string). Retourne array (clés 'etat' et 'correcte').
9. Normaliser la lettre. Stocker dans $lettreNormalisee.
10. Gérer le doublon. Si la lettre est déjà dans $etat['lettresProposees'] (in_array), retourner l'état inchangé avec 'correcte' valant lettreDansMot(...).
11. Ajouter aux propositions : $etat['lettresProposees'][] = $lettreNormalisee;
12. Si dans le mot : ajouter à lettresTrouvees si absente. Appeler motComplete. Si complet, mettre termine et victoire à true. Retourner ['etat' => $etat, 'correcte' => true].
13. Si pas dans le mot : décrémenter $etat['vies']. Si vies ≤ 0, mettre termine à true, victoire à false. Retourner ['etat' => $etat, 'correcte' => false].
14. Tester : initialiser avec 'chat'. Récupérer l'état à chaque appel ($etat = $resultat['etat'];). Proposer 'c' (correcte), 'z' (incorrecte, vies - 1), reproposer 'c' (doublon, état inchangé).

11.1 : tourSuivant

1. Dans pendu/logiqueDuJeu.php, créer la fonction. Reçoit $etat (array). Retourne array.
2. Incrémenter $etat['tour'] avec ++.
3. Retourner $etat. L'appelant fera $etat = tourSuivant($etat);.

11.2 : afficherFinPartie

4. Dans pendu/interface.php, créer la fonction. Reçoit $etat (array). Retourne void.
5. Afficher : une ligne de séparation ; si $etat['victoire'] est true, afficher VICTOIRE ! Vous avez trouvé le mot ! ; sinon DÉFAITE ! Vous avez épuisé toutes vos vies. ; dans les deux cas, afficher Le mot était : suivi de $etat['mot'] ; une ligne de séparation.

12.1 : Compléter la boucle dans jouer

1. Revenir dans la boucle while de jouer. Après $lettre = demanderLettre($etat);, ajouter les lignes suivantes :
2. Traiter la proposition : appeler traiterProposition($etat, $lettre). Stocker le résultat dans $resultat. Puis mettre à jour l'état : $etat = $resultat['etat'];. C'est essentiel car la fonction travaille sur une copie.
3. Afficher le feedback : si $resultat['correcte'] est true, afficher "Bonne lettre !". Sinon, afficher "Mauvaise lettre ! Vous perdez 1 vie.".
4. Passer au tour suivant : si la partie n'est pas terminée (!$etat['termine']), appeler tourSuivant($etat) et stocker le résultat dans $etat.
5. Après la boucle, appeler afficherFinPartie($etat);.

12.2 : Tester le jeu complet

6. Exécuter php ./index.php depuis la racine du projet.
7. Choisir une catégorie et jouer une partie complète en vérifiant :
   • Proposer une bonne lettre → "Bonne lettre !" et le mot masqué se complète.
   • Proposer une mauvaise lettre → "Mauvaise lettre !" et les vies diminuent.
   • Reproposer une lettre déjà proposée → message d'erreur, pas de perte de vie.
   • Taper un chiffre, un symbole ou plusieurs lettres → message d'erreur approprié.
   • Gagner une partie (trouver toutes les lettres).
   • Perdre une partie (épuiser toutes les vies).
8. Relancer plusieurs parties pour tester différentes catégories et l'option hasard.