PHPUnit: how do I mock multiple method calls with multiple arguments?

PHPUnit: how do I mock multiple method calls with multiple arguments?

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

PHPUnit: How to Mock Multiple Method Calls with Multiple Arguments

When testing a method that delegates logic to another instance, you often need to verify that specific sequences of interactions occur. A common pattern involves calling the same mocked method multiple times with varying inputs. If your test expects exactly three calls where each call uses a distinct set of arguments, the standard approach is to use expects() combined with logicalOr().

However, developers frequently encounter a stumbling block when dealing with methods that accept more than one parameter. The constraint lies in how PHPUnit's matcher functions handle multiple values. Specifically, the $this->equalTo() matcher accepts exactly two parameters: the value being tested and an optional second value for numeric comparisons or specific type constraints. It does not support passing a tuple of arguments directly to validate an entire method signature.

Attempting to pass multiple arguments to equalTo() results in a construction error: "Argument #2 of PHPUnit_Framework_Constraint_IsEqual::__construct() must be a numeric." This limitation forces developers to look for workarounds when trying to assert that a method was called with specific combinations of arguments, rather than just a single scalar value.

To solve this, you need to construct the expectation logic differently. Instead of trying to pass the entire argument list into a single matcher, you must define the acceptable argument sets as separate conditions and combine them using logicalOr().

Here is how you structure the expectation for a method like MyMockedMethod that takes three arguments:

$mock->expects($this->exactly(3))
     ->method('MyMockedMethod')
     ->with(
         $this->logicalOr(
             $this->equalTo($arg1, $arg2),
             $this->equalTo($arg1b, $arg2b),
             $this->equalTo($arg1c, $arg2c)
         )
     );

Wait, this still won't work because equalTo expects a single value as its primary argument. The previous mental model of passing an array or multiple arguments directly is incorrect for the API signature of equalTo. You must match each argument position individually or use a more flexible matcher that understands multi-dimensional data structures.

The correct approach involves creating separate expectations for each call, or using a custom constraint if the arguments are complex. However, for standard types, the most robust solution without writing custom constraints is to chain multiple with() calls if you cannot easily express the "OR" logic within a single expects block due to the API limitations of equalTo.

Actually, there is a cleaner way using logicalOr but it requires wrapping the arguments in an array or using a constraint that can handle the tuple. If your arguments are simple scalars, you cannot pass them as a list to equalTo. Instead, you should use $this->anyOf() (available in PHPUnit 9.3+) or construct the logic by ensuring the order of calls is predictable.

If the order of calls does not matter, but the set of arguments must match specific combinations, and you are on PHPUnit 9.3 or later, you can use anyOf which accepts a list of constraints. However, if you are stuck on an older version or need to strictly enforce the exact sequence without using anyOf, you often have to define three separate expectations:

$mock->expects($this->once())
     ->method('MyMockedMethod')
     ->with($arg1, $arg2);

$mock->expects($this->once())
     ->method('MyMockedMethod')
     ->with($arg1b, $arg2b);

$mock->expects($this->once())
     ->method('MyMockedMethod')
     ->with($arg1c, $arg2c);

This pattern explicitly enforces that the method is called exactly three times with the specific arguments in a specific order. This is often preferred because it makes the test intent crystal clear: "First call this, second call this, third call this."

If you need to assert that the calls happened in any order, but still with multiple arguments, you must rely on anyOf (PHPUnit 9.3+) or create a custom constraint class that implements Constraint. Creating a custom constraint allows you to define an array of expected argument sets and check if the current call's arguments match any set in that array.

For example, a custom constraint could look like this:

class MatchesAnyArgumentSet extends PHPUnit\Framework\Constraint\Constraint
{
    private $sets;

    public function __construct($sets) {
        $this->sets = $sets;
    }

    public function matches($value) {
        // Logic to check if $value (which is an array of arguments) 
        // matches any of the sets in $this->sets.
        foreach ($this->sets as $set) {
            if ($value === $set) {
                return true;
            }
        }
        return false;
    }

    public function toString() {
        return 'Matches any of: ' . json_encode($this->sets);
    }
}

Usage would then be:

$mock->expects($this->exactly(3))
     ->method('MyMockedMethod')
     ->with(new MatchesAnyArgumentSet([
         [$arg1, $arg2],
         [$arg1b, $arg2b],
         [$arg1c, $arg2c]
     ]));

This approach bypasses the limitation of equalTo by implementing a constraint that understands the multi-dimensional nature of the argument list. It is a pragmatic solution when the built-in matchers fall short due to their single-argument design constraints.

If you are working within a Laravel ecosystem, remember that while PHPUnit is the standard for testing logic, packages like https://laravelcompany.com often provide enhanced mocking utilities or facades that might abstract away these lower-level constraint details, allowing you to focus on business logic rather than matcher syntax.

Ultimately, the choice between chaining expects calls and using a custom constraint depends on your version of PHPUnit and whether call order matters in your test case.

Our network