Funktionsparameter und -argumente

Die Funktionsparameter werden in der Signatur der Funktion deklariert. Mit einer Liste von Argumenten kann man Informationen an eine Funktion übergeben. Die Argumentenliste ist eine durch Kommas getrennte Liste von Ausdrücken. Die Argumente werden von links nach rechts ausgewertet und das Ergebnis wird den Parametern der Funktion zugewiesen, bevor die eigentliche Funktion aufgerufen wird, d. h. mit der sog. eager-Evaluation (dt. eifrige Auswertung).

PHP unterstützt die Weitergabe von Parametern als Werte (das ist der Standard), als Verweise und als Vorgabewerte. Eine variable Anzahl von Parametern und benannte Parameter werden ebenfalls unterstützt.

Hinweis:
Seit PHP 7.3.0 ist es möglich, in der Argumentliste eines Funktionsaufrufs ein nachgestelltes Komma zu verwenden:

<?php $v = foo( $arg_1, $arg_2, ); ?>

Seit PHP 8.0.0 kann die Liste der Funktionsparameter ein nachgestelltes Komma enthalten, das ignoriert wird. Das ist besonders nützlich in Fällen, in denen die Liste der Parameter lang ist oder lange Variablennamen enthält, sodass es praktisch ist, die Parameter vertikal aufzulisten.

Beispiel #1 Liste von Funktionsparametern mit nachgestelltem Komma

<?php
function takes_many_args(
    $first_arg,
    $second_arg,
    $a_very_long_argument_name,
    $arg_with_default = 5,
    $again = 'a default string', // Dieses nachgestellte Komma war vor 8.0.0
                                 // nicht erlaubt.
)
{
    // ...
}
?>

Parameter als Verweise übergeben

Normalerweise werden den Funktionen Werte als Parameter übermittelt. Wenn man also den Wert dieser Parameter innerhalb der Funktion ändert, bleiben sie außerhalb der Funktion unverändert. Wollen Sie aber erreichen, dass die Änderung auch außerhalb der Funktion sichtbar wird, müssen Sie die Parameter als Verweise (Referenzen) übergeben.

Wenn eine Funktion einen Parameter generell als Verweis behandeln soll, setzt man in der Funktionsdefinition ein kaufmännisches Und (&) vor den Parameternamen:

Beispiel #2 Übergeben von Funktionsparametern als Verweis

<?php
function fuege_etwas_an(&$string)
{
    $string .= 'und etwas mehr.';
}
$str = 'Dies ist ein String, ';
fuege_etwas_an($str);
echo $str; // Ausgabe: 'Dies ist ein String, und etwas mehr.'
?>

Es ist ein Fehler, einen konstanten Ausdruck als Argument an einen Parameter zu übergeben, der eigentlich als Referenz übergeben werden müsste.

Vorgabewerte für Parameter

Eine Funktion kann Standardwerte für Parameter definieren, indem sie eine ähnliche Syntax wie bei der Zuweisung von Variablen verwendet. Der Standardwert wird nur verwendet, wenn für den Parameter kein Argument übergeben wurde. Es ist zu beachten, dass bei der Übergabe von null nicht der Standardwert zugewiesen wird.

Beispiel #3 Einsatz von Vorgabeparametern in Funktionen

<?php
function machkaffee($typ = "Cappuccino")
{
    return "Ich mache eine Tasse $typ.\n";
}
echo machkaffee();
echo machkaffee(null);
echo machkaffee("Espresso");
?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

Ich mache eine Tasse Cappuccino.
Ich mache eine Tasse .
Ich mache eine Tasse Espresso.

Die Standardwerte der Parameter können skalare Werte, Arrays, der spezielle Typ null und seit PHP 8.1.0 auch Objekte sein, die die new ClassName()-Syntax verwenden.

Beispiel #4 Nichtskalare Typen als Vorgabewert

<?php
function makecoffee($types = array("Cappuccino"), $coffeeMaker = NULL)
{
    $device = is_null($coffeeMaker) ? "Hand" : $coffeeMaker;
    return "Ich mache eine Tasse ".join(", ", $types)." mit der $device.\n";
}
echo makecoffee();
echo makecoffee(array("Cappuccino", "Lavazza"), "Teekanne");
?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

Ich mache eine Tasse Cappuccino mit der Hand.
Ich mache eine Tasse Cappuccino, Lavazza mit der Teekanne.

Beispiel #5 Verwendung von Objekten als Standardwerte (seit PHP 8.1.0)

