### Install Prophecy via Composer

Source: https://github.com/phpspec/prophecy/blob/master/README.md

This bash command installs Prophecy and its dependencies using Composer, preferring the distributed versions for faster installation.

```Bash
$> composer install --prefer-dist

```

--------------------------------

### Running Prophecy Tests with Composer, phpspec, and PHPUnit

Source: https://github.com/phpspec/prophecy/blob/master/CONTRIBUTING.md

This snippet demonstrates how to install dependencies and run tests for the Prophecy project. It uses Composer to install packages, phpspec to run specifications, and PHPUnit for unit testing.

```bash
$> composer install --prefer-dist
$> vendor/bin/phpspec run
$> vendor/bin/phpunit
```

--------------------------------

### Prophecy ReturnPromise Example

Source: https://github.com/phpspec/prophecy/blob/master/README.md

Demonstrates the basic usage of ReturnPromise to specify a return value for a method call with specific arguments.

```php
$prophecy->read('123')->will(new Prophecy\Promise\ReturnPromise(array('value')));
```

--------------------------------

### PHPUnit Test with Prophecy Mocking

Source: https://github.com/phpspec/prophecy/blob/master/README.md

This example demonstrates how to use Prophecy within a PHPUnit test case to mock a Hasher object and assert its behavior when hashing a password.

```PHP
<?php

class UserTest extends PHPUnit\Framework\TestCase
{
    private $prophet;

    public function testPasswordHashing()
    {
        $hasher = $this->prophet->prophesize('App\Security\Hasher');
        $user   = new App\Entity\User($hasher->reveal());

        $hasher->generateHash($user, 'qwerty')->willReturn('hashed_pass');

        $user->setPassword('qwerty');

        $this->assertEquals('hashed_pass', $user->getPassword());
    }

    protected function setUp()
    {
        $this->prophet = new \Prophecy\Prophet;
    }

    protected function tearDown()
    {
        $this->prophet->checkPredictions();
    }
}

```

--------------------------------

### Prophecy Allows sebastian/comparator and sebastian/recursion-context 6

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

This update allows Prophecy to be installed with version 6 of sebastian/comparator and sebastian/recursion-context, ensuring compatibility with newer versions of these related packages.

```PHP
1.19.0
======

**Added:**

* Allow sebastian/comparator and sebastian/recursion-context 6
```

--------------------------------

### Prophecy Allows Installing with PHP 8.2

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

This version of Prophecy allows installation and usage with PHP 8.2, ensuring compatibility with the latest PHP release.

```PHP
1.16.0 / 2022/11/29
===================

* [added] Allow installing with PHP 8.2 [@gquemener]
```

--------------------------------

### Prophecy Allows sebastian/comparator and sebastian/recursion-context 5, phpunit/phpunit 10

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

This version of Prophecy allows installation with specific versions of sebastian/comparator (5.x), sebastian/recursion-context (5.x), and phpunit/phpunit (10.x), ensuring compatibility with these dependencies.

```PHP
1.18.0 / 2023-12-07
===================

* [Added] Allow sebastian/comparator and sebastian/recursion-context 5, and phpunit/phpunit 10 [@Jean85]
```

--------------------------------

### Prophecy: Checking Predictions

Source: https://github.com/phpspec/prophecy/blob/master/README.md

Illustrates how to trigger the verification of all defined predictions on the Prophet object. This is typically done at the end of a test, for example, in a tearDown() method.

```PHP
$prophet->checkPredictions();
```

--------------------------------

### Prophecy Allows Install on PHP 8.1

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Prophecy now allows installation on PHP 8.1, with necessary fixes to the test suite to ensure compatibility.

```PHP
1.14.0 / 2021/09/16
===================

* [added] Allow install on PHP 8.1 (with test suite fixes) [@javer]
```

--------------------------------

### Get Checked Predictions - MethodProphecy

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Introduces a method to retrieve checked predictions from MethodProphecy. This allows users to inspect the prediction status after execution.

```PHP
MethodProphecy::getCheckedPredictions()
```

--------------------------------

### PHP: Specify required php version for composer

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Specifies the required PHP version in the `composer.json` file, ensuring that users install Prophecy with a compatible PHP environment.

```JSON
{
    "require": {
        "php": ">=5.3.0"
    }
}
```

--------------------------------

### Prophecy: Creating a Prophet Instance

Source: https://github.com/phpspec/prophecy/blob/master/README.md

Initializes a new Prophet object, which is the central entry point for creating prophecies in Prophecy.

```PHP
$prophet = new Prophecy\Prophet;

```

--------------------------------

### PHP Prophecy: Using Argument Tokens

Source: https://github.com/phpspec/prophecy/blob/master/README.md

Demonstrates how to use Prophecy's Argument class to create argument tokens for method prophecies, replacing hardcoded values with flexible matching strategies like exact values, types, or custom callbacks.

```PHP
use Prophecy\Argument;

$user->setName(Argument::exact('everzet'));
```

```PHP
use Prophecy\Argument;

$user->setName(Argument::type('string'));
```

