Deprecate `TestCase` methods for creating return stub configuration objects

[sebastianbergmann]

To reduce complexity inside PHPUnit's test double functionality, these methods will be deprecated and then removed:

• TestCase::returnValue() (use $double->willReturn() instead of $double->will($this->returnValue()))
• TestCase::onConsecutiveCalls() (use $double->willReturn() instead of $double->will($this->onConsecutiveCalls()))
• TestCase::returnValueMap() (use $double->willReturnMap() instead of $double->will($this->returnValueMap()))
• TestCase::returnArgument() (use $double->willReturnArgument() instead of $double->will($this->returnArgument()))
• TestCase::returnSelf() (use $double->willReturnSelf() instead of $double->will($this->returnSelf()))
• TestCase::returnCallback() (use $double->willReturnCallback() instead of $double->will($this->returnCallback()))
• TestCase::throwException() (use $double->willThrowException() instead of $double->will($this->throwException()))

Timeline

• soft deprecation in PHPUnit 10.3 (add @deprecated annotation to the method declaration)
• deprecation in PHPUnit 11 (using the method will trigger a deprecation)
• removal in PHPUnit 12

[InvisibleSmiley]

Two questions:

1. Why is this not mentioned in the changelog for 10.3? With tools like phpstan-deprecation-rules even "soft deprecations" as you call them cause some trouble and it would be nice to find a pointer to this issue there.
2. How exactly is willReturn a replacement for onConsecutiveCalls? Please describe the migration path (maybe give an example).

[sebastianbergmann]

1. Why is this not mentioned in the changelog for 10.3?

Because I forgot to, my bad. The deprecations made in PHPUnit 10.3.0 are now documented: https://github.com/sebastianbergmann/phpunit/blob/10.3.2/ChangeLog-10.3.md#deprecated-1

[sebastianbergmann]

2. How exactly is willReturn a replacement for onConsecutiveCalls?

I hope this example from PHPUnit's own test suite is enough:

final public function testMethodCanBeConfiguredToReturnDifferentValuesOnConsecutiveCalls(): void
{
    $double = $this->createTestDouble(InterfaceWithReturnTypeDeclaration::class);

    $double->method('doSomething')->willReturn(false, true, false, true);

    $this->assertFalse($double->doSomething());
    $this->assertTrue($double->doSomething());
    $this->assertFalse($double->doSomething());
    $this->assertTrue($double->doSomething());
}