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

(PHP 4, PHP 5, PHP 7)

تُعيد الدالّة func_get_arg()‎ وسيطًا من قائمة الوسطاء.

الوصف

mixed func_get_arg ( int $arg_num )

تحصل الدالّة func_get_arg()‎ على وسيط من قائمة وسطاء الدّالة المعرّفة من قبل المستخدم.

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

المعاملات

arg_num

فهرس الوسيط المُراد الحصول على قيمته. لاحظ أنَّه تُعَدّ وسائط الدّالة بدءًا من الصفر.

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

تُعيد الدالّة func_get_arg()‎ الوسيط المحدّد، أو تُعيد FALSE في حال حدوث الخطأ.

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

الإصدار	الوصف
5.3.0	يمكن الآن استخدام هذه الدالة في قائمة المعاملات.
5.3.0	إذا استُدعيت هذه الدالّة من النطاق الخارجي لملف مُضمَّن من خلال استدعاء include أو  require من داخل دالّة في الملف المستدعي، فستولد تحذيرًا وتُعيد FALSE.

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

تولّد الدّالة func_get_arg()‎ تحذيرًا إذا استدعيت من خارج دالة معرّفة من قبل المستخدم، أو إذا كانت قيمة arg_num أكبر من عدد الوسطاء الممرّرة.

أمثلة

المثال 1: مثال عن استخدام الدالّة func_get_arg()‎

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

foo(1, 2, 3);
?>

سينتج المثال السابق الناتج الآتي:

Number of arguments: 3
Second argument is: 2

المثال 2: مثال عن استخدام الدالّة func_get_arg()‎ قبل و بعد الاصدار PHP 5.3

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

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

fga.inc
<?php

$arg = func_get_arg(1);
var_export($arg);

?>

سينتج المثال السابق قبل الاصدار PHP 5.3  الناتج الآتي :

'Second arg'

سينتج المثال السابق في الاصدار  PHP 5.3 ومابعد الناتج الآتي :

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

المثال 3: مثال عن استخدام func_get_arg()‎ بوسائط تُمرَّر بالقيمة وبالمرجعية

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

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

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

ناتج المثال السابق في الاصدار PHP 7 هو:

As passed : 'bar'
After change : 'baz'
As passed : 'bar'
After change : 'baz'

ناتج المثال السابق في الاصدار PHP 5 هو:

As passed : 'bar'
After change : 'bar'
As passed : 'bar'
After change : 'baz'

ملاحظات

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

إذا مُرّرت الوسائط بواسطة المرجعية، فإنّ أي تغيير في الوسائط سينعكس على القيم المُعادة باستخدام هذه الدّالة. بدءًا من الاصدار PHP 7 ستعاد القيم الحاليّة أيضًا إذا مُرّر الوسائط بواسطة القيمة.

هذه الدّالة تعيد نسخة من الوسائط الممرّرة فقط، ولا تهتم بالوسائط الافتراضية (غير الممرَّرة إلى الدالة مباشرةً).

انظر أيضًا

• الدالّة ()func_num_args: إعادة عدد الوسائط الممرّرة إلى الدّالة.
• الدالّةfunc_get_args() ‎: إعادة مصفوفة فيها الوسائط المُمرَّرة إلى الدالة.

مصادر

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