```PHP
use Prophecy\Argument;

$user->setName(Argument::any());
```

```PHP
use Prophecy\Argument;

$user->setName(Argument::containingString('test'));
```

```PHP
use Prophecy\Argument;

$user->setName(Argument::in(['a', 'b']));
```

```PHP
use Prophecy\Argument;

$user->setName(Argument::notIn(['a', 'b']));
```

```PHP
use Prophecy\Argument;

$user->setName(Argument::which('getProperty', 'value'));
```

```PHP
use Prophecy\Argument;

$user->setName(Argument::that(function ($arg) {
    return $arg === 'expected';
}));
```

--------------------------------

### Prophecy Mock: Expecting a Method Call

Source: https://github.com/phpspec/prophecy/blob/master/README.md

Demonstrates how to set an expectation that a method will be called at least once using Prophecy's shouldBeCalled() shortcut. This is a common pattern for verifying interactions with mocked objects.

```PHP
$entityManager->flush()->shouldBeCalled();
```

--------------------------------

### Prophecy: Creating an Object Prophecy

Source: https://github.com/phpspec/prophecy/blob/master/README.md

Generates an ObjectProphecy instance from a Prophet, which will be used to define the behavior of a mock object.

```PHP
$prophecy = $prophet->prophesize();

```

--------------------------------

### PHP: Support for object type hints

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Prophecy now supports object type hints in method signatures, allowing for more precise mocking of methods that expect specific object types as arguments or return values.

```PHP
<?php

// Example usage with object type hint:
$mockObject->processRequest(Request $request);

// Mocking a method with object type hint:
$mockObject->processRequest($mockRequest)->willReturn($mockResponse);
```

--------------------------------

### PHP: Support for mocking classes with methods returning references

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Prophecy now correctly handles mocking classes where methods return references, ensuring that reference behavior is accurately simulated.

```PHP
<?php

// Example of a method that returns a reference:
// class MyClass { public function &getValue() { $val = 10; return $val; } }
// $mockObject->getValue()->willReturn(10);
```

--------------------------------

### Prophecy Supports 'static' Return Type

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Prophecy now supports the `static` return type hint. This allows for accurate mocking of methods that return the current class instance.

```PHP
1.15.0 / 2021/12/08
===================

* [added] Support for the `static` return type [@denis-rolling-scopes]
```

--------------------------------

### Composer Dependency for Prophecy

Source: https://github.com/phpspec/prophecy/blob/master/README.md

This JSON snippet shows how to add Prophecy as a development dependency to your project using Composer.

```JSON
{
    "require-dev": {
        "phpspec/prophecy": "~1.0"
    }
}

```

--------------------------------

### PHP: Add Variadics support

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Prophecy now supports variadic arguments in method prophecies, allowing for flexible mocking of methods that accept a variable number of arguments.

```PHP
<?php

// Example usage with variadic arguments:
$mockObject->processItems(string ...$items);

// Mocking a method with variadic arguments:
$mockObject->processItems('apple', 'banana', 'cherry');
```

--------------------------------

### PHP Prophecy: Refactoring setName/getName with Argument Tokens

Source: https://github.com/phpspec/prophecy/blob/master/README.md

Refactors the setName and getName methods using Prophecy's argument tokens to accept any string argument, demonstrating how to use closures for promises and handling different PHP versions.

```PHP
use Prophecy\Argument;

$user->getName()->willReturn(null);

// For PHP 5.4
$user->setName(Argument::type('string'))->will(function ($args) {
    $this->getName()->willReturn($args[0]);
});

// For PHP 5.3
$user->setName(Argument::type('string'))->will(function ($args, $user) {
    $user->getName()->willReturn($args[0]);
});

// Or
$user->setName(Argument::type('string'))->will(function ($args) use ($user) {
    $user->getName()->willReturn($args[0]);
});
```

```PHP
use Prophecy\Argument;

$user->getName()->willReturn(null);

// For PHP 5.4
$user->setName(Argument::type('string'))->will(function ($args) {
    $this->getName()->willReturn($args[0]);
});

// For PHP 5.3
$user->setName(Argument::type('string'))->will(function ($args, $user) {
    $user->getName()->willReturn($args[0]);
});

// Or
$user->setName(Argument::type('string'))->will(function ($args) use ($user) {
    $user->getName()->willReturn($args[0]);
});

$user->setName(Argument::any())->will(function () {
});
```

--------------------------------

### PHP: Add more information to MethodNotFound exceptions

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Improves `MethodNotFound` exceptions by including more contextual information, aiding in debugging when unexpected method calls occur.

```PHP
<?php

// Example of a MethodNotFound exception (conceptual):
// MethodNotFoundException: Method 'nonExistentMethod' not found on MockedClass.
```

--------------------------------

### Prophecy: Revealing a Dummy Object

Source: https://github.com/phpspec/prophecy/blob/master/README.md

Obtains a dummy object from an ObjectProphecy. Dummy objects have no logic and return null for all method calls, useful for satisfying type hints.

```PHP
$dummy = $prophecy->reveal();

```