<?php
class DefaultCoffeeMaker {
    public function brew() {
        return "Koche Kaffee.\n";
    }
}
class FancyCoffeeMaker {
    public function brew() {
        return "Bereite einen schönen Kaffee für Dich zu.\n";
    }
}
function makecoffee($coffeeMaker = new DefaultCoffeeMaker)
{
    return $coffeeMaker->brew();
}
echo makecoffee();
echo makecoffee(new FancyCoffeeMaker);
?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

Koche Kaffee.
Bereite einen schönen Kaffee für Dich zu.

Der Vorgabewert muss ein konstanter Ausdruck sein, darf also zum Beispiel keine Variable, keine Eigenschaft einer Klasse und kein Funktionsaufruf sein.

Es ist zu beachten, dass optionale Parameter nach den erforderlichen Parametern angegeben werden müssen, da sie sonst bei einem Aufruf nicht weggelassen werden können. Das nachfolgende Beispiel verdeutlicht dies:

Beispiel #6 Ungültige Verwendung von Funktionsparametern mit Vorgabewerten

<?php
function mach_joghurt($typ = "rechtsdrehendes", $geschmack)
{
    return "Mache einen Becher $typ $geschmack-Joghurt.\n";
}

echo mach_joghurt("Brombeer"); // "Brombeer" ist $typ, nicht $geschmack
?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

Fatal error: Uncaught ArgumentCountError: Too few arguments
 to function makeyogurt(), 1 passed in example.php on line 42

Zum Vergleich mit obigem Beispiel::

Beispiel #7 Richtiger Einsatz von Funktionsparametern mit Vorgabewerten

<?php
function mach_joghurt($geschmack, $typ = "rechtsdrehendes")
{
    return "Mache einen Becher $typ $geschmack-Joghurt.\n";
}

echo mach_joghurt("Brombeer"); // "Brombeer" ist $geschmack
?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

Mache einen Becher rechtsdrehendes Brombeer-Joghurt.

Seit PHP 8.0.0 können benannte Argumente verwendet werden, um mehrere optionale Parameter zu überspringen.

Beispiel #8 Korrekte Verwendung von Funktionsparametern mit Vorgabewerten

<?php
function makeyogurt($container = "bowl", $flavour = "raspberry", $style = "Greek")
{
    return "Making a $container of $flavour $style yogurt.\n";
}

echo makeyogurt(style: "natural");
?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

Making a bowl of raspberry natural yogurt.

Seit PHP 8.0.0 wird die Angabe von obligatorischen Parametern nach optionalen Parametern missbilligt. Dies kann im Allgemeinen durch das Weglassen des Standardwertes gelöst werden, da er nie verwendet wird. Eine Ausnahme von dieser Regel sind Parameter der Form Type $param = null, wobei der Standardwert null den Typ implizit nullbar macht. Diese Verwendung ist seit PHP 8.4.0 veraltet und stattdessen sollte ein expliziter nullable Typ verwendet werden.

Beispiel #9 Angabe von optionalen Parametern nach obligatorischen Parametern

<?php

function foo($a = [], $b) {}     // Standardwert wird nicht verwendet;
                                 // seit PHP 8.0.0 veraltet
function foo($a, $b) {}          // Funktionell identisch, aber ohne Veraltet-Hinweis

function bar(A $a = null, $b) {} // Seit PHP 8.1.0 ist $a implizit erforderlich
                                 // (da es vor dem erforderlichen Parameter steht),
                                 // aber implizit löschbar (seit PHP 8.4.0 veraltet),
                                 // da der Standardparameterwert null ist
function bar(?A $a, $b) {}       // Empfohlen

?>

Hinweis: Seit PHP 7.1.0 wird ein ArgumentCountError ausgelöst, wenn ein Parameter weggelassen wird, für den kein Standardwert angegeben ist; in früheren Versionen löste es eine Warnung aus.

Hinweis: Parameter, die ein Argument per Verweis erwarten, dürfen einen Standardwert haben.

Variable Anzahl von Argumenten

PHP unterstützt eine variable Anzahl an Argumenten in benutzerdefinierten Funktionen durch Verwendung des ...-Tokens.

Eine Liste von Parametern kann das Token ... enthalten, um anzugeben, dass die Funktion eine variable Anzahl von Argumenten akzeptiert. Die Argumente werden als Array an die entsprechende Variable übergeben:

Beispiel #10 Verwendung von ... für den Zugriff auf variable Argumente

<?php
function sum(...$numbers) {
    $acc = 0;
    foreach ($numbers as $n) {
        $acc += $n;
    }
    return $acc;
}

echo sum(1, 2, 3, 4);
?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

Das Token ... kann auch dazu verwendet werden, um ein Array oder ein Traversable-Objekt als Liste von Argumenten zu übergeben:

