عرض مصدر PHP/magic

<noinclude>{{DISPLAYTITLE:التوابع السحرية في PHP}}</noinclude>
التوابع السحرية في أصناف PHP هي <code>‎__construct()</code>‎ و <code>‎__destruct()</code>‎ و <code>‎__call()</code>‎ و <code>‎__callStatic()</code>‎ و <code>‎__get()</code>‎ و <code>‎__set()‎</code> و ‎<code>__isset()</code>‎ و ‎<code>__unset()‎‎</code> و <code>‎__sleep()</code>‎ و ‎<code>__wakeup()</code>‎ و <code>‎__toString()‎</code> و ‎<code>__invoke()‎</code> و ‎<code>_‎_set_state()‎</code> و ‎<code>__clone()</code>‎ و <code>‎__debugInfo()</code>‎. ولا يمكنك استخدام دوالّ تحمل هذه الأسماء في أي صنف ما لم تكن ترغب في الاستفادة من الوظيفة السحرية التي تتمتّع بها.

تحذير: تحجز PHP جميع الدوال التي تبدأ بالرمز <code>__</code> كدوال سحرية؛ لذا ينصح بعدم تسمية دوالك الخاصة بأسماء تبدأ بهذا الرمز ما لم تكن ترغب في استخدام الدوال السحرية.

== ‎<code>__sleep()‎</code> و <code>‎__wakeup()</code>‎ ==
<syntaxhighlight lang="php">

public array __sleep ( void )
void __wakeup ( void )
</syntaxhighlight>

تتأكد الدالة <code>[[PHP/serialize|serialize()‎]]</code> من امتلاك الصنف للتابع السحري <code>‎__sleep()</code>‎، فإن كان موجودًا فستُنفَّذ تلك الدالة قبل إجراء أيّ عملية سَلْسَلَة (serialization). يمكن لهذه الدالة أن تنظّف الكائن ومن المفترض أن تعيد مصفوفة تحمل أسماء جميع المتغيرات الخاصة بالكائن الذي ستجرى عليه عملية السَلْسَلَة. وإن لم يعد التابع أي شيء فإنّ السلسلة تجري على NULL ويطلق خطأ من نوع E_NOTICE.

ملاحظة:  لا يمكن للتابع <code>‎__sleep()</code>‎ أن يعيد أسماء الخصائص من نوع private في الصنف الأب. يؤدي القيام بذلك إلى إطلاق خطأ من المستوى E_NOTICE، ويمكن بدلًا من ذلك استخدام الواجهة <code>Serializable</code>.

إنّ الهدف من استخدام ‎<code>__sleep()</code>‎ هو تنفيذ البيانات المعلّقة أو إجراء مهام التنظيف المشابهة، وهذا التابع مفيد في حال وجود كائنات كبيرة جدًّا لا تحتاج إلى حفظها بالكامل.

يعمل التابع <code>[[PHP/unserialize|unserialize()‎]]</code> على التأكد من وجود الدالة السحرية ‎<code>__wakeup()</code>‎، وفي حال وجودها، يمكن لهذه الدالة إعادة هيكلة أي مصدر قد يمتلكه الكائن.

إنّ الهدف من استخدام <code>‎__wakeup()</code>‎ هو إعادة إجراء الاتصال مع قواعد البيانات التي يمكن أن تكون قد قطعت أثناء عملية السلسلة إضافة إلى إجراء مهامّ إعادة تأهيل أخرى.

المثال 1: التابعان <code>sleep</code> و <code>wakeup</code>

<syntaxhighlight lang="php">

<?php
class Connection
{
    protected $link;
    private $dsn, $username, $password;
    
    public function __construct($dsn, $username, $password)
    {
        $this->dsn = $dsn;
        $this->username = $username;
        $this->password = $password;
        $this->connect();
    }
    
    private function connect()
    {
        $this->link = new PDO($this->dsn, $this->username, $this->password);
    }
    
    public function __sleep()
    {
        return array('dsn', 'username', 'password');
    }
    
    public function __wakeup()
    {
        $this->connect();
    }
}?>
</syntaxhighlight>

== <code>‎__toString()‎</code> ==
<syntaxhighlight lang="php">

public string __toString ( void )
</syntaxhighlight>

يتيح التابع <code>‎__toString()‎</code> للصنف اختيار طريقة تفاعله في حال عومِل معاملة السلاسل النصية. فعلى سبيل المثال، ما الذي ستطبعه العبارة <code>echo $obj</code>. يجب أن يعيد هذا التابع سلسلة نصية وإلا فستطلق اللغة خطأ من المستوى E_RECOVERABLE_ERROR.

تحذير: لا يمكنك إطلاق استثناء من داخل التابع <code>‎__toString()</code>‎ وسيؤدي القيام بذلك إلى إطلاق خطأ من نوع fatal.

المثال 2: مثال بسيط على استخدام التابع <code>‎__toString()</code>‎
<syntaxhighlight lang="php">

<?php
// التصريح عن صنف بسيط
class TestClass
{
    public $foo;

    public function __construct($foo)
    {
        $this->foo = $foo;
    }

    public function __toString()
    {
        return $this->foo;
    }
}

$class = new TestClass('Hello');
echo $class;
?>
</syntaxhighlight>

يعطي المثال السابق النتيجة التالية:
<syntaxhighlight lang="php">

Hello
</syntaxhighlight>