--------------------------------

### Prophecy: Defining Object Interface Implementation

Source: https://github.com/phpspec/prophecy/blob/master/README.md

Configures an ObjectProphecy to implement a specified interface, ensuring the mock object adheres to the interface's contract.

```PHP
$prophecy->willImplement('SessionHandlerInterface');

```

--------------------------------

### Prophecy Supports New sebastian/comparator and sebastian/recursion-context Versions

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Adds support for newer versions of the `sebastian/comparator` and `sebastian/recursion-context` packages. This ensures compatibility and allows using the latest features of these dependencies.

```PHP
1.10.2 / 2020/01/20
===================

* [added] support for new versions of ` sebastian/comparator` and `sebastian/recursion-context` (@sebastianbergmann)
```

--------------------------------

### Prophecy CallbackPromise for Complex Behaviors

Source: https://github.com/phpspec/prophecy/blob/master/README.md

Shows how to use CallbackPromise to define custom logic or chain behaviors, such as setting a return value for another method after a specific call.

```php
$user->getName()->willReturn(null);

// For PHP 5.4
$user->setName('everzet')->will(function () {
    $this->getName()->willReturn('everzet');
});

// For PHP 5.3
$user->setName('everzet')->will(function ($args, $user) {
    $user->getName()->willReturn('everzet');
});

// Or
$user->setName('everzet')->will(function ($args) use ($user) {
    $user->getName()->willReturn('everzet');
});
```

--------------------------------

### Exception Handling - Method Not Found

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Fixes the namespace for `MethodNotFoundException` to ensure correct error reporting.

```PHP
Fix MethodNotFoundException wrong namespace
```

--------------------------------

### PHP: Add support for 'self' and 'parent' return type hints

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Prophecy now correctly handles mocking methods that declare their return type as 'self' or 'parent', ensuring accurate type hinting in prophecies.

```PHP
<?php

class MyClass { public function getSelf(): self { return $this; } }

$mock = $prophet->prophesize(MyClass::class);
$mock->getSelf()->willReturn($mock);
// Mocking methods returning 'self' is now supported.
```

--------------------------------

### PHP: Support for PHP 7 scalar type hints

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Prophecy now supports PHP 7 scalar type hints for method arguments, allowing for more precise mocking of methods with scalar type declarations.

```PHP
<?php

// Example usage with scalar type hint:
$mockObject->setCount(int $count);

// Mocking a method with scalar type hint:
$mockObject->setCount(5);
```

--------------------------------

### Argument Matching - Array Entry

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Introduces `ArrayEntryToken` and `Argument::withEveryEntry()` for more granular argument matching, specifically for array contents.

```PHP
Added ArrayEntryToken and Argument::withEveryEntry()
```

--------------------------------

### Exception Handling - Call Recording

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Prophecy now records calls that result in exceptions being thrown, providing better insight into runtime behavior.

```PHP
Record calls that throw exceptions
```

--------------------------------

### PHP: Add ability to specify argument in willReturnArgument

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Enhances `willReturnArgument` to allow specifying which argument should be returned, providing more control over mock method return values based on argument order.

```PHP
<?php

// Example usage:
$mockObject->getArgument(1)->willReturnArgument(0); // Returns the first argument passed to getArgument
```

--------------------------------

### PHP: Support for 'self' and 'parent' return types

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Prophecy allows mocking methods that return 'self' or 'parent' type hints, ensuring accurate representation of methods that return instances of the current or parent class.

```PHP
<?php

// Example usage with 'self' return type:
$mockObject->getParentInstance(): self;

// Mocking a method returning 'self':
$mockObject->getParentInstance()->willReturn($mockObject);
```

--------------------------------

### Prophecy Supports 'never' Return Type

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

This version of Prophecy adds support for the `never` return type hint, allowing for mocking of methods that are guaranteed not to return.

```PHP
1.14.0 / 2021/09/16
===================

* [added] Support for the 'never' return type [@ciaranmcnulty]
```

--------------------------------

### Prophecy Multiple Return Values for Repeated Calls

Source: https://github.com/phpspec/prophecy/blob/master/README.md

Demonstrates how to specify multiple return values for a method that is called multiple times with the same arguments, though this practice is generally discouraged.

```php
$prophecy->read('123')->willReturn(1, 2, 3);
```

--------------------------------

### PHP: Allow PHP5 keywords methods generation on PHP7

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Enables the generation of methods using PHP 5 keywords as method names when running on PHP 7, maintaining compatibility with older codebases.

```PHP
<?php

// Example of a method name that might have been problematic in older PHP versions:
// $mockObject->function(); // If 'function' was a reserved keyword in older PHP
```

--------------------------------

### Argument Matching - Logical Tokens

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Adds logical `AND` and `NOT` tokens for constructing more complex argument matching conditions.

```PHP
Logical `AND` token added
```

```PHP
Logical `NOT` token added
```

--------------------------------

### PHP Prophecy: Revealing Stub Objects

Source: https://github.com/phpspec/prophecy/blob/master/README.md