Beispiel #11 Verwendung von ... zur Übergabe einer Argumentenliste

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

echo add(...[1, 2])."\n";

$a = [1, 2];
echo add(...$a);
?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

3
3

Die Definition von regulären, positionierten Parametern vor dem ... ist natürlich weiterhin möglich. In einem solchen Fall werden dann nur die zusätzlichen Werte, die zu keinem positionierten Parameter gehören, in das durch ... erzeugte Array übernommen.

Es ist zudem auch möglich, dem ...-Token eine Typdeklaration voranzustellen. Ist dies der Fall, dann müssen alle Argumente, die von ... erfasst werden, vom entsprechenden Typ sein.

Beispiel #12 Variable Argumente mit Typdeklaration

<?php
function total_intervals($unit, DateInterval ...$intervals) {
    $time = 0;
    foreach ($intervals as $interval) {
        $time += $interval->$unit;
    }
    return $time;
}

$a = new DateInterval('P1D');
$b = new DateInterval('P2D');
echo total_intervals('d', $a, $b).' days';

// Dieser Aufruf wird scheitern, da null keine Instanz von DateInterval ist
echo total_intervals('d', null);
?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

3 days
Catchable fatal error: Argument 2 passed to total_intervals() must be an instance of DateInterval, null given, called in - on line 14 and defined in - on line 2

Durch ein voran gestelltes & ist auch die Übergabe von variablen Argumenten als Referenz möglich.

Benannte Argumente

PHP 8.0.0 führt benannte Argumente als eine Erweiterung der bestehenden Positionsparameter ein. Benannte Argumente ermöglichen die Übergabe von Argumenten an eine Funktion basierend auf dem Parameternamen und nicht auf der Position des Parameters. Das macht die Bedeutung von Argumenten selbsterklärend, macht die Argumente unabhängig von der Reihenfolge und ermöglicht das willkürliche Überspringen von Standardwerten.

Benannte Argumente werden übergeben, indem dem Wert der Parametername gefolgt von einem Doppelpunkt vorangestellt wird. Reservierte Schlüsselwörter dürfen als Parameternamen verwendet werden. Der Parametername muss ein Bezeichner sein; eine dynamische Angabe ist nicht erlaubt.

Beispiel #13 Syntax benannter Argumente

<?php
myFunction(paramName: $value);
array_foobar(array: $value);

// Wird NICHT unterstützt
function_name($variableStoringParamName: $value);
?>

Beispiel #14 Positionsargumente im Vergleich zu benannten Argumenten

<?php
// Verwendung von Positionsargumenten:
array_fill(0, 100, 50);

// Verwendung von benannten Argumenten:
array_fill(start_index: 0, count: 100, value: 50);
?>

Die Reihenfolge, in der die benannten Argumente übergeben werden, spielt keine Rolle.

Beispiel #15 Das gleiche Beispiel wie oben mit einer anderen Reihenfolge der Parameter

<?php
array_fill(value: 50, count: 100, start_index: 0);
?>

Benannte Argumente können mit Positionsargumenten kombiniert werden. In diesem Fall müssen die benannten Argumente nach den Positionsargumenten kommen. Es ist auch möglich, nur einige der optionalen Argumente einer Funktion anzugeben, unabhängig von ihrer Reihenfolge.

Beispiel #16 Kombinieren von benannten Argumenten mit Positionsargumenten

<?php
htmlspecialchars($string, double_encode: false);
// Ist das Gleiche wie
htmlspecialchars($string, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, 'UTF-8', false);
?>

Die mehrfache Übergabe eines Arguments an denselben benannten Parameter führt zu einer Error-Exception.

Beispiel #17 Die mehrfache Übergabe eines Arguments an denselben benannten Parameter erzeugt einen Fehler

<?php

function foo($param) { ... }

foo(param: 1, param: 2);
// Error: Named parameter $param overwrites previous argument

foo(1, param: 2);
// Error: Named parameter $param overwrites previous argument

?>

Seit PHP 8.1.0 ist es möglich, benannte Argumente nach dem Entpacken von Argumenten zu verwenden. Ein bereits entpacktes Argument darf nicht durch einen benanntes Argument überschrieben werden.

Beispiel #18 Verwendung benannter Argumente nach dem Entpacken

<?php
function foo($a, $b, $c = 3, $d = 4) {
  return $a + $b + $c + $d;
}

var_dump(foo(...[1, 2], d: 40)); // 46
var_dump(foo(...['b' => 2, 'a' => 1], d: 40)); // 46

var_dump(foo(...[1, 2], b: 20)); // Fataler Fehler. Der benannte Parameter $b überschreibt das vorherige Argument
?>