# 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:

```php
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:

```php
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.

```php
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:

```php
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.

```php
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.

```php
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...

```php
Functions\when('duplicate')->alias(function($value) {
    return "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"
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://giuseppe-mazzapica.gitbook.io/brain-monkey/functions-testing-tools/functions-when.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.