Demonstrates how to obtain a stub object from a Prophecy prophecy using the reveal() method, which is essential for interacting with the mocked object in tests.

```PHP
$stub = $prophecy->reveal();
```

--------------------------------

### Prophecy Method Prophecies Idempotency

Source: https://github.com/phpspec/prophecy/blob/master/README.md

Illustrates that Prophecy enforces the same method prophecies and promises for identical method calls with the same arguments, ensuring consistency.

```php
$methodProphecy1 = $prophecy->read('123');
$methodProphecy2 = $prophecy->read('123');
$methodProphecy3 = $prophecy->read('321');

$methodProphecy1 === $methodProphecy2;
$methodProphecy1 !== $methodProphecy3;
```

--------------------------------

### Argument Matching - Array Entry Token

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Introduces the `ArrayEntryToken` for more specific matching of array elements.

```PHP
New ArrayEntryToken
```

--------------------------------

### Prophecy: Defining Object Inheritance

Source: https://github.com/phpspec/prophecy/blob/master/README.md

Configures an ObjectProphecy to extend a specified class, allowing the mock object to inherit its properties and methods.

```PHP
$prophecy->willExtend('stdClass');

```

--------------------------------

### PHP: Support for PHP 7 return types

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Prophecy includes support for PHP 7 return type declarations, enabling accurate mocking of methods that specify their return types.

```PHP
<?php

// Example usage with return type hint:
$mockObject->calculateTotal(): float;

// Mocking a method with return type hint:
$mockObject->calculateTotal()->willReturn(100.50);
```

--------------------------------

### ObjectStateToken Support

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Adds support for `ObjectStateToken`, enabling state-based assertions on objects.

```PHP
Added support for properties in ObjectStateToken
```

--------------------------------

### Prophecy Supports Union and Mixed Types

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Prophecy now supports union types and the `mixed` type hint in PHP. This allows for more accurate mocking of methods with complex return or parameter types.

```PHP
1.12.0 / 2020/10/28
===================

* [added] Support for union and mixed types [@ciaranmcnulty]
```

--------------------------------

### Argument Token - Identical Value

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Introduces `IdenticalValueToken` and `Argument::is()` for strict, identical value comparisons in argument matching.

```PHP
Added IdenticalValueToken and Argument::is()
```

--------------------------------

### Argument Matching - Type Token

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Enhances argument matching by adding support for interfaces within the `TypeToken` and `Argument::type()` methods.

```PHP
Add support for interfaces into TypeToken and Argument::type()
```

--------------------------------

### PHP: Add support for sebastian/recursion-context 2

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Updates the dependency on `sebastian/recursion-context` to version 2, ensuring compatibility with the features and improvements in that version.

```PHP
<?php

// This is a dependency update, no direct code change visible to the user.
```

--------------------------------

### PHP: Add willYield feature to Method Prophecy

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Introduces the `willYield` method to `MethodProphecy`, enabling mocks to yield values sequentially, useful for simulating iterators or generators.

```PHP

```

--------------------------------

### Internal Class Method Naming

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Adds support for internal classes that use keywords as method names.

```PHP
Added support for internal classes using keywords as method names
```

--------------------------------

### PHP: Allow `Throwable` instances in `ThrowPromise`

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

The `ThrowPromise` in Prophecy can now accept `Throwable` instances directly, providing a more direct way to mock exception throwing behavior.

```PHP
<?php

use Prophecy\Promise\ThrowPromise;

// Example usage:
$exception = new InvalidArgumentException('Invalid value');
$promise = new ThrowPromise($exception);

// This promise would be used when setting up a prophecy method.
```

--------------------------------

### Magic Method Doubling

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Enables doubling of magic methods, with documentation support for these methods as specified in the class phpdoc.

```PHP
Added support for doubling magic methods documented in the class phpdoc
```

--------------------------------

### PHP: Fix PhpDoc for interfaces usage

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Ensures that phpDocumentor tags are correctly generated and interpreted when dealing with interfaces, improving documentation accuracy for interface-based mocking.

```PHP
<?php

interface MyInterface {}
/** @method MyInterface getMyObject() */
class MyClass {}
// PhpDoc for interface usage is now correct.
```

--------------------------------

### Prophecy Supports Standalone False, True, and Null Types

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Prophecy now supports standalone `false`, `true`, and `null` types. This enhances the framework's ability to mock methods with these scalar return types.

```PHP
1.16.0 / 2022/11/29
===================

* [added] Support standalone false,true and null types [@kschatzle]
```

--------------------------------

### Class Generation - ReflectionClass::newInstance

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Introduces a class patch for `ReflectionClass::newInstance` to ensure its arguments are consistently optional.

```PHP
Added a clss patch for ReflectionClass::newInstance to make its argument optional consistently
```

--------------------------------

### PHP: Add support for 'self' and 'parent' return type

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Prophecy now supports mocking methods that declare their return type as 'self' or 'parent', improving accuracy when dealing with methods that return instances of the current or parent class.

