PHP Functions: Define, Return, Parameters and Types

A PHP function is defined with the function keyword, a name, a parameter list and a body; return sends a value back to the caller. function add(int $a, int $b): int { return $a + $b; } defines it, and add(2, 3) calls it and returns 5.

<?php
function greet(string $name): string
{
    return "Hello, $name";
}

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

echo greet('Ada'), "\n";
echo add(2, 3), "\n";
echo add(add(1, 2), 10), "\n";

The string and int before the parameters are type declarations, and : string after the parentheses is the return type. Both are optional, but they catch mistakes early and document what the function expects.

Return values and returning several values

return ends the function immediately. A function without return, or with a bare return;, returns null; declare : void when it is called only for its effect. A function returns one value, but that value can be an array, which you destructure on the calling side:

<?php
function grade(int $score): string
{
    if ($score >= 90) {
        return 'A';
    }
    return $score >= 75 ? 'B' : 'C';   // reached only below 90
}

function stats(array $numbers): array
{
    return [
        'min' => min($numbers),
        'max' => max($numbers),
        'avg' => array_sum($numbers) / count($numbers),
    ];
}

function logLine(string $msg): void
{
    echo "[log] $msg\n";
}

echo grade(95), grade(80), grade(40), "\n";

['min' => $min, 'max' => $max, 'avg' => $avg] = stats([4, 8, 15, 16, 23, 42]);
echo "min $min, max $max, average $avg\n";

[$quotient, $remainder] = [intdiv(17, 5), 17 % 5];
echo "17 / 5 = $quotient remainder $remainder\n";

var_dump(logLine('saved'));   // a void function returns null

See array destructuring for the other forms of [...] =.

Default parameters and named arguments

A parameter with = value is optional: callers can leave it out. Optional parameters go after the required ones. Since PHP 8.0, named arguments let the caller pass any parameter by name, so you can skip the optional ones you do not need.

<?php
function makeTag(string $text, string $tag = 'p', ?string $class = null, bool $escape = true): string
{
    $body = $escape ? htmlspecialchars($text) : $text;
    $attr = $class !== null ? " class=\"$class\"" : '';
    return "<$tag$attr>$body</$tag>";
}

echo makeTag('Hello'), "\n";
echo makeTag('Title', 'h1'), "\n";

// Named arguments: skip $tag and $class, set only $escape
echo makeTag('<b>bold</b>', escape: false), "\n";
echo makeTag(class: 'note', text: 'Order does not matter'), "\n";

Named arguments make calls to built-in functions readable too: str_pad('7', 3, '0', pad_type: STR_PAD_LEFT). The parameter name becomes part of the function's public interface, so renaming a parameter can break callers that use names.

Pass by reference

Normally PHP passes a copy of each argument, so the function cannot change the caller's variable. An & before a parameter passes the variable itself. Built-in functions like sort() work this way.

<?php
function addOne(int $n): void
{
    $n++;          // changes the copy only
}

function addOneRef(int &$n): void
{
    $n++;          // changes the caller's variable
}

$a = 5;
addOne($a);
echo $a, "\n";

addOneRef($a);
echo $a, "\n";

function addItem(array &$cart, string $item): void
{
    $cart[] = $item;
}

$cart = [];
addItem($cart, 'apple');
addItem($cart, 'pear');
print_r($cart);

Returning a new value is usually clearer than changing an argument. Use references when the function really is meant to modify something in place.

Type declarations and strict_types

By default PHP converts arguments to the declared type when it can: add("5", 3) turns "5" into 5. Putting declare(strict_types=1); at the very top of the file turns that off for calls made in that file, so a wrong type throws a TypeError instead of being converted.

<?php
declare(strict_types=1);
// This throws a TypeError on purpose: "5" is a string, not an int

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

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

Without the declare line, the same call prints 8. Strings that are not numbers, like "five", throw a TypeError in both modes.

The types you can declare for parameters and return values:

<?php
// ?string: a string or null
function findUser(int $id): ?string
{
    $users = [1 => 'Ada', 2 => 'Linus'];
    return $users[$id] ?? null;
}

// int|float: a union type (PHP 8.0)
function half(int|float $n): float
{
    return $n / 2;
}

// mixed: anything at all
function describe(mixed $value): string
{
    return get_debug_type($value);
}

var_dump(findUser(1), findUser(9));
var_dump(half(5), half(2.5));
echo describe([1, 2]), ' ', describe(null), ' ', describe(1.5), "\n";

never is a return type for functions that always throw or exit. Class and interface names work as types too.

Variable number of arguments with ...$args

...$numbers collects any number of arguments into an array. The same ... on the calling side spreads an array into separate arguments.

<?php
function sum(int ...$numbers): int
{
    return array_sum($numbers);
}

echo sum(), "\n";
echo sum(1, 2, 3), "\n";

$values = [10, 20, 30];
echo sum(...$values), "\n";          // spread an array

function logMessage(string $level, string ...$parts): string
{
    return strtoupper($level) . ': ' . implode(' ', $parts);
}

echo logMessage('info', 'user', 'Ada', 'logged in'), "\n";

Using an outside variable inside a function

A function has its own scope. A variable defined outside it is not visible inside, which surprises people coming from JavaScript:

<?php
$taxRate = 0.2;

function priceWithTax(float $price): float
{
    return $price * (1 + $taxRate);   // $taxRate is undefined here
}

Warning: Undefined variable $taxRate in /path/to/index.php on line 6

and the function returns the price without tax. Pass the value in as a parameter instead. That keeps the function honest about what it depends on and easy to test:

<?php
$taxRate = 0.2;

function priceWithTax(float $price, float $taxRate): float
{
    return $price * (1 + $taxRate);
}

echo priceWithTax(100, $taxRate), "\n";
echo priceWithTax(100, 0.1), "\n";

The global keyword also works, but hides the dependency; variable scope covers it. For short functions passed to other functions, like callbacks for array_map(), see anonymous functions, which can capture outside variables with use.