Patching functions with when()

The first way Brain Monkey offers to monkey patch a function is Functions\when().
This function has to be used to set a behavior for functions.
when() and 5 related methods are used to define functions (if not defined yet) and:
make them return a specific value
make them return one of the received arguments
make them echo a specific value
make them echo one of the received arguments
make them behave just like another callback
For the sake of readability, in all the code samples below I'll assume that an use statement is in place:
use Brain\Monkey\Functions;
Don't forget to add it in your code as well, or use the fully qualified class name.
Also be sure to read the PHP Functions / Setup section that explain how setup Brain Monkey for usage in tests.
justReturn()
By using when() in combination with justReturn() you can make a (maybe) undefined function just return a given value:
Functions\when('a_undefined_function')->justReturn('Cool!');
​
echo a_undefined_function(); // echoes "Cool!"
Without passing a value to justReturn() the target function will return nothing (null).
returnArg()
This other when-related method is used to make the target function return one of the received arguments, by default the first.
Functions\when('give_me_the_first')->returnArg(); // is the same of ->returnArg(1)
Functions\when('i_want_the_second')->returnArg(2);
Functions\when('and_the_third_for_me')->returnArg(3);
​
echo give_me_the_first('A', 'B', 'C'); // echoes "A"
echo i_want_the_second('A', 'B', 'C'); // echoes "B"
echo and_the_third_for_me('A', 'B', 'C'); // echoes "C"
Note that if the target function does not receive the desired argument, returnArg() throws an exception:
Functions\when('needs_the_third')->returnArg(3);
​
// throws an exception because required 3rd argument, but received 2
echo needs_the_third('A', 'B');
justEcho()
Similar to justReturn(), it makes the mocked function echo some value instead of returning it.
Functions\when('a_undefined_function')->justEcho('Cool!');
​
a_undefined_function(); // echoes "Cool!"
echoArg()
Similar to returnArg(), it makes the mocked function echo some received argument instead of returning it.
Functions\when('echo_the_first')->echoArg(); // is the same of ->echoArg(1)
Functions\when('echo_the_second')->echoArg(2);
​
echo_the_first('A', 'B', 'C'); // echoes "A"
echo_the_second('A', 'B', 'C'); // echoes "B"
alias()
The last of the when-related methods allows to make a function behave just like another callback. The replacing function can be anything that can be run: a core function or a custom one, a class method, a closure...
Functions\when('duplicate')->alias(function($value) {
    "Was ".$value.", now is ".($value * 2);
});
​
Functions\when('bigger')->alias('strtoupper');
​
echo duplicate(1); // echoes "Was 1, now is 2"
echo bigger('was lower'); // echoes "WAS LOWER"

Functions testing tools - Previous

Setup for functions testing

Next - Functions testing tools

Bulk patching with stubs()

Last modified 2yr ago

Copy link

On this page

justReturn()

returnArg()

justEcho()

echoArg()

alias()

`justReturn()`

`returnArg()`

`justEcho()`

`echoArg()`

`alias()`