Deprecate `MockBuilder::addMethods()`

[sebastianbergmann]

To reduce complexity inside PHPUnit's test double functionality, MockBuilder::addMethods() will be deprecated and then removed:

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

[g105b]

In one of my projects, I wanted to use PHPUnit mocks to check that an anonymous function was being called X times. I mocked stdClass and used addMethods() to add the __invoke method, then I could use MockObject::expects() to do the checking.

To fix this deprecation message, I've introduced a new class into my tests directory called MockedCaller, which does the same thing but more explicitly. Here's an example:

class ExampleTest extends MyTestCase {
	public function testAnonFuncIsCalled10Times():void {
		$sut = new MyObject();
// this will pass in a callable to `doSomething10Times` that must be called 10 times with the provided parameters
		$sut->doSomething10Times(self::mockCallable(10, "example param"));
	}
}

class MyTestCase extends TestCase {
	/** @return MockObject|callable */
	protected function mockCallable(int $numCalls = null, ...$expectedParams):MockObject {
		$mock = self::createMock(MockedCaller::class);

		if(!is_null($numCalls)) {
			$expectation = $mock->expects(self::exactly($numCalls))
				->method("__invoke");

			if(!empty($expectedParameters)) {
				foreach($expectedParameters as $p) {
					$expectation->with(self::identicalTo($p));
				}
			}
		}

		return $mock;
	}
}

class MockedCaller {
	public function __invoke():void {}
}

Hope this helps someone!

[pkly]

I was wondering, what is the correct way of handling this deprecation/removal?
Calling onlyMethods with a method that does not exist produces an exception.

I'm referring to cases where you're mocking an interface which contains a method listed as a phpdoc method for backwards compatibility reasons, and does not exist within the interface itself. I understand it's somewhat of a weird scenario, but still technically valid.

[LordSimal]

@pkly We use either an anonymous class like this

$entity = new class extends Entity {
    protected function _setName(?string $name): string
    {
        return 'Dr. ' . $name;
    }
};

or straight up another class (inside the TestCase class or in a separate file)

[derrabus]

I'm referring to cases where you're mocking an interface which contains a method listed as a phpdoc method for backwards compatibility reasons, and does not exist within the interface itself.

Declare a new interface that extends that interface and materialize the virtual method.

/**
 * @method void foo(string $a)
 */
interface MyInterface {}

interface MyMockableInterface extends MyInterface
{
    public function foo(string $a): void;
}

$this->createMock(MyMockableInterface::class);