toString و debugInfo

جزء من قسم Object Oriented Programming في رحلة PHP على Coddy — الدرس 45 من 91.

تسمح لك الطريقة __toString() بتحديد كيفية تمثيل الكائن كسلسلة نصية. يتم استدعاء ذلك تلقائيًا عند استخدام كائن في سياق سلسلة نصية، كما هو الحال مع echo أو دمج السلاسل النصية.

<?php
class User {
    public function __construct(
        private string $name,
        private string $email
    ) {}
    
    public function __toString(): string {
        return $this->name . " (" . $this->email . ")";
    }
}

$user = new User("Alice", "alice@example.com");
echo $user;

الناتج:

Alice (alice@example.com)

تتحكم الطريقة __debugInfo() في المعلومات التي تظهر عند استخدام var_dump() على كائن ما. هذا مفيد لإخفاء البيانات الحساسة أو إظهار القيم المحسوبة أثناء تصحيح الأخطاء:

<?php
class BankAccount {
    public function __construct(
        private string $accountNumber,
        private float $balance,
        private string $pin
    ) {}
    
    public function __debugInfo(): array {
        return [
            'accountNumber' => '****' . substr($this->accountNumber, -4),
            'balance' => $this->balance,
            'pin' => '[HIDDEN]'
        ];
    }
}

$account = new BankAccount("1234567890", 1500.00, "9876");
var_dump($account);

المخرجات:

object(BankAccount)#1 (3) {
  ["accountNumber"]=>
  string(8) "****7890"
  ["balance"]=>
  float(1500)
  ["pin"]=>
  string(8) "[HIDDEN]"
}

لاحظ كيف تُرجع __debugInfo() مصفوفة من أزواج المفتاح-القيمة التي تحل محل تفريغ الخصائص الافتراضي. يتم إخفاء رقم الـ PIN الحساس، ويتم قناع رقم الحساب جزئيًا - وهو أمر مثالي لتصحيح الأخطاء بشكل آمن.

التحدي

سهل

دعونا نبني نظاماً لإدارة بيانات الاعتماد يوضح كلاً من الطرق السحرية (magic methods) ‏__toString() و __debugInfo(). ستقوم بإنشاء فئة (class) تعرض معلومات سهلة القراءة للمستخدم عند طباعتها، مع حماية البيانات الحساسة أثناء عملية التصحيح (debugging).

ستقوم بتنظيم الكود الخاص بك عبر ملفين:

Credential.php — أنشئ فئة Credential تقوم بتخزين معلومات تسجيل الدخول بشكل آمن. استخدم خاصية constructor promotion لتعريف خصائص خاصة (private properties) لكل من $username (سلسلة نصية)، و $password (سلسلة نصية)، و $lastLogin (سلسلة نصية). قم بتنفيذ طريقتين سحريتين:
- __toString() — تعيد سلسلة نصية سهلة القراءة: "User: [username] (Last login: [lastLogin])". لاحظ أن كلمة المرور لا يتم كشفها أبداً في التمثيل النصي.
- __debugInfo() — تعيد مصفوفة لـ var_dump() تعرض اسم المستخدم كما هو، وتخفي كلمة المرور بإظهار "[PROTECTED]" فقط، وتعرض تاريخ آخر تسجيل دخول بشكل طبيعي.
main.php — قم بتضمين ملف Credential. ستتلقى ثلاثة مدخلات: اسم المستخدم، وكلمة المرور، وتاريخ آخر تسجيل دخول. أنشئ كائناً (instance) من Credential بهذه القيم. أولاً، قم بعمل echo لكائن credential مباشرة (هذا سيؤدي لاستدعاء __toString()). ثم في سطر جديد، استخدم var_dump() على الكائن لرؤية مخرجات التصحيح المحمية.

توفر طريقة __toString() وسيلة نظيفة وآمنة لعرض بيانات الاعتماد دون كشف كلمة المرور. وتضمن طريقة __debugInfo() أنه حتى أثناء عملية التصحيح، تظل المعلومات الحساسة مخفية — وهي ممارسة بالغة الأهمية عند التعامل مع بيانات المصادقة.

ورقة مرجعية

تحدد الطريقة __toString() كيفية تمثيل الكائن كسلسلة نصية عند استخدامه مع echo أو دمج السلاسل النصية:

<?php
class User {
    public function __construct(
        private string $name,
        private string $email
    ) {}
    
    public function __toString(): string {
        return $this->name . " (" . $this->email . ")";
    }
}

$user = new User("Alice", "alice@example.com");
echo $user; // Alice (alice@example.com)

تتحكم الطريقة __debugInfo() في المعلومات التي تظهر عند استخدام var_dump() على كائن ما. وهي تعيد مصفوفة من أزواج المفتاح والقيمة لعرضها:

<?php
class BankAccount {
    public function __construct(
        private string $accountNumber,
        private float $balance,
        private string $pin
    ) {}
    
    public function __debugInfo(): array {
        return [
            'accountNumber' => '****' . substr($this->accountNumber, -4),
            'balance' => $this->balance,
            'pin' => '[HIDDEN]'
        ];
    }
}

$account = new BankAccount("1234567890", 1500.00, "9876");
var_dump($account);
// يعرض رقم الحساب المقنع والرمز السري المخفي

هذه الطرق مفيدة لإخفاء البيانات الحساسة أو تخصيص مخرجات الكائن لسياقات مختلفة.

جرّب بنفسك

<?php

require_once 'Credential.php';

// قراءة المدخلات
$username = trim(fgets(STDIN));
$password = trim(fgets(STDIN));
$lastLogin = trim(fgets(STDIN));

// TODO: إنشاء كائن (instance) من Credential باستخدام قيم المدخلات

// TODO: طباعة كائن الاعتماد (يستدعي __toString())

// TODO: استخدم var_dump() على الكائن لرؤية مخرجات التصحيح المحمية

?>