```PHP
<?php

class Base {}
class Child extends Base { public function getParent(): parent { return new Base(); } }

$mock = $prophet->prophesize(Child::class);
$mock->getParent()->willReturn(new Base());
// Mocking methods returning 'parent' is now supported.
```

--------------------------------

### PHP: Support for void return types

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Prophecy now supports void return types without requiring explicit `will()` calls. This simplifies mocking scenarios where methods are expected to return nothing.

```PHP
<?php

// Example usage (conceptual):
$mockObject->someMethod()->willReturn(); // No explicit will() needed for void
```

--------------------------------

### PHP: Add ProphecyComparator for comparing objects

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Introduces `ProphecyComparator` to facilitate the comparison of objects within prophecies, allowing for more sophisticated assertion logic.

```PHP
<?php

use Prophecy\Comparator\ProphecyComparator;

$comparator = new ProphecyComparator();
$result = $comparator->compare($expectedObject, $actualObject);
// $result indicates if objects are considered equal by the comparator.
```

--------------------------------

### PHP: Fix issues with PHP 7.2 (object type hints)

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Specifically addresses issues related to object type hints in PHP 7.2, ensuring that Prophecy correctly mocks methods with object type declarations.

```PHP
<?php

// Example usage with object type hint in PHP 7.2:
$mockObject->processObject(stdClass $obj);
$mockObject->processObject(new stdClass());
```

--------------------------------

### DirectoryIterator Support

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Adds support for `DirectoryIterator` objects, allowing them to be used within Prophecy.

```PHP
Add support for DirectoryIterators
```

--------------------------------

### PHP: Add support for sebastian/comparator ^3.0

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Updates the dependency on `sebastian/comparator` to version 3.0 or higher, ensuring compatibility with the latest features and improvements in the comparator library.

```PHP
<?php

// This is a dependency update, no direct code change visible to the user.
```

--------------------------------

### PHP: Updated ExportUtil to reflect latest changes by Sebastian

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

The `ExportUtil` class has been updated to align with the latest changes made by Sebastian Bergmann, ensuring consistency and compatibility with his contributions.

```PHP
<?php

// This is an internal utility update, no direct user code example.
```

--------------------------------

### PHP: Fixed the mocking of SplFileObject

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Resolves issues encountered when mocking the `SplFileObject` class, ensuring that its methods and properties can be reliably prophesied.

```PHP
<?php

use Prophecy\Prophecy\ObjectProphecy;

// Example of mocking SplFileObject:
$splFileObjectProphecy = $prophet->prophesize(SplFileObject::class);
$splFileObjectProphecy->openFile('path/to/file')->willReturn($mockFileHandle);
```

--------------------------------

### Spec Suite Migration

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Migrates the internal spec suite to use PhpSpec 2.0.

```PHP
Migrate spec suite to PhpSpec 2.0
```

--------------------------------

### Prophecy Adds Support for doctrine/instantiator 2.0

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

This update adds support for version 2.0 of the doctrine/instantiator package, ensuring compatibility with the latest features and improvements in dependency instantiation.

```PHP
1.17.0 / 2023-02-02
===================

* [added] Add support for doctrine/instantiator 2.0 [@stof]
```

--------------------------------

### Prophecy Improves Error for Unsupported Return Types

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Enhances the error message in Prophecy when attempting to mock methods with return types that Prophecy does not support. This provides clearer feedback to the user.

```PHP
1.18.0 / 2023-12-07
===================

* [changed] Improve the error when using return types that Prophecy does not support for mocking [@stof]
```

--------------------------------

### PHP: Fix phpdoc for magic methods

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Ensures that phpDocumentor tags for magic methods (e.g., `__call`, `__get`) are correctly generated and interpreted, improving the documentation of mocked objects.

```PHP
<?php

/** @method void __call(string $name, array $arguments) */
class MyClass {}
// The phpdoc for __call is now correctly generated.
```

--------------------------------

### Typehint Fix - Non-existent Classes

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Corrects the doubling of methods that have typehints referencing non-existent classes.

```PHP
Fixed the doubling of methods with typehints on non-existent classes
```

--------------------------------

### Exception Handling - Typos

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Corrects several typos found in exception messages across the library.

```PHP
Fix some typos in the exception messages
```

--------------------------------

### PHP: Add support for sebastian/comparator ^2.0

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Updates the dependency on `sebastian/comparator` to version 2.0 or higher, ensuring compatibility with the latest features and improvements in the comparator library.

```PHP
<?php

// This is a dependency update, no direct code change visible to the user.
```

--------------------------------

### PHP: Add ApproximateValueToken

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Introduces `ApproximateValueToken` for creating prophecies that match values within a certain tolerance, useful for floating-point comparisons.

```PHP
<?php

use Prophecy\Argument;
use Prophecy\Argument\ApproximateValueToken;

$mock->processValue(Argument::that(new ApproximateValueToken(10.5, 0.1)));
// This will match values between 10.4 and 10.6.
```

--------------------------------

### Callable Typehint Support

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Adds support for `callable` typehints in method arguments.

```PHP
Support callable typehints
```

--------------------------------

