פונקציות ב-PHP: הגדרה, return, פרמטרים וטיפוסים

פונקציה ב-PHP מוגדרת עם מילת המפתח function, שם, רשימת פרמטרים וגוף; return שולחת ערך בחזרה לקורא. function add(int $a, int $b): int { return $a + $b; } מגדירה אותה, ו-add(2, 3) קוראת לה ומחזירה 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";

ה-string וה-int שלפני הפרמטרים הם הצהרות טיפוס, ו-: string אחרי הסוגריים הוא טיפוס ההחזרה. שניהם אופציונליים, אבל הם תופסים טעויות מוקדם ומתעדים מה הפונקציה מצפה לקבל.

ערכי החזרה והחזרת כמה ערכים

return מסיימת את הפונקציה מיד. פונקציה בלי return, או עם return; ריק, מחזירה null; הצהירו : void כשקוראים לה רק בשביל ההשפעה שלה. פונקציה מחזירה ערך אחד, אבל הערך הזה יכול להיות מערך, שמפרקים בצד הקורא:

<?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

ראו פירוק מערכים לצורות האחרות של [...] =.

פרמטרים עם ברירת מחדל וארגומנטים בשם

פרמטר עם = value הוא אופציונלי: הקוראים יכולים להשמיט אותו. פרמטרים אופציונליים באים אחרי פרמטרי החובה. מאז PHP 8.0, ארגומנטים בשם מאפשרים לקורא להעביר כל פרמטר לפי שם, כך שאפשר לדלג על האופציונליים שלא צריך.

<?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";

ארגומנטים בשם הופכים גם קריאות לפונקציות מובנות לקריאות: str_pad('7', 3, '0', pad_type: STR_PAD_LEFT). שם הפרמטר הופך לחלק מהממשק הציבורי של הפונקציה, ולכן שינוי שם של פרמטר יכול לשבור קוראים שמשתמשים בשמות.

העברה לפי הפניה

בדרך כלל PHP מעבירה עותק של כל ארגומנט, ולכן הפונקציה לא יכולה לשנות את המשתנה של הקורא. & לפני פרמטר מעביר את המשתנה עצמו. פונקציות מובנות כמו sort() עובדות כך.

<?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);

החזרה של ערך חדש היא בדרך כלל ברורה יותר משינוי של ארגומנט. השתמשו בהפניות כשהפונקציה באמת נועדה לשנות משהו במקום.

הצהרות טיפוס ו-strict_types

כברירת מחדל PHP ממירה ארגומנטים לטיפוס המוצהר כשהיא יכולה: add("5", 3) הופכת את "5" ל-5. שימוש ב-declare(strict_types=1); בראש הקובץ ממש מכבה את זה בקריאות שנעשות בקובץ הזה, כך שטיפוס שגוי זורק TypeError במקום להיות מומר.

<?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";

בלי שורת ה-declare, אותה קריאה מדפיסה 8. מחרוזות שאינן מספרים, כמו "five", זורקות TypeError בשני המצבים.

הטיפוסים שאפשר להצהיר עליהם לפרמטרים ולערכי החזרה:

<?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 הוא טיפוס החזרה לפונקציות שתמיד זורקות חריגה או יוצאות. גם שמות של מחלקות וממשקים עובדים כטיפוסים.

מספר משתנה של ארגומנטים עם ...$args

...$numbers אוסף כל מספר של ארגומנטים למערך. אותו ... בצד הקורא פורס מערך לארגומנטים נפרדים.

<?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";

שימוש במשתנה חיצוני בתוך פונקציה

לפונקציה יש טווח משלה. משתנה שהוגדר מחוצה לה לא גלוי בתוכה, וזה מפתיע אנשים שמגיעים מ-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

והפונקציה מחזירה את המחיר בלי מס. העבירו במקום זאת את הערך כפרמטר. זה שומר על הפונקציה כנה לגבי מה שהיא תלויה בו וקלה לבדיקה:

<?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";

גם מילת המפתח global עובדת, אבל היא מסתירה את התלות; טווח משתנים מסביר אותה. לפונקציות קצרות שמועברות לפונקציות אחרות, כמו callbacks ל-array_map(), ראו פונקציות אנונימיות, שיכולות ללכוד משתנים חיצוניים עם use.