الدالة func_get_args()‎ في PHP

(PHP 4, PHP 5, PHP7)

تعيد الدالة func_get_args()‎ بعد استدعائها مصفوفةً عناصرها هي جميع المعاملات التي مُرِّرت للدالة المعرَّفة من طرف المستخدم.

الوصف

array func_get_args ( void )

تستعمل هذه الدالة غالبًا بالتزامن مع الدالة func_get_arg()‎ والدالة func_num_args()‎ وذلك للسماح للدوال المعرفة من طرف المستخدم بقبول عدد متغيّر من المعاملات.

القيم المعادة

عند استدعاء هذه الدالة ضمن دالة معرفة من قبل المستخدم، فإنَّها تعيد مصفوفة عناصرها هي جميع المعاملات التي مُرِّرت إلى تلك الدالة آنذاك.

سجل التغييرات

الإصدار	الوصف
5.3.0	يمكن أن تُستعمل هذه الدالة معاملًا لدالة أخرى.
5.3.0	أصبح بإمكان هذه الدالة أن تعيد القيمة FALSE إن استُدعيت خارج الدالة المعرفة من طرف المستخدم؛ أي مثلًا إن استُدعيت هذه الدالة من نطاق خارجي وليكن ملف ثم ضُمَّن هذا الملف باستعمال include أو require ضمن الدالة المعرَّفة من طرف المستخدم، فإنَّها تعيد FALSE. انظر المثال 2 في الأسفل لتوضيح هذه الفكرة.

الأخطاء والاستثناءات

تولِّد هذه الدالة تحذيرًا إذا استدعيت خارج دالة معرِّفة من طرف المستخدم.

أمثلة

مثال 1: استعمال الدالة func_get_args()‎ مع الدالة func_num_args()‎ وذلك لمعرفة عدد المعاملات الممرَّرة للدالة وطباعتها:

<?php
function foo()
{
    $numargs = func_num_args();
    echo "Number of arguments: $numargs \n";
    if ($numargs >= 2) {
        echo "Second argument is: " . func_get_arg(1) . "\n";
    }
    $arg_list = func_get_args();
    for ($i = 0; $i < $numargs; $i++) {
        echo "Argument $i is: " . $arg_list[$i] . "\n";
    }
}

foo(1, 2, 3);
?>

يعطي المثال السابق النتيجة التالية:

Number of arguments: 3 
Second argument is: 2
Argument 0 is: 1
Argument 1 is: 2
Argument 2 is: 3

مثال 2: استعمال الدالة func_get_args()‎ قبل إصدار PHP 5.3.0 وبعده: عرَّفنا في هذا المثال الدالة foo()‎ ثمَّ ضمنّا الملف fga.inc فيها والذي استدعينا فيه الدالة func_get_args()‎. مرَّرنا بعدئذٍ إلى تلك الدالة معاملين.

test.php
<?php
function foo() {
    include './fga.inc';
}

foo('First arg', 'Second arg');
?>

fga.inc
<?php

$args = func_get_args();
var_export($args);

?>

كان ناتج المثال السابق باستعمال إصدار سابق للإصدار 5.3 هو:

array (
  0 => 'First arg',
  1 => 'Second arg',
)

أما باستعمال إصدار PHP 5.3 وما بعده، فإن ناتج المثال سيكون:

Warning: func_get_args():  Called from the global scope - no function
context in /home/torben/Desktop/code/ml/fga.inc on line 3
false

مثال 3: استعمال func_get_args()‎ مع معاملات متغيرة (قيم المتغيرات) باستعمال الدالة byval ومعاملات مرجعية (عناوين المتغيرات) باستعمال الدالة byref: إنَّ المعامل المُمرَّر إلى الدالة الأولى byVal()‎ هو المتغير ‎$arg المُمرَّر بالقيمة، بينما سنمرره في الدالة الثانية بالمرجعية ‎&$arg (راجع قسم التمرير بالمرجعية في صفحة المراجع لمزيدٍ من التفاصيل).

<?php
function byVal($arg) {
    echo 'As passed     : ', var_export(func_get_args()), PHP_EOL;
    $arg = 'baz';
    echo 'After change  : ', var_export(func_get_args()), PHP_EOL;
}

function byRef(&$arg) {
    echo 'As passed     : ', var_export(func_get_args()), PHP_EOL;
    $arg = 'baz';
    echo 'After change  : ', var_export(func_get_args()), PHP_EOL;
}

$arg = 'bar';
byVal($arg);
byRef($arg);
?>

ناتج المثال السابق باستعمال إصدار PHP 7 سيكون:

As passed : array (
0 => 'bar',
)
After change : array (
0 => 'baz',
)
As passed : array (
0 => 'bar',
)
After change : array (
0 => 'baz',
)

أما ناتج المثال السابق باستعمال إصدار PHP 5 سيكون:

As passed : array (
0 => 'bar',
)
After change : array (
0 => 'bar',
)
As passed : array (
0 => 'bar',
)
After change : array (
0 => 'baz',
)

ملاحظات

• لا يمكن استخدام هذه الدالة معاملًا لدالة أخرى في إصدار قبل 5.3.0 إذ تعتمد على النطاق الحالي (current scope) لتحديد المعاملات. في حال اضطررت إلى ذلك (تمرير قيم هذه الدالة إلى دالة أخرى) فيمكن اسناد القيم إلى متغير ثم تمرير ذلك المتغير إلى الدالة المطلوبة.
• إن مُرِّرت المعاملات بالمرجعية، فإنَّ أي تغيير لتلك المعاملات سينعكس على القيم التي ترجعها هذه الدالة. ستُرجع القيم الحالية في PHP 7 نفسها إذا مرِّرت بالقيمة (معاملات متغيرة).
• تعيد هذه الدالة نسخة عن قيم المعاملات الممرَّرة إلى الدالة المعرَّفة فقط، ولن تأخذ القيم الافتراضية للمعاملات الاختيارية بالحسبان.

انظر أيضًا

• الدالّة func_get_arg()‎: إعادة وسيط من قائمة الوسائط.
• الدالّة func_num_args()‎: إعادة عدد الوسائط الممرّرة إلى الدّالة.
• الدالّة ReflectionFunctionAbstract::getNumberOfParameters()‎.

مصادر

• صفحة الدالة func_get_args في توثيق PHP الرسمي.