Writing a function that returns a calculated value

Why functions exist

A function gives a name to a small piece of work. Instead of repeating the same arithmetic in several places, you write it once and call it with different inputs. This makes programs shorter and easier to check, because each function does one job.

The shape of a function

PHP defines a function with the function keyword, a name, a parenthesised list of parameters (which may be empty), and a body inside curly braces. Parameters are separated by commas. Since PHP 8.0 a trailing comma after the last parameter is allowed.

A function name starts with a letter or underscore, followed by letters, numbers or underscores. PHP function names are case-insensitive for the ASCII letters A to Z, but you should call a function with the same spelling you used to declare it. PHP also has no function overloading, so you cannot declare two functions with the same name and different parameter lists.

Here is the smallest useful pattern: two parameters, one calculation, one returned value.

<?php
function add(int $a, int $b): int
{
    return $a + $b;
}

echo add(2, 3), "\n";

5

The int before each parameter name is a type declaration. It says the function expects whole numbers. The : int after the parentheses says the function promises to return an integer. The return statement ends the function and hands the value back to the code that called it.

Returning versus printing

A common beginner mistake is to echo inside the function and forget to return. A function that only prints cannot be reused: the caller cannot store the result, add it to something else, or test it. Prefer to return a value and let the calling code decide what to do with it.

<?php
function perimeter(int $width, int $height): int
{
    return 2 * ($width + $height);
}

$result = perimeter(3, 4);
echo "Perimeter: " . $result . "\n";

Perimeter: 14

Notice that the call perimeter(3, 4) is an expression. Its value is whatever the function returns, so you can assign it to a variable, as above, or use it directly inside another expression.

Arguments and parameters

The names in the declaration are parameters. The values you pass when calling are arguments. Arguments are matched to parameters by position: in perimeter(3, 4), 3 goes to $width and 4 goes to $height. Variables inside a function are local to it, so changing $width in the body does not change a variable with the same name outside.

If a function has a return type of int but the body produces something else that cannot be converted, PHP raises a TypeError. Keep your arithmetic on integers and the return type will hold.

Calling a function several times

The real payoff is reuse. One definition can serve many inputs, including boundary values such as zero.

<?php
function rectangleArea(int $width, int $height): int
{
    return $width * $height;
}

$areas = [rectangleArea(3, 4), rectangleArea(0, 5), rectangleArea(6, 7)];
echo json_encode($areas), "\n";

[12,0,42]

The middle call returns 0 because multiplying by zero gives zero. Boundary cases like this are worth checking whenever you write a calculation.

Where to declare a function

A function declared at the top level of a file can be called before the line where it appears, because PHP registers it when the file is loaded. Functions declared inside an if block or inside another function only exist after that code has run. For now, declare plain top-level functions and you will not meet that problem.

Worked reasoning for the exercise

The task is to write rectangleArea(int $width, int $height): int. Work through it in three steps:

1. Decide the inputs: two integers named $width and $height.
2. Decide the calculation: area is width multiplied by height.
3. Return the result with return, not echo.

Check it by hand with 3 and 4: 3 * 4 is 12. Then check a boundary: 0 and 5 gives 0. If both work on paper, the code should work in the checker.

Exercise contract

Implement rectangleArea so that it accepts two integers and returns their product as an integer. Do not print anything. The checker calls the function with five different pairs of arguments, including zero and one, and compares the returned values.

Recap

• Declare a function with function, a name, parameters and a body.
• Use return to hand a value back to the caller.
• Parameters receive arguments by position.
• Return types such as : int document and enforce what comes back.
• Return values instead of printing them so the result can be reused.