1. ¿Qué es Prophecy y para qué sirve?

Prophecy es una potente librería orientada a objetos para crear mocks (objetos simulados) en PHP. Ofrece una API elegante, expresiva y flexible para generar stubs, spies y objetos falsos que imitan el comportamiento de dependencias reales en pruebas unitarias. A diferencia de otras librerías, Prophecy se basa en el concepto de "profecía" (prophecy): tú describes cómo debería comportarse un objeto y la librería genera automáticamente la implementación.

El objetivo principal de Prophecy es hacer que escribir pruebas unitarias sea lo más simple y legible posible. En lugar de crear manualmente objetos mock complejos con montones de configuraciones, simplemente "declaras una profecía" para la clase o interfaz deseada, y luego invocas los métodos que deberían ejecutarse en el código bajo prueba. Prophecy verifica automáticamente si las llamadas reales coinciden con tus expectativas.

Esta librería es especialmente útil al probar código que depende de servicios externos (bases de datos, APIs, sistema de archivos), objetos complejos u objetos con efectos secundarios. Prophecy permite aislar el código bajo prueba, reemplazando las dependencias reales con simulaciones predecibles. Es el estándar de facto para muchos frameworks PHP, incluyendo Symfony y Laravel, y se utiliza en proyectos populares como Doctrine y PHPUnit (a través de su integración).

2. Instalación

Prophecy se instala mediante Composer, el gestor de dependencias estándar de PHP. Ejecuta el siguiente comando en la raíz de tu proyecto:

composer require --dev phpspec/prophecy

La bandera --dev indica que la librería se añadirá solo en la sección require-dev de tu archivo composer.json, ya que Prophecy es necesaria exclusivamente para pruebas y no debe usarse en el entorno de producción.

Si usas PHPUnit, también se recomienda instalar el paquete de integración para que Prophecy funcione automáticamente:

composer require --dev phpspec/prophecy-phpunit

Después de la instalación, asegúrate de que el archivo vendor/autoload.php esté incluido en tu archivo de pruebas (normalmente PHPUnit lo hace automáticamente).

3. Inicio rápido — ejemplo mínimo funcional

Escribamos una prueba sencilla usando Prophecy. Supongamos que tenemos una clase UserMailer que envía un correo de bienvenida a un nuevo usuario. Esta clase depende de la interfaz MailerInterface.

<?php
// Clases a probar
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,
            '¡Bienvenido!',
            '¡Gracias por unirte!'
        );
    }
}

// Prueba con Prophecy
use Prophecy\PhpUnit\ProphecyTrait;
use PHPUnit\Framework\TestCase;

class UserMailerTest extends TestCase {
    use ProphecyTrait;
    
    public function testSendWelcomeEmail() {
        // 1. Creamos una profecía para MailerInterface
        $mailerProphecy = $this->prophesize(MailerInterface::class);
        
        // 2. Declaramos la expectativa: el método send se llamará una vez con argumentos específicos
        $mailerProphecy->send('user@example.com', '¡Bienvenido!', '¡Gracias por unirte!')
            ->willReturn(true);
        
        // 3. Obtenemos el objeto mock a partir de la profecía
        $mailerMock = $mailerProphecy-