الدوال في PHP: التعريف والإرجاع والمعاملات والأنواع

تُعرَّف دالة 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 أيضًا، لكنها تخفي الاعتماد؛ وتشرحها صفحة نطاق المتغيرات. وللدوال القصيرة التي تُمرر إلى دوال أخرى، مثل دوال الاستدعاء لـ array_map()، راجع الدوال المجهولة، التي تستطيع التقاط المتغيرات الخارجية بـ use.