declare في PHP

(PHP 4, PHP 5, PHP 7)

تستخدم بنية declare لتعيين موجّهات التنفيذ (execution directives) لكتلة من الشيفرة، وصيغة declare مشابهة لبنى التحكم في تدفق الشيفرة.

الوصف

declare (directive)
    statement

يتيح الموجه تعيين سلوك كتلة (block). يمكن للغة في الوقت الحاضر أن تتعرف على ثلاثة أنواع من الموجهات فقط: موجه ticks (للمزيد من المعلومات حول موجه ticks انظر أدناه)، وموجه encoding (للمزيد من المعلومات حول موجه encoding انظر أدناه)، وموجه strict_types (للمزيد من المعلومات راجع قسم strict في صفحة معاملات الدالة).

عند معالجة الموجّهات أثناء تجميع ملف الشيفرة، تأخذ الموجّهات قيمًا حرفية "literal" فقط ولا يمكن استخدام المتغيّرات أو الثوابت، كما هو موضّح في المثال التالي.

<?php
// هذه الشيفرة صالحة
declare(ticks=1);

// هذه الشيفرة غير صالحة
const TICK_VALUE = 1;
declare(ticks=TICK_VALUE);
?>

تنفّذ اللغة العبارة الموجودة في كتلة declare، ولكن تعتمد عملية التنفيذ هذه وما يترتب عليها من نتائج على نوع الموجّه المعيَّن للكتلة.

يمكن استخدام بنية declare ضمن النطاق العام أيضًا، وستؤثّر في هذه الحالة على جميع الشيفرات التي تأتي بعدها (إن كانت declare في ملف مضمّن included فإنّها لن تؤثّر على الملف الأب).

<?php
// الشيفرتان التاليتان متشابهتان:

// يمكن استخدام هذه الشيفرة:
declare(ticks=1) {
    // الشيفرة كاملة هنا
}

// أو استخدام هذه الشيفرة:
declare(ticks=1);
// الشيفرة كاملة هنا
?>

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

الإصدار	الوصف
5.3.0	إضافة موجّه الترميز
7.0.0	إضافة موجّه strict_types

الموجه Ticks

المقصود بـ tick هو حدث يقع لكل عدد (N) من العبارات التي يمكن تطبيق هذا الموجه عليها، والتي تنفّذ من قبل المفسّر ضمن كتلة declare. يمكن تعيين قيمة N باستخدام العبارة ticks=N ضمن قسم الموجّه في كتلة declare.

لا يمكن تطبيق الموجه tick على جميع العبارات، وفي العادة لا يمكن تطبيق هذا الموجه على العبارات الشرطية والمعاملات.

يحدّد الحدث أو الأحداث التي تقع في كل tick باستخدام الدالة register_tick_function()‎. يقدم المثال التالي المزيد من التفاصيل. لاحظ أنّه يمكن وقوع أكثر من حدث لكل tick.

المثال 3: مثال على استخدام tick

<?php

declare(ticks=1);

// تستدعى دالة في حدث tick
function tick_handler()
{
    echo "tick_handler() called\n";
}

register_tick_function('tick_handler');

$a = 1;

if ($a > 0) {
    $a += 2;
    print($a);
}

?>

المثال 4: استخدام ticks

<?php

function tick_handler()
{
  echo "tick_handler() called\n";
}

$a = 1;
tick_handler();

if ($a > 0) {
    $a += 2;
    tick_handler();
    print($a);
    tick_handler();
}
tick_handler();

?>

راجع أيضًا register_tick_function()‎ و unregister_tick_function()‎.

الترميز Encoding

يمكن تحديد الترميز الخاص بكل شيفرة باستخدام موجّه الترميز.

المثال 5: التصريح عن الترميز الخاص بالشيفرة

<?php
declare(encoding='ISO-8859-1');
// الشيفرة هنا
?>

تنبيه: عند استخدام declare مع مجال الأسماء namespace، فإن الصيغة الصحيحة الوحيدة لـ declare هي: declare(encoding='...')‎;‎ حيث تستبدل ... بقيمة الترميز المطلوبة. يؤدي استخدام الصيغة declare(encoding='...') {}‎ في إطلاق خطأ إعرابي عند استخدام declare مع مجال الأسماء.

مصادر

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