Deprecate `any()` matcher

[sebastianbergmann]

Based on the evolution of PHPUnit's testing philosophy and the specific changes discussed here and here, $this->expects($this->any()) represents an anti-pattern in modern PHPUnit usage and should be avoided in new tests. The construct creates semantic ambiguity that conflicts with PHPUnit's current emphasis on intentional, clear testing practices.

The any() matcher indicates that a method may be called "zero or more times". When combined with expects(), this creates a fundamental contradiction: you're creating a mock object (designed to verify communication) but configuring it with an expectation that essentially says "I don't care if this communication happens at all". This ambiguity is precisely what PHPUnit 12.5's new diagnostic notices target.

When you use expects($this->any()), you're treating a mock object as a stub while paying the complexity cost of a mock.

There is no valid use for expects($this->any()) anymore. The construct represents a legacy pattern that PHPUnit's evolution has rendered obsolete. The framework now enforces a clear dichotomy:

• Test Stubs control indirect inputs via createStub() and method()->willReturn(), for example
• Mock Objects verify indirect outputs via createMock() and specific expects() matchers

Considering the above, the any() matcher should be soft-deprecated in PHPUnit 12.5, hard-deprecated in PHPUnit 13.0, and removed in PHPUnit 14.0.

Migration Path

1. Identify the intent: Is the test verifying communication or just controlling data?
2. Replace with createStub() if no communication verification is needed
3. Use specific matchers (once(), ...) if communication matters

[zerkms]

Not sure if I'm too late for the party: I have skimmed through the referred article, and not sure I see what covers the following test case:

a) we need an actor that implements interface Foo
b) its method methodA should return the following value (true), invoked exactly two times
c) its method methodB should return the following value (42), can be invoked any number of times

The point b) implies we need a mock, the point c) implies we need a stub.

I agree, that in (almost?) all cases we can tell how many times exactly methodB will be called. But if it's not the test's intention to verify it - I would prefer to let it be $this->any() to not overload the test with unnecessary details.

Does this point ☝️ hold or I'm "doing it wrong" and simply must specify exact number of calls for methodB even if it makes test less readable?

[sebastianbergmann]

You do not need any() to express what you want:

<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

interface Foo
{
    public function methodA(): bool;

    public function methodB(): int;
}

final class Test extends TestCase
{
    public function testOne(): void
    {
        $foo = $this->createMock(Foo::class);

        $foo
            ->expects($this->exactly(2))
            ->method('methodA')
            ->willReturn(true);

        $foo
            ->method('methodB')
            ->willReturn(42);

        $this->assertTrue($foo->methodA());
        $this->assertTrue($foo->methodA());
        $this->assertSame(42, $foo->methodB());
    }
}