1. Qu'est-ce que Prophecy et pourquoi l'utiliser ?

Prophecy est une bibliothèque orientée objet puissante pour créer des mocks (objets simulés) en PHP. Elle offre une API élégante, expressive et flexible pour générer des bouchons de test, des espions et des objets factices qui imitent le comportement de dépendances réelles dans les tests unitaires. Contrairement à d'autres bibliothèques, Prophecy se concentre sur la "prophétie" — vous décrivez comment un objet doit se comporter, et la bibliothèque génère automatiquement l'implémentation.

L'objectif principal de Prophecy est de rendre l'écriture de tests unitaires aussi simple et lisible que possible. Au lieu de créer manuellement des objets mock complexes avec une multitude de configurations, vous "déclarez une prophétie" pour la classe ou l'interface souhaitée, puis vous appelez les méthodes qui doivent être invoquées dans le code testé. Prophecy vérifie automatiquement si les appels réels correspondent à vos attentes.

Cette bibliothèque est particulièrement utile pour tester du code qui dépend de services externes (bases de données, API, système de fichiers), d'objets complexes ou d'objets avec des effets de bord. Prophecy permet d'isoler le code testé en remplaçant les dépendances réelles par des bouchons prévisibles. C'est un standard de facto pour de nombreux frameworks PHP, notamment Symfony et Laravel, et il est utilisé dans des projets populaires comme Doctrine et PHPUnit (via une intégration).

2. Installation

Prophecy s'installe via Composer, le gestionnaire de dépendances standard pour PHP. Exécutez la commande suivante à la racine de votre projet :

composer require --dev phpspec/prophecy

Le flag --dev indique que la bibliothèque sera ajoutée uniquement dans la section require-dev de votre fichier composer.json, car Prophecy est nécessaire exclusivement pour les tests et ne doit pas être utilisée en environnement de production.

Si vous utilisez PHPUnit, il est recommandé d'installer également le paquet d'intégration pour une compatibilité automatique avec Prophecy :

composer require --dev phpspec/prophecy-phpunit

Après l'installation, assurez-vous que le fichier vendor/autoload.php est inclus dans votre fichier de test (cela se fait généralement automatiquement avec PHPUnit).

3. Démarrage rapide — exemple minimal fonctionnel

Écrivons un test simple avec Prophecy. Supposons que nous ayons une classe UserMailer qui envoie un e-mail de bienvenue à un nouvel utilisateur. Elle dépend de l'interface MailerInterface.

<?php
// Classes à tester
interface MailerInterface {
    public function send(string $to, string $subject, string $body): bool;
}

class UserMailer {
    private $mailer;
    
    public function __construct(MailerInterface $mailer) {
        $this->mailer = $mailer;
    }
    
    public function sendWelcomeEmail(string $email): bool {
        return $this->mailer->send(
            $email,
            'Bienvenue !',
            'Merci de nous avoir rejoints !'
        );
    }
}

// Test avec Prophecy
use Prophecy\PhpUnit\ProphecyTrait;
use PHPUnit\Framework\TestCase;

class UserMailerTest extends TestCase {
    use ProphecyTrait;
    
    public function testSendWelcomeEmail() {
        // 1. Créer une prophétie pour MailerInterface
        $mailerProphecy = $this->prophesize(MailerInterface::class);
        
        // 2. Déclarer une attente : la méthode send sera appelée une fois avec des arguments spécifiques
        $mailerProphecy->send('user@example.com', 'Bienvenue !', 'Merci de nous avoir rejoints !')
            ->willReturn(true);
        
        // 3. Obtenir l'objet mock à partir de la prophétie
        $mailerMock = $mailerProphecy->reveal();
        
        // 4. Injecter le mock dans la classe à tester
        $userMailer = new UserMailer($mailerMock);
        
        // 5. Exécuter la méthode à tester
        $result = $userMailer->sendWelcomeEmail('user@example.com');
        
        // 6. Vérifier le résultat
        $this->assertTrue($result);
        
        // 7. Prophecy vérifie automatiquement que toutes les prophéties ont été réalisées
    }
}
?>

Ce test vérifie que la méthode sendWelcomeEmail appelle correctement la méthode send du service de messagerie avec les bons arguments et retourne le résultat attendu. Prophecy valide automatiquement que l'appel a bien eu lieu.