### PHP: Add willYield feature to Method Prophecy

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Introduces the `willYield` feature to `MethodProphecy`, allowing mocks to yield values over multiple calls, useful for simulating iterators or generators.

```PHP
<?php

// Example usage:
$mockIterator = $prophet->prophesize(Iterator::class);
$mockIterator->current()->willYield([1, 2, 3]);

// When current() is called multiple times, it will yield 1, then 2, then 3.
```

--------------------------------

### PHP: Improved object comparison

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Enhances the object comparison logic within Prophecy, leading to more reliable and accurate comparisons of objects during testing.

```PHP
<?php

// Example of comparing objects:
$mockObject->processObject($expectedObject)->willReturn($actualObject);
// Prophecy's internal comparison will determine if $expectedObject matches.
```

--------------------------------

### Class Generation - Constructor Arguments

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Adds the ability to set custom constructor arguments when generating classes.

```PHP
Add support for setting custom constructor arguments
```

--------------------------------

### Class Generation - Naming Strategy

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Changes the strategy for generating class names to use a static counter instead of random numbers, promoting more predictable naming.

```PHP
Changed the generated class names to use a static counter instead of a random number
```

--------------------------------

### PHP 8.4 Support Added in Prophecy

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

This update introduces support for PHP 8.4 in the Prophecy mocking framework. It ensures compatibility with the latest PHP features and syntax.

```PHP
1.20.0
======

**Added:**

* Add support for PHP 8.4 (@andypost)
```

--------------------------------

### Prophecy Fixes Comparator Return Type Warnings

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

This fix addresses deprecation warnings from Symfony's DebugClassLoader by adding return types for Comparator implementations in Prophecy.

```PHP
1.15.0 / 2021/12/08
===================

* [fixed] Add return types for Comparator implementations to avoid deprecation warnings from Symfony's DebugClassLoader [@stof]
```

--------------------------------

### Spy Method Call Promotion

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

In version 1.1.2, the Spy functionality was updated to automatically promote a spied method call to an expected one. This simplifies the process of verifying method interactions.

```PHP
Spy automatically promotes spied method call to an expected one
```

--------------------------------

### PHP: Add ApproximateValueToken for fuzzy matching

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Introduces `ApproximateValueToken` for fuzzy matching of values in prophecies. This is useful for scenarios where exact matches are not required or possible, such as with floating-point numbers.

```PHP
<?php

use Prophecy\Argument\ApproximateValueToken;

// Example usage:
$mockObject->processFloat(Argument::that(new ApproximateValueToken(3.14, 0.01)));
```

--------------------------------

### Prophecy Mock: Explicit Call Prediction

Source: https://github.com/phpspec/prophecy/blob/master/README.md

Shows the explicit way to assign a CallPrediction to a method prophecy, which checks if the method was called one or more times. This is equivalent to using the shouldBeCalled() shortcut.

```PHP
$entityManager->flush()->should(new Prophecy\Prediction\CallPrediction());
```

--------------------------------

### PHP: Add support for sebastian/recursion-context ^3.0

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Updates the dependency on `sebastian/recursion-context` to version 3.0 or higher, ensuring compatibility with the latest features and improvements in the recursion context library.

```PHP
<?php

// This is a dependency update, no direct code change visible to the user.
```

--------------------------------

### PHP: Add full PHP 7.1 Support

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Provides comprehensive support for all features introduced in PHP 7.1, including new type declarations and operators.

```PHP
<?php

// Example of a PHP 7.1 feature:
$nullableValue = null;
$nonNullableValue = 'hello';

// Mocking methods with nullable types:
$mockObject->processNullable(?string $value);
$mockObject->processNullable(null);
```

--------------------------------

### PHP: Add __invoke to allowed reflectable methods list

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Includes the `__invoke` magic method in the list of methods that Prophecy can reflect and mock, enabling the prophesying of objects that implement the magic `__invoke` method.

```PHP
<?php

// Example of a class with __invoke:
class CallableObject { public function __invoke() { return 'called'; } }

// Mocking the __invoke method:
$callableObjectProphecy = $prophet->prophesize(CallableObject::class);
$callableObjectProphecy->__invoke()->willReturn('mocked call');
```

--------------------------------

### Prophecy Exception Interfaces Implement Throwable

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Prophecy exception interfaces now explicitly implement `Throwable`. This aligns with modern PHP error handling practices and ensures compatibility.

```PHP
1.13.0 / 2021/03/17
===================

* [added] Prophecy exception interfaces are explicitly Throwable [@ciaranmcnulty]
```

--------------------------------

### Class Generation - Final Constructor Mocking

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Adds support for mocking classes that have a final constructor, overcoming a previous limitation.

```PHP
Added support for mocking classes with a final constructor
```

--------------------------------

### Prophecy's willYield Specifies Return Value

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

The `willYield` method in Prophecy can now specify a return value. This provides more control over the mocked behavior when yielding values.

```PHP
1.13.0 / 2021/03/17
===================

* [added] willYield can now specify a return value [@camilledejoye]
```

