Soft-deprecate `id()` and `after()` for mock object expectations

[sebastianbergmann]

What these methods do

id(string $id) assigns a string identifier to an expectation configured on a mock object.

after(string $id) makes an expectation contingent on another expectation (identified by its ID) having already been invoked at least once before this one will match.

Together they allow expressing invocation ordering constraints between methods on the same mock object.

$mock = $this->createMock(Foo::class);

$mock
    ->expects($this->once())
    ->method('foo')
    ->id('foo-expectation');

$mock
    ->expects($this->once())
    ->method('bar')
    ->after('foo-expectation');

$mock->foo();
$mock->bar();

Here, the expectation on bar() will not match until foo() has been invoked at least once.
If bar() is called before foo(), it will not match.

Why this should be removed

The id() / after() mechanism is obscure. A test that needs id() / after() to enforce call order is likely testing an implementation detail rather than observable behaviour.

If the ordering of foo() and bar() is significant then withParameterSetsInOrder() should be used instead.

Plan

• PHPUnit 13: Soft-deprecate id() and after()
• PHPUnit 14: Hard-deprecate id() and after(), calling them now triggers a deprecation
• PHPUnit 15: Remove id() and after() from the InvocationMocker interface, calling them now results in an error