Understanding named arguments

Named arguments represent a way to avoid confusion when calling functions or methods with a large number of arguments. This not only helps avoid problems with arguments being supplied in an incorrect order, but also helps you to skip arguments with defaults. In this section, you will learn how to apply named arguments to improve the accuracy of your code, reduce confusion during future maintenance cycles, and make your method and function calls more concise. We start by examining the generic syntax required to use named arguments.

Named argument generic syntax

In order to use named arguments, you need to know the names of the variables used in the function or method signature. You then specify that name, without the dollar sign, followed by a colon and the value to be supplied, as follows:

$result = function_name( arg1 : <VALUE>, arg2 : <value>);

When the function_name() function is invoked, the values are passed to the arguments corresponding to arg1, arg2, and so on.

Calling core functions using named arguments

One of the most common reasons to use named arguments is when you call a core PHP function that has a large number of parameters. As an example, here's the function signature for setcookie():

setcookie ( string $name [, string $value = "" 
    [, int $expires = 0 [, string $path = "" 
    [, string $domain = "" [, bool $secure = FALSE 
    [, bool $httponly = FALSE ]]]]]] ) : bool

Let's say that all you really wanted to set were the name, value, and httponly arguments. Before PHP 8, you would have had to look up the default values and supply them, in order, until you got to the one you wished to override. In the following case, we wish to set httponly to TRUE:

setcookie('test',1,0,0,'','',FALSE,TRUE);

Using named arguments, the equivalent in PHP 8 would be as follows:

setcookie('test',1,httponly: TRUE);

Note that we do not need to name the first two parameters as they are supplied in order.

Tip

In PHP extensions, named arguments do not always match the names of variables you see in the PHP documentation for function or method signatures. As an example, the function imagettftext() shows a variable $font_filename in its function signature. If you scroll down a bit further, however, you'll see in the Parameters section, that the named parameter is fontfile.

If you encounter a fatal Error: Unknown named parameter $NAMED_PARAM. Always use the name as listed in the Parameters section of the documentation rather than the name of the variable in the function or method signature.

Order independence and documentation

Another use for named arguments is to provide order independence. In addition, for certain core PHP functions, the sheer number of parameters presents a documentation nightmare.

As an example, have a look here at the function signature for imagefttext() (note that this function is central to the chapter project of producing a secure CAPTCHA image):

imagefttext ( object $image , float $size , float $angle , 
    int $x , int $y , int $color , string $fontfile , 
    string $text [, array $extrainfo ] ) : array 

As you can imagine, trying to remember the names and order of these parameters when reviewing your work 6 months later might be problematic.

Important note

In PHP 8, the image creation functions (for example, imagecreate()) now return a GdImage object instance instead of a resource. All image functions in the GD extension have been rewritten to accommodate this change. There's no need to rewrite your code!

Accordingly, using named arguments, the following function call would be acceptable in PHP 8:

// /repo/ch01/php8_named_args.php
// not all code is shown
$rotation = range(40, -40, 10);
foreach ($rotation as $key => $offset) {
    $char->writeFill();
    [$x, $y] = RotateText::calcXYadjust($char, $offset);
    $angle = ($offset > 0) ? $offset : 360 + $offset;
    imagettftext(
        angle        : $angle,
        color        : $char->fgColor,
        font_filename : FONT_FILE,
        image        : $char->image,
        size         : 60,                
        x            : $x,
        y            : $y,
        text         : $char->text);
    $fn = IMG_DIR . '/' . $baseFn . '_' . $key . '.png';
    imagepng($char->image, $fn);
    $images[] = basename($fn);
}

The code example just shown writes out a string of distorted characters as a set of PNG image files. Each character is rotated 10 degrees clockwise with respect to its neighboring images. Note how named arguments are applied to make arguments to the imagettftext() function easier to understand.

Named arguments can also be applied to functions and methods of your own creation. In the next section, we cover new data types.

Tip

A detailed analysis of named arguments can be found here:

https://wiki.php.net/rfc/named_params