--------------------------------

### Exception Handling - Call Prediction

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Adds more debug information to exception messages related to `CallTimes` and `Call prediction` for improved debugging.

```PHP
Add more debug information to CallTimes and Call prediction exception messages
```

--------------------------------

### Class Generation - Mirroring Typehints

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Fixes the mirroring of classes with typehints on non-existent classes, ensuring correct behavior.

```PHP
Fixed mirroring of classes with typehints on non-existent classes
```

--------------------------------

### Prophecy Removes MethodProphecy Instantiation Without Arguments

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Removes the functionality to instantiate a MethodProphecy without providing its arguments. This change enforces stricter usage and avoids potential errors.

```PHP
1.17.0 / 2023-02-02
===================

* [changed] Remove support for instantiating a MethodProphecy without its arguments [@stof]
```

--------------------------------

### Prophecy Adds Generic Types for Interfaces

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Introduces generic type support for ProphecyInterface and ObjectProphecy. This enhances type safety and improves integration with modern PHP type hinting.

```PHP
1.17.0 / 2023-02-02
===================

* [added] Add generic types for ProphecyInterface and ObjectProphecy [@stof]
```

--------------------------------

### Prophecy Supports Static Closures in will and should

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Prophecy's `will` and `should` methods now support static closures. This allows for more flexible stubbing and verification of method calls.

```PHP
1.14.0 / 2021/09/16
===================

* [added] Support for static closures in will and should [@ntzm]
```

--------------------------------

### Stringify Hashes

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Ensures that hashes are properly converted to strings.

```PHP
Properly stringify hashes
```

--------------------------------

### Exception Handling - Unexpected Call

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Fixes a broken exception message for `UnexpectedCallException`.

```PHP
Fix broken UnexpectedCallException message
```

--------------------------------

### PHP: Allow Throwable as string in willThrow()

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

The `MethodProphecy::willThrow()` method now accepts a Throwable class name as a string. This provides flexibility in specifying exceptions to be thrown during mock method calls.

```PHP
<?php

use Prophecy\Prophecy\MethodProphecy;

// Example usage:
$methodProphecy = new MethodProphecy(...);
$methodProphecy->willThrow('InvalidArgumentException');
```

--------------------------------

### PHP: Add support for phpdocumentor/reflection-docblock v4

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Updates the dependency on `phpdocumentor/reflection-docblock` to version 4, ensuring compatibility with the latest features and improvements in the reflection docblock library.

```PHP
<?php

// This is a dependency update, no direct code change visible to the user.
```

--------------------------------

### Prophecy Spy: Checking Method Calls Manually

Source: https://github.com/phpspec/prophecy/blob/master/README.md

Demonstrates how to use Prophecy's spying feature to check method calls after they have occurred. The shouldHaveBeenCalled() method is used to verify that a specific method was invoked on a prophesized object.

```PHP
$em = $prophet->prophesize('Doctrine\ORM\EntityManager');

$controller->createUser($em->reveal());

$em->flush()->shouldHaveBeenCalled();
```

--------------------------------

### PHP: Add support for phpdocumentor/reflection-docblock 3

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Updates the dependency on `phpdocumentor/reflection-docblock` to version 3, ensuring compatibility with the latest features and improvements in the reflection docblock library.

```PHP
<?php

// This is a dependency update, no direct code change visible to the user.
```

--------------------------------

### ExactValueToken Object Comparison

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Fixes the comparison of objects within `ExactValueToken` to ensure accurate matching.

```PHP
Fixed the comparison of objects in ExactValuetoken
```

--------------------------------

### Argument Matching - String Containment

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Adds `StringContainToken` and `Argument::containingString()` to facilitate argument matching based on whether a string argument contains a specific substring.

```PHP
Added StringContainToken and Argument::containingString()
```

--------------------------------

### Prophecy Fixes Named Parameters Issues

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Addresses issues in Prophecy caused by the introduction of named parameters in PHP. This ensures correct behavior when using named arguments in mocked methods.

```PHP
1.12.0 / 2020/10/28
===================

* [fixed] Issues caused by introduction of named parameters [@ciaranmcnulty]
```

--------------------------------

### Prophecy Marks Argument::in() and notIn() as Static

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

The `Argument::in()` and `Argument::notIn()` methods in Prophecy are now marked as static. This reflects their intended usage and improves code clarity.

```PHP
1.13.0 / 2021/03/17
===================

* [fixed] Argument::in() and notIn() now marked as static [@tyteen4a03]
```

--------------------------------

### Prophecy Removes HHVM Workarounds

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Workarounds for unsupported HHVM versions have been removed in this release of Prophecy. This simplifies the codebase and focuses on standard PHP environments.

```PHP
1.16.0 / 2022/11/29
===================

* [fixed] Remove workarounds for unsupported HHVM [@TysonAndre]
```

--------------------------------

### Prophecy: Stubbing a Method Call

Source: https://github.com/phpspec/prophecy/blob/master/README.md

Defines a stub for a specific method on an ObjectProphecy. This stub dictates the return value when the method is called with specific arguments.

