1. O que é e para que serve

Prophecy é uma biblioteca poderosa e orientada a objetos para criar mocks (objetos simulados) em PHP. Ela oferece uma API elegante, expressiva e flexível para criar stubs, spies e objetos falsos que imitam o comportamento de dependências reais em testes unitários. Diferente de muitas outras bibliotecas, Prophecy foca no conceito de "profecia" (prophecy) — você descreve como o objeto deve se comportar, e a biblioteca gera automaticamente a implementação.

O principal objetivo do Prophecy é tornar a escrita de testes unitários o mais simples e legível possível. Em vez de criar manualmente objetos mock complexos com várias configurações, você simplesmente "declara uma profecia" para a classe ou interface desejada e, em seguida, chama os métodos que devem ser invocados no código testado. O Prophecy verifica automaticamente se as chamadas reais correspondem às suas expectativas.

A biblioteca é especialmente útil ao testar código que depende de serviços externos (banco de dados, APIs, sistema de arquivos), objetos complexos ou objetos com efeitos colaterais. Prophecy permite isolar o código testado, substituindo dependências reais por stubs previsíveis. Ela é o padrão de facto para muitos frameworks PHP, incluindo Symfony e Laravel, e é usada em projetos populares como Doctrine e PHPUnit (através de integração).

2. Instalação

Prophecy é instalado via Composer, o gerenciador de dependências padrão do PHP. Execute o seguinte comando na raiz do seu projeto:

composer require --dev phpspec/prophecy

A flag --dev indica que a biblioteca será adicionada apenas na seção require-dev do seu composer.json, já que Prophecy é necessária exclusivamente para testes e não deve ser usada em ambiente de produção.

Se você usa PHPUnit, é recomendável instalar também o pacote de integração para funcionamento automático com Prophecy:

composer require --dev phpspec/prophecy-phpunit

Após a instalação, certifique-se de que o arquivo vendor/autoload.php está incluído no seu arquivo de teste (geralmente isso é feito automaticamente no PHPUnit).

3. Início rápido — exemplo mínimo funcional

Vamos escrever um teste simples usando Prophecy. Suponha que temos uma classe UserMailer que envia um e-mail de boas-vindas para um novo usuário. Ela depende da interface MailerInterface.

<?php
// Classes para teste
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,
            'Welcome!',
            'Thank you for joining!'
        );
    }
}

// Teste usando Prophecy
use Prophecy\PhpUnit\ProphecyTrait;
use PHPUnit\Framework\TestCase;

class UserMailerTest extends TestCase {
    use ProphecyTrait;
    
    public function testSendWelcomeEmail() {
        // 1. Cria uma profecia para MailerInterface
        $mailerProphecy = $this->prophesize(MailerInterface::class);
        
        // 2. Declara a expectativa: o método send será chamado uma vez com argumentos específicos
        $mailerProphecy->send('user@example.com', 'Welcome!', 'Thank you for joining!')
            ->willReturn(true);
        
        // 3. Obtém o objeto mock a partir da profecia
        $mailerMock = $mailerProphecy-