يجدر الانتباه إلى أنّ التابع <code>‎__toString()</code>‎ قبل الإصدار 5.2.0 كان يستدعى عند دمجه مباشرة مع <code>[[PHP/echo|echo]]</code> أو <code>[[PHP/print|print]]</code> فقط، ولكن منذ الإصدار 5.2.0 أصبح بالإمكان استدعاء هذا التابع في أي سياق نصّي (مثل: <code>[[PHP/printf|printf()‎]]</code> مع المعدِّلات ‎%s) وليس في أي سياق من أنواع أخرى (مثل المعدِّلات ‎%d). في الإصدار 5.2.0 يؤدي تحويل الكائنات إلى سلاسل نصّية دون استخدام التابع ‎<code>__toString()‎</code> إلى إطلاق خطأ من المستوى E_RECOVERABLE_ERROR.

== <code>‎__invoke()‎</code> ==
<syntaxhighlight lang="php">

mixed __invoke ([ $... ] )
</syntaxhighlight>

تستدعى الدالة ‎<code>__invoke()</code>‎ عندما تحاول الشيفرة استدعاء كائن كدالة.

ملاحظة: هذه الميزة متوفّرة في الإصدار 5.3.0 وما بعده من PHP.

المثال 3: استخدام التابع <code>‎__invoke()</code>‎
<syntaxhighlight lang="php">

<?php
class CallableClass
{
    public function __invoke($x)
    {
        var_dump($x);
    }
}
$obj = new CallableClass;
$obj(5);
var_dump(is_callable($obj));
?>
</syntaxhighlight>

يعطي المثال السابق المخرجات التالية:
<syntaxhighlight lang="php">

int(5)
bool(true)

</syntaxhighlight>

== <code>‎__set_state()‎</code> ==
<syntaxhighlight lang="php">
static object __set_state ( array $properties )
</syntaxhighlight>يستدعى هذا التابع الساكن عند تصدير الأصناف باستخدام الدالة <code>[[PHP/var_export|var_export()‎]]</code> في الإصدار 5.1.0 من PHP وما بعده.

يأخذ هذا التابع معاملًا واحدًا وهو مصفوفة تتضمن الخائص المصدَّرة على هيئة <code>‎array('property' => value, ...)‎</code>.

المثال 4: استخدام ‎<code>__set_state()‎</code> (الإصدار 5.1.0 وما بعده من PHP)
<syntaxhighlight lang="php">

<?php

class A
{
    public $var1;
    public $var2;

    public static function __set_state($an_array)
    // في الإصدار 5.1.0 وما بعده
    {
        $obj = new A;
        $obj->var1 = $an_array['var1'];
        $obj->var2 = $an_array['var2'];
        return $obj;
    }
}

$a = new A;
$a->var1 = 5;
$a->var2 = 'foo';

eval('$b = ' . var_export($a, true) . ';'); // $b = A::__set_state(array(
                                            //    'var1' => 5,
                                            //    'var2' => 'foo',
                                            // ));
var_dump($b);

?>
</syntaxhighlight>

يعطي المثال السابق النتائج التالية:
<syntaxhighlight lang="php">

object(A)#2 (2) {
  ["var1"]=>
  int(5)
  ["var2"]=>
  string(3) "foo"
}
</syntaxhighlight>

ملاحظة: عند تصدير الكائن لا تتحقّق الدالة var_export ممّا إذا كان التابع ‎<code>__set_state()</code>‎ قد استخدم بواسطة كائن الصنف؛ لذا فإنّ إعادة استيراد مثل هذه الكائنات سينتهي بالفشل إن لم يُستخدم التابع ‎<code>__set_state()‎</code>، ويؤثّر هذا الأمر بشكل خاصّ على بعض الأصناف الداخلية. تقع مسؤولية التحقّق من الكائنات التي سيعاد استيرادها والأصناف التي ستستخدم التابع ‎<code>__set_state()‎</code> على كاهل المبرمج.

== ‎<code>__debugInfo()‎</code> ==
<syntaxhighlight lang="php">

array __debugInfo ( void )
</syntaxhighlight>

يستدعى هذا التابع بواسطة الدالة <code>[[PHP/var_dump|var_dump()‎]]</code> عند إسقاط dumping الكائن للحصول على الخصائص التي يجب عرضها. إن لم يُعرّف التابع على الكائن فستعرض الخصائص بجميع أنواعها public و protected و private.

أضيفت هذه الميزة إلى الإصدار 5.6.0 من PHP.

المثال 5: استخدام <code>‎__debugInfo()‎</code>
<syntaxhighlight lang="php">

<?php
class C {
    private $prop;

    public function __construct($val) {
        $this->prop = $val;
    }

    public function __debugInfo() {
        return [
            'propSquared' => $this->prop ** 2,
        ];
    }
}

var_dump(new C(42));
?>
</syntaxhighlight>

يعطي المثال السابق المخرجات التالية:
<syntaxhighlight lang="php">

object(C)#1 (1) {
  ["propSquared"]=>
  int(1764)
}
</syntaxhighlight>

== مصادر ==
* [http://php.net/manual/en/language.oop5.magic.php صفحة Magic Methods في توثيق PHP الرسمي.]
[[تصنيف:PHP|{{SUBPAGENAME}}]]
[[تصنيف:PHP OOP|{{SUBPAGENAME}}]]