```PHP
$prophecy->read('123')->willReturn('value');

```

--------------------------------

### Prophecy Support for PHP 7.2 and 7.3 Removed

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Support for PHP 7.2 and 7.3 has been removed in this version of Prophecy. Users are encouraged to upgrade to newer PHP versions.

```PHP
Unreleased
==========

1.22.0
======

**Removed:**

* Support for PHP 7.2 and 7.3 (@jean85)
```

--------------------------------

### PHP: Add ProphecyComparator for object comparison

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Introduces `ProphecyComparator` for comparing objects that require revealing their internal state. This enhances the accuracy of assertions involving complex objects.

```PHP
<?php

use Prophecy\Comparator\ProphecyComparator;

// Example usage (conceptual):
$comparator = new ProphecyComparator();
$areEqual = $comparator->compare($expected, $actual);
```

--------------------------------

### Prophecy Fixes Constructor Parameter Deprecation

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Resolves a deprecation warning in Prophecy that occurred when doubling a class with constructor parameters. This update ensures smoother integration and avoids warnings.

```PHP
1.20.0
======

**Fixed:**

* Fix deprecation when doubling a class with constructor parameters (@singinwhale, @W0rma)
```

--------------------------------

### Class Generation - Old-Style Constructors

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Adds support for old-style constructors where the method name is the same as the class name.

```PHP
Add support for old-style (method name === class name) constructors
```

--------------------------------

### Exception Message Improvement

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Improves the clarity and detail of exception messages across the library.

```PHP
Improve exception messages
```

--------------------------------

### HHVM Compatibility

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Ensures compatibility with HHVM, including removing scalar typehints that are not supported in HHVM 3.

```PHP
Fix HHVM compatibility
```

```PHP
Removed the usage of scalar typehints in HHVM as HHVM 3 does not support them anymore in PHP code
```

--------------------------------

### Prophecy Doubles Methods Case-Insensitively

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Methods can now be doubled case-insensitively in Prophecy to match PHP's default behavior. This improves flexibility when mocking methods.

```PHP
1.10.0 / 2019/12/17
===================

* [added] methods can now be doubled case-insensitively to match PHP semantics (@michalbundyra)
```

--------------------------------

### Prophecy Adds Argument::in() and Argument::notIn()

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Introduces `Argument::in()` and `Argument::notIn()` methods for more flexible argument matching in Prophecy. These allow checking if an argument is within a given set or not.

```PHP
1.12.0 / 2020/10/28
===================

* [added] Argument::in() and Argument::notIn() [@viniciusalonso]
```

--------------------------------

### Mocking Final Constructors

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Prophecy now supports mocking classes that have a final constructor. This addresses a limitation where such classes could not be effectively mocked.

```PHP
Added support for mocking classes with a final constructor
```

--------------------------------

### Prophecy Customizes CallbackToken __toString Representation

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Introduces the ability to customize the `__toString` representation of a CallbackToken in Prophecy. This allows for more informative debugging and logging of callback tokens.

```PHP
1.17.0 / 2023-02-02
===================

* [added] Add the ability to customize the __toString representation of a CallbackToken [@ian-zunderdorp]
```

--------------------------------

### PHP: Fix missing sprintf in InvalidArgumentException __construct

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Resolves a bug where `sprintf` was missing in the `InvalidArgumentException` constructor, ensuring that exception messages are formatted correctly.

```PHP
<?php

// This is an internal fix for an exception class.
```

--------------------------------

### PHP: Support for PHP 7.1 features

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Prophecy has been updated to fully support PHP 7.1 features, including nullable types and other language enhancements.

```PHP
<?php

// Example usage with nullable type hint:
$mockObject->process(?string $input): void;

// Mocking a method that returns a nullable type:
$mockObject->getNullableValue()->willReturn(null);
```

--------------------------------

### PHP: Exclude 'args' in generated backtrace

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

The generated backtrace now excludes the 'args' key, which can contain sensitive or large data, leading to cleaner and more focused error reporting.

```PHP
<?php

// Example of a backtrace (conceptual):
// [ 'file' => '...', 'line' => ..., 'function' => '...', 'class' => '...' ]
// The 'args' key would be omitted.
```

--------------------------------

### PHP: Escape file path for SplFileObjectConstructor on Windows

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Ensures that file paths sent to `SplFileObjectConstructor` are correctly escaped when running on Windows, preventing potential errors related to path handling.

```PHP
<?php

// Example of how a path might be handled (conceptual):
$filePath = 'C:\\Users\\some_file.txt'; // Escaped path
// ... code that uses SplFileObjectConstructor with $filePath
```

--------------------------------

### PHP: Fix non-typehinted arguments treated as optional

Source: https://github.com/phpspec/prophecy/blob/master/CHANGES.md

Corrects an issue where non-typehinted arguments were incorrectly treated as optional, ensuring that argument expectations are enforced correctly.

```PHP
<?php

// Example where this fix might be relevant:
// $mockObject->process($arg);
// If $arg was expected to be required but treated as optional.
```