Aller au contenu principal

Les annotations

Notions théoriques​

Les annotations sont des métadonnées que vous pouvez ajouter à votre code pour fournir des informations supplémentaires sur le comportement de votre code. En PHP, les annotations sont généralement ajoutées sous forme de commentaires docblock, qui sont des commentaires multi-lignes qui commencent par /** et se terminent par */.

PHP 8 a introduit un support natif pour les annotations (appelées attributs), mais avant PHP 8, les annotations étaient souvent utilisées dans le cadre de bibliothèques externes comme phpDocumentor ou Doctrine.

Les annotations PHPDoc sont une forme courante d'annotations en PHP. Elles sont utilisées pour documenter votre code, en indiquant le type des variables, des paramètres de fonction, des valeurs de retour, et en fournissant une description de ce que fait votre code.

Exemple pratique​

Voici un exemple simple d'utilisation des annotations PHPDoc pour documenter notre classe Character dans notre jeu de combat.

<?php

/**
 * Classe représentant un personnage dans notre jeu de combat.
 */
class Character {
    /**
     * Le nom du personnage.
     *
     * @var string
     */
    public $name;

    /**
     * Les points de vie du personnage.
     *
     * @var int
     */
    public $hp;

    /**
     * La force d'attaque du personnage.
     *
     * @var int
     */
    public $attack;

    /**
     * Crée un nouveau personnage.
     *
     * @param string $name Le nom du personnage.
     * @param int $hp Les points de vie du personnage.
     * @param int $attack La force d'attaque du personnage.
     */
    public function __construct($name, $hp, $attack) {
        $this->name = $name;
        $this->hp = $hp;
        $this->attack = $attack;
    }

    /**
     * Vérifie si le personnage est vivant.
     *
     * @return bool True si le personnage est vivant, false sinon.
     */
    public function isAlive() {
        return $this->hp > 0;
    }
}

Test de mémorisation/compréhension​


Qu'est-ce qu'une annotation en PHP ?


Quelle est la syntaxe pour un commentaire docblock en PHP ?


PHP a-t-il un support natif pour les annotations ?


À quoi servent les annotations PHPDoc ?


Où place-t-on les annotations en PHP ?


TP pour réfléchir et résoudre des problèmes​

Dans ce TP, vous allez créer une nouvelle classe Fight qui va gérer un combat entre deux personnages de notre jeu.

Vous allez utiliser les annotations PHPDoc pour documenter cette classe, ses propriétés et ses méthodes.

Voici la classe Character que vous pouvez utiliser pour le TP :

<?php

class Character {
    public string $name;
    public int $hp;
    public int $attack;

    public function __construct(string $name, int $hp, int $attack) {
        $this->name = $name;
        $this->hp = $hp;
        $this->attack = $attack;
    }

    public function isAlive(): bool {
        return $this->hp > 0;
    }
}

Consignes :

  1. Créez une nouvelle classe Fight dans un nouveau fichier Fight.php.

  2. Ajoutez 2 propriétés à la classe Fight : character1 et character2. Ces propriétés représenteront les deux personnages qui vont se battre.

  3. Annoter ces 2 propriétés avec PHPDoc pour indiquer qu'elles sont de type Character.

  4. Créez une méthode start() qui va lancer le combat entre les deux personnages. Cette méthode doit retourner le personnage qui a gagné le combat.

    Ici, on suppose que le premier personnage gagne toujours, dans une vraie application, vous auriez une logique pour déterminer le vainqueur.

  5. Annoter cette méthode avec PHPDoc pour indiquer qu'elle retourne un objet de type Character.

  6. Ajoutez une annotation @package CombatGame à votre classe pour indiquer qu'elle fait partie de notre jeu de combat.

  7. Ensuite, créez un fichier testFight.php pour tester votre classe Fight.

    • Incluez les fichiers Character.php et Fight.php dans le fichier testFight.php.
    • Créez deux nouveaux personnages.
    • Créez un nouveau combat avec ces deux personnages.
    • Lancez le combat et affichez le vainqueur.
    <?php

    require_once 'Character.php';
    require_once 'Fight.php';

    $character1 = new Character('Guerrier', 100, 20);
    $character2 = new Character('Monstre', 80, 15);

    $fight = new Fight($character1, $character2);

    $winner = $fight->start();
    print("Le vainqueur est : " . $winner->name);
Une solution