الجلسات

خيارات session_start()‎

يمكننا تمرير مصفوفة من خيارات الملف php.ini المعتمدة على الجلسة (session) إلى الدالة session_start، مثال:

<?php
    if (version_compare(PHP_VERSION, '7.0.0') >= 0) {
        // php >= 7 
        session_start([
            'cache_limiter' => 'private',
            'read_and_close' => true,
        ]);
    } else {
        // php < 7 
        session_start();
    }
?>

تقدّم أيضًا هذه الميزة إعداد php.ini جديد يسمى lazy_write قيمته الافتراضية true ويعني أن بيانات الجلسة يُعاد كتابتها فقط إذا تغيرت.

قفل الجلسة

تكتب PHP بيانات الجلسة في ملف موجود على الخادم، عندما يُرسَل طلب لبدء الجلسة باستخدام session_start()‎ إلى سكربت PHP تقفل PHP ملف الجلسة لمنع/انتظار طلبات أخرى قادمة لنفس session_id للمتابعة‌ وبسبب ذلك ستبقى الطلبات الأخرى عالقة عند session_start()‎ حتى يُلغى قفل ملف الجلسة.

يبقى ملف الجلسة مقفلًا حتى ينتهي السكربت أو تُغلق الجلسة يدويًا، لتجنب هذه الحالة أي تجنب منع تعطيل عدة طلبات يمكننا أن نبدأ الجلسة ونغلقها مما سيحرر القفل من ملف الجلسة ويسمح بمتابعة الطلبات الباقية.

// php < 7.0
// بدء الجلسة
session_start();

// كتابة بيانات في ملف الجلسة
$_SESSION['id'] = 123;
// عندها يُقفل ملف الجلسة لذا تتعطل الطلبات

// إغلاق الجلسة وتحرير القفل
session_write_close();

قد تتساءل الآن كيف ستُقرأ قيم الجلسة إذا كانت الجلسة مغلقة؟ تبقى الجلسة متاحة حتى بعد إغلاقها لذا بإمكاننا قراءة بياناتها.

echo $_SESSION['id']; // 123

يتوفر بدءًا من الإصدار php 7.0 خيارات الجلسة read_only وread_write وlazy_write لذا من الممكن ألا نستخدم session_write_close()‎.

معالجة بيانات الجلسة

إنّ المتغير ‎$_SESSION عبارة عن مصفوفة وبإمكانك استعادتها أو معالجتها مثل أي مصفوفة عادية.

<?php
// بدء الجلسة
session_start();

// تخزين قيمة في الجلسة
$_SESSION['id'] = 342;

// استخدام تقليدي لقيم جلسة ربما قد ضُبطت في جلسة سابقة
if(!isset($_SESSION["login"])) {
    echo "Please login first";
    exit;
}

// login يمكننا الآن أن نستخدم
$user = $_SESSION["login"];

// PHP 7 في Null الحصول على قيمة من بيانات الجلسة أو القيمة الافتراضية باستخدام عامل تجميع
$name = $_SESSION['name'] ?? 'Anonymous';

لاحظ أنّه إذا خزّنت كائن في الجلسة فيمكنك استعادته بأمان إذا كان لديك محمّل تلقائي للصنف أو إذا كنت قد حمّلت الصنف مسبقًا، وإلا سيخرج الكائن كالنوع ‎__PHP_Incomplete_Class مما قد يسبب الأعطال لاحقًا.

تحذير: يمكن أن تتعرض بيانات الجلسة لهجوم اختطاف الجلسة (session hijacking) وهذا موضّح في كتاب أمن PHP المتقدم: من مبادئ أمن التطبيق إلى تنفيذ حماية xss - الفصل السابع: منع هجوم اختطاف الجلسة لذا يُنصح بعدم تخزين أي معلومات شخصية في المصفوفة ‎$_SESSION وخاصةً أرقام بطاقات الائتمان والمعرّفات الحكومية وكلمات المرور إنما يمكن تخزين المعلومات الأقل خطرًا مثل الأسماء وعناوين البريد الإلكتروني وأرقام الهاتف وغيرها مما يسمح للمخترق بانتحال شخصية مستخدم شرعي. كقاعدة عامة استخدم الجلسة لتخزين المعلومات الشخصية قليلة الأهمية.

تدمير كامل الجلسة

يمكنك استخدام الدالة session_destroy()‎ لتدمير الجلسة، بفرض لدينا الجلسة التالية:

Array([firstname] => Jon, [id] => 123)

ابدأ الجلسة أولًا بعدها يمكنك حذف كل القيم الموجودة في المتغير ذي النطاق العام العالي SESSION، إذا أهملت هذا الحذف فإنّ كل المتغيرات العامة المخزنة في المتغير SESSION ستبقى موجودة حتى لو دُمِّرت الجلسة.

session_start();
$_SESSION = array();

// إذا كنت ترغب في تدمير الجلسة يجب حذف ملف ارتباط الجلسة أيضًا
// الشيفرة التالية ستُدمر الجلسة وليس فقط بياناتها
if (ini_get("session.use_cookies")) {
    $params = session_get_cookie_params();
    setcookie(session_name(), '', time() - 42000,
    $params["path"], $params["domain"],
    $params["secure"], $params["httponly"]
    );
}

// يمكنك الآن تدمير الجلسة
session_destroy();

إنّ استخدام session_destroy()‎ مختلف عن استخدام ‎$_SESSION = array();‎ التي ستزيل كل القيم الموجودة في المتغير ذي النطاق العام العالي SESSION ولن تدمر نسخة الجلسة المخزّنة الفعلية.

ملاحظة: نستخدم ‎$_SESSION = array();‎ بدلًا من session_unset()‎ لأنّ توثيق PHP ينص على أنّ استخدام session_unset()‎ فقط للشيفرة القديمة المهملة التي لا تستخدم ‎$_SESSION.

بدء جلسة آمنة دون أخطاء

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

if (version_compare(PHP_VERSION, '7.0.0') >= 0) {
    if(session_status() == PHP_SESSION_NONE) {
        session_start(array(
            'cache_limiter' => 'private',
            'read_and_close' => true,
        ));
    }
}
else if (version_compare(PHP_VERSION, '5.4.0') >= 0)
{
    if (session_status() == PHP_SESSION_NONE) {
        session_start();
    }
}
else
{
    if(session_id() == '') {
        session_start();
    }
}

يمكن أن يساعدك هذا كثيرًا لتجنب خطأ session_start.

اسم الجلسة

التحقق من إنشاء ملفات تعريف ارتباط الجلسة

اسم الجلسة هو الاسم الذي يستخدمه ملف تعريف الارتباط (cookie) لتخزين الجلسات، يمكنك أن تستخدم هذا لتفحص فيما إذا اُنشئت ملفات تعريف الارتباط لجلسة ما:

if(isset($_COOKIE[session_name()])) {
    session_start();
}

لاحظ أنّ هذه الطريقة لا تفيد بشكلٍ عام إلا إذا كنت لا تريد إنشاء ملفات تعريف الارتباط دون ضرورة.

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

يمكنك استدعاء الدالة session_name()‎ لتغيير اسم الجلسة.

// ضبط اسم الجلسة
session_name('newname');

// بدء الجلسة
session_start();

إذا لم يُمرَّر وسيط إلى الدالة session_name()‎ سيُرجع اسم الجلسة الحالي، يجب أن يحتوي الاسم على محارف أبْجَعَددية فقط وأن يكون قصيرًا ووصفيًا (للمستخدمين الذين مكّنوا تحذيرات ملفات تعريف الارتباط)، لا يمكن أن يحتوي الاسم على أرقام فقط إنما يجب وجود حرف واحد على الأقل وإلا سيُنشأ معرّف جلسة جديد في كل مرة.

ملفات تعريف الارتباط

تأخذ الدالة setcookie()‎ المعاملات التالية:

ملف تعريف ارتباط HTTP هو جزء بيانات صغير يُرسل من موقع ما ويُخزَّن على حاسوب المستخدم من قبل متصفح ويب العميل أثناء تصفح المستخدم لمواقع الإنترنت.

تعديل ملف تعريف الارتباط

يمكن أن تُعدَّل قيمة ملف تعريف الارتباط (cookie) بإعادة ضبط الملف، بفرض لدينا ملف تعريف ارتباط باسم "user":

setcookie("user", "John", time() + 86400, "/");

ملفات تعريف الارتباط هي جزء من ترويسة HTTP، لذا يجب أن تُستدعى setcookie()‎ قبل أن يُرسل أي خرج إلى المتصفح.

تأكد عند تعديل ملف الارتباط أنّ المعاملات path وdomain للدالة setcookie()‎ تطابق ملف تعريف الارتباط الموجود وإلا سيُنشأ ملف جديد.

سيُشفَّر قسم القيمة من ملف تعريف الارتباط تلقائيًا عند إرساله وعندما يُستقبل سيُفك تشفيره ويُسند إلى متغير بنفس اسم الملف.

ضبط ملف تعريف الارتباط

يُضبط ملف تعريف الارتباط باستخدام الدالة setcookie()‎، وبما أنّ ملفات تعريف الارتباط جزء من ترويسة HTTP فيجب أن تُضبط قبل إرسال أي خرج إلى المتصفح، مثال:

setcookie("user", "Tom", time() + 86400, "/");

الوصف:

• أنشئ ملف تعريف ارتباط بالاسم user
• قيمة الملف Tom (معامل اختياري)
• ستنتهي صلاحية هذا الملف بعد يوم واحد (86400 ثانية) (معامل اختياري)
• يتوفر الملف على كامل الموقع / (معامل اختياري)
• يُرسل الملف عبر HTTPS فقط (معامل اختياري)
• لا يمكن للغات البرمجة من جهة العميل مثل جافاسكربت الوصول لهذا الملف (معامل اختياري)

يمكن الوصول لملف تعريف الارتباط المُنشأ أو المُعدَّل في الطلبات اللاحقة فقط (عند تطابق المسار والمجال) لأنّ المتغير ذو النطاق العام العالي ‎$_COOKIE لا يُملأ بالبيانات الجديدة مباشرةً.

التحقق من ضبط ملف تعريف ارتباط

يمكن استخدام الدالة isset()‎ للمتغير ذو النطاق العام العالي ‎$_COOKIE للتحقق من ضبط ملف تعريف ارتباط.

// PHP <7.0
if (isset($_COOKIE['user'])) {
    // ضُبط ملف تعريف الارتباط
    echo 'User is ' . $_COOKIE['user'];
else {
    // لم يُضبط ملف تعريف الارتباط
    echo 'User is not logged in';
}

// PHP 7.0+
echo 'User is ' . $_COOKIE['user'] ?? 'User is not logged in';

حذف ملف تعريف ارتباط

يمكنك ضبط الختم الزمني لصلاحية ملف تعريف الارتباط إلى وقت ما في الماضي ليُحذف هذا الملف:

setcookie('user', '', time() - 3600, '/');

تأكد عند حذف ملف تعريف ارتباط من توافق المعاملات path وdomain للدالة setcookie()‎ مع معلومات الملف الذي تريد حذفه وإلا سيُنشأ ملف تعريف ارتباط جديد تنتهي صلاحيته مباشرةً.

ومن الجيّد أيضًا أن تلغي قيمة المتغير ‎$_COOKIE في حال كانت الصفحة الحالية تستخدمه:

unset($_COOKIE['user']);

استعادة ملف تعريف ارتباط

استعادة وعرض ملف تعريف ارتباط اسمه User

يمكن أن نستعيد قيمة ملف تعريف ارتباط باستخدام المتغير العام ‎$_COOKIE، فمثلًا إذا كان لدينا ملف تعريف ارتباط اسمه user نستعيده بالشكل التالي:

echo $_COOKIE['user'];

عميل بروتوكول SOAP (‏Simple Object Access Protocol)

المعاملات التي تأخذها الدالة SoapClient هي:

النمط WSDL

ننشئ كائنًا جديدًا من الصنف SoapClient ونمرر رابط ملف WSDL ومصفوفة خيارات اختيارية.

// WSDL إنشاء كائن عميل جديد باستخدام رابط
$soap = new SoapClient('https://example.com/soap.wsdl', [

    // هذه المصفوفة وقيمها اختيارية
    'soap_version' => SOAP_1_2,
    'compression' => SOAP_COMPRESSION_ACCEPT |             SOAP_COMPRESSION_GZIP,
    'cache_wsdl' => WSDL_CACHE_BOTH,

    # تساعد هذه الخيارات في تنقيح الأخطاء
    'trace' => TRUE,
    'exceptions' => TRUE
]);

ثم نستخدم الكائن ‎$soap لاستدعاء توابع SOAP.

$result = $soap->requestData(['a', 'b', 'c']);

النمط Non-WSDL

يشبه هذا النمط النمط السابق إلا أننا نمرر NULL مكان ملف WSDL ويجب أن نتأكد من ضبط الخيارات location وuri.

$soap = new SoapClient(NULL, [
    'location' => 'https://example.com/soap/endpoint',
    'uri' => 'namespace'
]);

خرائط الصنف (Classmaps)

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

class MyAddress {
    public $country;
    public $city;
    public $full_name;
    public $postal_code; // or zip_code
    public $house_number;
}

class MyBook {
    public $name;
    public $author;
    // SOAP بإضافة دوال مفيدة إلى الكائنات المُعادة من عمليات classmap يسمح لنا
    public function getShortDescription() {
        return "{$this->name}, written by {$this->author}";
    }
}

$soap_client = new SoapClient($link_to_wsdl, [
// Other parameters
    "classmap" => [
        // ‫ يعيد الصنف كسلسلة نصية ‎::class
        "Address" => MyAddress::class, 
        "Book" => MyBook::class,
    ]
]);

بعد ضبط خريطة الصنف، عندما تجري عملية معينة تعيد النوع Address أو Book فإنّ SoapClient ينشئ نسخة من ذلك الصنف ويملأ الحقول بالبيانات ويعيده عند استدعاء العملية.

بفرض لدينا التابع getAddress(1234)‎ يعيد كائن Address وفقًا للمعرّف (ID) الموجود في قاعدة البيانات والتابع getBook(1234)‎ يعيد كائن Book وفقًا للمعرّف (ID) الموجود في قاعدة البيانات.

$address = $soap_client->getAddress(1234);

// (1)
echo $address->country;

$book = $soap_client->getBook(124);

// (2)
echo $book->getShortDescription();

// (3)
$author = $soap_client->getAuthor(1234);

// (4)
echo $author->name;

في الموضع (1) أصبح المتغير ‎$address‎ من النوع MyAddress وذلك حسب classmap. في الموضع (2) لا يمكننا استخدام دوال أخرى معرفة في الصنف MyBook. في الموضع (3) أي نوع معرف في WSDL غير معرف في classmap سيصبح كائن StdClass عادي. في الموضع (4) لا يوجد خريطة صنف للنوع Author لذا فإنّ ‎$author هو StdClass عادي، أي لا يزال بإمكاننا الوصول للحقول لكن دون استكمال تلقائي ولا دوال مخصصة لتعريف الكائنات.

تتبع طلب ورد SOAP

قد نحتاج أحيانًا لتتبع ما الذي يُرسل ويُستقبل في طلب SOAP، تعيد التوابع التالية صيغة XML الموجودة في الطلب والرد:

SoapClient::__getLastRequest()
SoapClient::__getLastRequestHeaders()
SoapClient::__getLastResponse()
SoapClient::__getLastResponseHeaders()

لنفرض مثلًا أنه لدينا الثابت ENVIRONMENT وعندما تُضبط قيمته لتكون DEVELOPMENT فإننا نريد طباعة كل المعلومات إذا رمى استدعاء التابع getAddress خطأً، يمكن أن يكون الحل كالتالي:

try {
    $address = $soap_client->getAddress(1234);
} catch (SoapFault $e) {
    if (ENVIRONMENT === 'DEVELOPMENT') {
        var_dump(
            $soap_client->__getLastRequestHeaders()
            $soap_client->__getLastRequest(),
            $soap_client->__getLastResponseHeaders(),
            $soap_client->__getLastResponse()
        );
    }
    ...
}

خادم SOAP أساسي

function test($x) {
    return $x; 
} 

$server = new SoapServer(null, array('uri' => "http://test-uri/")); $server->addFunction("test"); 
$server->handle();

استخدام مكتبة cURL

الاستخدام الأساسي (طلبات GET)

تعد cURL أداة لنقل البيانات بصياغة رابط (URL)، وتدعم HTTP وFTP وSCP والعديد من البروتوكولات الأخرى (بدءًا من الإصدار 7.19.4). تذكر أنّك تحتاج إلى تنصيب وتمكين إضافة cURL لاستخدامها.

// (1)
if(!extension_loaded("curl")) {
    die("cURL extension not loaded! Quit Now.");
}

// بدء السكربت
// (2)
$curl = curl_init();

// ضبط الرابط والخيارات الأخرى
curl_setopt($curl, CURLOPT_URL, "http://www.example.com");

// تنفيذ وتمرير النتيجة إلى المتصفح
curl_exec($curl);

// cURL إغلاق مورد
curl_close($curl);

في الموضع (1) سكربت بسيط يفحص إن كانت إضافة cURL محمّلة أم لا. في الموضع (2) إنشاء مورد cURL جديد و‎$curl هو معالج المورد.

طلبات POST

يمكنك استخدام cURL إذا أردت محاكاة إجراء نموذج HTML يستخدم الطريقة POST:

// في مصفوفة POST بيانات
$post = [
    'a' => 'apple',
    'b' => 'banana'
];

// POST جديد مع رابط إلى cURL ننشئ مورد
$ch = curl_init('http://www.example.com');

// ليقرأ الخرج CURLOPT_RETURNTRANSFER نضبط المعامل
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// POST نمرر بيانات
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);

// $response ننفذ الطلب ونحصل على الخرج في المتغير
$response = curl_exec($ch);

// نغلق الاتصال
curl_close($ch);

استخدام ملفات تعريف الارتباط

يمكن لمكتبة cURL أن تحافظ على ملفات تعريف الارتباط المستقبَلة في الردود للاستخدام مع الطلبات اللاحقة، نحقق هذا بسطر شيفرة واحد من أجل ملف تعريف ارتباط جلسة بسيط في الذاكرة:

curl_setopt($ch, CURLOPT_COOKIEFILE, "");

في الحالات التي يكون مطلوب فيها الحفاظ على ملفات تعريف الارتباط بعدأن يُدمَّر مُعالِج cURL يمكنك وصف ملف لتخزينها:

curl_setopt($ch, CURLOPT_COOKIEJAR, "/tmp/cookies.txt");

وعندما تحتاج استخدامها ثانيةً تمررها كملف تعريف ارتباط:

curl_setopt($ch, CURLOPT_COOKIEFILE, "/tmp/cookies.txt");

ومع ذلك تذكر أنّك لا تحتاج هاتين الخطوتين إذا لم تكن تريد حمل ملفات تعريف الارتباط بين معالجات cURL المختلفة، إذ أنّ ما تحتاجه في معظم الحالات هو ضبط CURLOPT_COOKIEFILE إلى سلسلة فارغة.

يمكن أن تستخدم معالجة ملف تعريف الارتباط لاستعادة موارد من موقع إنترنت يتطلب تسجيل دخول مثلًا، يكون هذا الإجراء من خطوتين عادةً، الأولى إرسال البيانات بالطريقة POST إلى صفحة تسجيل الدخول:

<?php
// cURL إنشاء معالج
$ch = curl_init();

// (curl_init() ضبط الرابط (أو يمكن تمريره إلى
curl_setopt($ch, CURLOPT_URL, "https://www.example.com/login.php");

// POST لتكون HTTP ضبط طريقة
curl_setopt($ch, CURLOPT_POST, true);

// يمكّن ضبط هذا الخيار إلى سلسلة فارغة معالجة ملف تعريف الارتباط لكنه لا يحمّله من ملف
curl_setopt($ch, CURLOPT_COOKIEFILE, "");

// ضبط القيم التي نريد إرسالها
curl_setopt($ch, CURLOPT_POSTFIELDS, array(
    "username"=>"joe_bloggs",
    "password"=>"$up3r_$3cr3t",
));

// إعادة جسم الرد
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// إرسال الطلب
$result = curl_exec($ch);

الخطوة الثانية (بعد انتهاء فحص الخطأ القياسي) عادةً هي رد GET بسيط، الشيء المهم هو إعادة استخدام معالِج cURL الموجود للطلب الثاني، يضمن هذا أنّ ملفات إعادة الارتباط من الرد الأول ستُضمَّن تلقائيًا في الطلب الثاني.

لن نستدعي curl_init()‎ في الشيفرة التالية:

// تغيير الرابط
curl_setopt($ch, CURLOPT_URL, "https://www.example.com/show_me_the_foo.php");

// GET تغيير الطريقة إلى
curl_setopt($ch, CURLOPT_HTTPGET, true);

// إرسال الطلب
$result = curl_exec($ch);

// cURL النهاية مع
curl_close($ch);

// $result تستطيع هنا إضافة الشيفرة التي تريدها لمعالجة

الشيفرة السابقة هي مجرد مثال عن معالجة ملف تعريف ارتباط ?أما في التطبيقات العملية تكون الأمور أكثر تعقيدًا، يجب أن تنفّذ عادةً طلب GET أولي لصفحة تسجيل الدخول لتسحب مفتاح تسجيل الدخول الذي تحتاج تضمينه في طلب POST. قد تعطّل بعض المواقع عميل cURL المعتمد على سلسلة نصية لوكيل المستخدم مما يتطلب منك تغييرها.

استخدام multi_curl لإرسال عدة طلبات POST

قد نحتاج أحيانًا إجراء عدة طلبات POST لنقطة نهائية (endpoint) واحدة أو أكثر، يمكننا استخدام multi_curl للتعامل مع هذه الحالة.

ننشئ في البداية عدد الطلبات الذي نحتاجه بنفس طريقة المثال البسيط السابق ونضعها في مصفوفة، نستخدم curl_multi_init ونضيف معالِج لكل منها.

نستخدم في المثال التالي نقطتين نهائيتين:

// POST مصفوفة بيانات لإرسالها بالطريقة
$request_contents = array();

// مصفوفة روابط
$urls = array();

// cURL مصفوفة معالجات
$chs = array();

//الأول $request_contents محتوى المصفوفة
$request_contents[] = [
    'a' => 'apple',
    'b' => 'banana'
];

// الثاني $request_contents محتوى المصفوفة
$request_contents[] = [
    'a' => 'fish',
    'b' => 'shrimp'
];

// ضبط الروابط
$urls[] = 'http://www.example.com';
$urls[] = 'http://www.example2.com';

// multi_curl وإضافتهم إلى cURL إنشاء مصفوفة من معالجات
$mh = curl_multi_init();
foreach ($urls as $key => $url) {
    $chs[$key] = curl_init($url);
    curl_setopt($chs[$key], CURLOPT_RETURNTRANSFER, true);
    curl_setopt($chs[$key], CURLOPT_POST, true);
    curl_setopt($chs[$key], CURLOPT_POSTFIELDS, $request_contents[$key]);
    curl_multi_add_handle($mh, $chs[$key]);
}

بعدها نستخدم curl_multi_exec لإرسال الطلبات:

// تنفيذ الطلبات
$running = null;
do {
    curl_multi_exec($mh, $running);
}

// الحصول على الردود
foreach(array_keys($chs) as $key){
    $error = curl_error($chs[$key]);
    $last_effective_URL = curl_getinfo($chs[$key], CURLINFO_EFFECTIVE_URL);
    $time = curl_getinfo($chs[$key], CURLINFO_TOTAL_TIME);
    $response = curl_multi_getcontent($chs[$key]); // get results
    if (!empty($error)) {
        echo "The request $key return a error: $error" . "\n";
    }
    else {
        echo "The request to '$last_effective_URL' returned '$response' in $time seconds." . "\n";
    }
    curl_multi_remove_handle($mh, $chs[$key]);
}

// إغلاق المعالِج الحالي
curl_multi_close($mh);

يمكن أن يعيد هذا المثال التالي:

• يعيد الطلب إلى 'http://www.example.com' القيمة 'fruits' في ثانيتين.
• يعيد الطلب إلى 'http://www.example2.com' القيمة 'seafood' في 5 ثواني.

إرسال بيانات متعددة الأبعاد وعدة ملفات في طلب واحد باستخدام cURL

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

لدينا مدخلات عادية وحقل متعدد الخيارات وحقل إرفاق ملف حيث يمكننا تحميل عدة ملفات.

بفرض نجاح طلب AJAX POST نحصل على البيانات التالية في الموقع:

// print_r($_POST)

Array
(
    [first_name] => John
    [last_name] => Doe
    [activities] => Array
    (
        [0] => soccer
        [1] => hiking
    )
)

وتبدو الملفات كما يلي:

// print_r($_FILES)
Array
(
    [upload] => Array
    (
        [name] => Array
        (
            [0] => my_photo.jpg
            [1] => my_life.pdf
        )
        [type] => Array
        (
            [0] => image/jpg
            [1] => application/pdf
        )
        [tmp_name] => Array
        (
            [0] => /tmp/phpW5spji
            [1] => /tmp/phpWgnUeY
        )
        [error] => Array
        (
            [0] => 0
            [1] => 0
        )
        [size] => Array
        (‎
            [0] => 647548
            [1] => 643223
        )
    )
)

نريد الآن إرسال هذه البيانات والملفات إلى خادم خارجي باستخدام cURL مع الصنف CurlFile، وبما أنّ cURL تقبل مصفوفة بسيطة فقط وليس مصفوفة متعددة الأبعاد فيجب أن نستخدم مصفوفة ‎$_POST أولًا.

نستخدم هذه الدالة مثلًا للقيام بذلك مما يعطيك الخرج:

// print_r($new_post_array)

Array
(
    [first_name] => John
    [last_name] => Doe
    [activities[0]] => soccer
    [activities[1]] => hiking
)

الخطوة التالية هي إنشاء كائنات CurlFile للملفات المحمّلة باستخدام الحلقة التالية:

$files = array();

foreach ($_FILES["upload"]["error"] as $key => $error) {
    if ($error == UPLOAD_ERR_OK) {
        $files["upload[$key]"] = curl_file_create(
        $_FILES['upload']['tmp_name'][$key],
        $_FILES['upload']['type'][$key],
        $_FILES['upload']['name'][$key]
        );
    }
}

الدالة curl_file_create مساعدة للصنف CurlFile وتنشئ كائنات CurlFile، نحفظ هذه الكائنات في المصفوفة ‎$files مع مفاتيح بالأسماء "upload[0]‎" و"upload[1]‎" لملفينا.

نحتاج الآن لجمع المصفوفة المعدَّلة مع مصفوفة الملفات ونحفظها في ‎$data:

$data = $new_post_array + $files;

الخطوة الأخيرة هي إرسال طلب cURL:

$ch = curl_init();

curl_setopt_array($ch, array(
    CURLOPT_POST => 1,
    CURLOPT_URL => "https://api.externalserver.com/upload.php",
    CURLOPT_RETURNTRANSFER => 1,
    CURLINFO_HEADER_OUT => 1,
    CURLOPT_POSTFIELDS => $data
));

$result = curl_exec($ch);

curl_close ($ch);

بما أنّ ‎$data هي مصفوفة بسيطة (مسطّحة) فإنّ cURL ترسل هذا الطلب بالطريقة POST مع نوع المحتوى multipart/form-data ويمكنك الحصول على المعلومات والملفات المرسلة مع ‎$_POST و‎$_FILES‎ في الملف upload.php على الخادم الخارجي كما تفعل عادةً.

إنشاء وإرسال طلب مع طريقة مخصصة

تدعم cURL افتراضيًا طلبات GET وPOST ومن الممكن أيضًا إرسال طلبات بطرق مخصصة مثل DELETE أوPUT أوPATCH (أو حتى طرق غير معيارية) باستخدام المعامل CURLOPT_CUSTOMREQUEST.

// DELETE إنشاء طلب
$method = 'DELETE';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
$content = curl_exec($ch);
curl_close($ch);

ترويسات HTTP المخصصة Get وSet في PHP

إرسال ترويسة الطلب

$uri = 'http://localhost/http.php';

$ch = curl_init($uri);
curl_setopt_array($ch, array(
    CURLOPT_HTTPHEADER => array('X-User: admin', 'X-Authorization: 123456'),
    CURLOPT_RETURNTRANSFER =>true,
    CURLOPT_VERBOSE => 1
));
$out = curl_exec($ch);
curl_close($ch);
// طباعة خرج الرد
echo $out;

قراءة الترويسة المخصصة

print_r(apache_request_headers());

الخرج:

Array
(
    [Host] => localhost
    [Accept] => */*
    [X-User] => admin
    [X-Authorization] => 123456
    [Content-Length] => 9
    [Content-Type] => application/x-www-form-urlencoded
)

يمكننا أيضًا إرسال الترويسة باستخدام الصياغة التالية:

curl --header "X-MyHeader: 123" www.google.com

ترجمة -وبتصرف- للفصول [SOAP Client - SOAP Server - Using cURL in PHP - Sessions - Cookies] من كتاب PHP Notes for Professionals book

اقرأ أيضًا

• المقال التالي: فضاء الأسماء (namespaces) في PHP
• المقال السابق: السلسلة Serialization في PHP

الدالة serialize()‎ في PHP لها الشكل العام التالي:

serialize ( mixed $value )

يعبّر المعامل value عن القيمة التي نريد سَلسَلتها، تعالج الدالة serialize()‎ كل الأنواع، عدا الأنواع الموردية (resource-type)، كما يمكنك سَلسَلة المصفوفات التي تحتوي مراجع إلى نفسها، المراجع الدائرية داخل المصفوفة/الكائن التي تُسلسلها ستُخزَّن أيضًا وأي مرجع آخر سيُفقد. تحاول PHP عند سَلسَلة الكائن استدعاء الدالة ‎__sleep()‎ قبل القيام بالسَلسَلة وذلك للسماح للكائن بالقيام بالتنظيف حتى اللحظة الأخيرة قبل بدء السَلسَلة. وكذلك عند استعادة كائن باستخدام unserialize()‎ تُستدعى الدالة ‎__wakeup()‎. يكون لأعضاء الكائن الخاصة اسم الصنف ملحقًا باسم العضو، وللأعضاء المحمية العلامة '*' ملحقًا باسم العضو. تحتوي هذه القيم المُلحقة على وحدات بايت فارغة على كلا الجانبين.

سَلسَلة أنواع مختلفة

تولّد تمثيلًا قابلًا للتخزين لقيمة ما، ويعدّ هذا مفيدًا لتخزين أو تمرير قيم PHP دون خسارة نوعها وبنيتها.

نستخدم unserialize()‎ لنعيد السلسلة النصية المُسَلسَلة إلى قيمة PHP من جديد.

سَلسَلة سلسلة نصية

$string = "Hello world";
echo serialize($string);

// s:11:"Hello world";

سَلسَلة قيمة عشرية

$double = 1.5;
echo serialize($double);

// d:1.5;

سَلسَلة عدد صحيح

$integer = 65;
echo serialize($integer);

// i:65;

سَلسَلة قيمة منطقية

$boolean = true;
echo serialize($boolean);

// b:1;

$boolean = false;
echo serialize($boolean);

// b:0;

سَلسَلة القيمة null

$null = null;
echo serialize($null);

// N;

سَلسَلة مصفوفة

$array = array(
    25,
    'String',
    'Array'=> ['Multi Dimension','Array'],
    'boolean'=> true,
    // ‫‎⁢$obj من المثال في الأعلى
    'Object'=>$obj,
    null,
    3.445
);

/*
سيرمي هذا خطأً فادحًا 
$array['function'] = function() { return "function"; };
*/

echo serialize($array);

// a:7:{i:0;i:25;i:1;s:6:"String";s:5:"Array";a:2:{i:0;s:15:"Multi
Dimension";i:1;s:5:"Array";}s:7:"boolean";b:1;s:6:"Object";O:3:"abc":1:{s:1:"i";i:1;}i:2;N;i:3;d:3.4449999999999998;}

سَلسَلة كائن

تحاول PHP عند سَلسَلة كائن استدعاء الدالة ‎__sleep()‎ قبل القيام بالسَلسَلة وذلك للسماح للكائن بالقيام بالتنظيف حتى اللحظة الأخيرة قبل بدء السَلسَلة. وكذلك عند استعادة كائن باستخدام unserialize()‎ تُستدعى الدالة ‎__wakeup()‎.

class abc {
    var $i = 1;

    function foo() {
        return 'hello world';
    }
}

$object = new abc();
echo serialize($object);

// O:3:"abc":1:{s:1:"i";i:1;}

لاحظ أنّه لا يمكن سَلسَلة المغلِّفات (Closures)

$function = function () { echo 'Hello World!'; };
$function(); // prints "hello!"
$serializedResult = serialize($function); 

// Fatal error: Uncaught exception 'Exception' with message 'Serialization of 'Closure' is not allowed'

مشاكل الحماية مع فك السَلسَلة

يمكن أن يكون استخدام الدالة unserialize لفك سَلسَلة دخل المستخدم خطيرًا.

تحذير: لا تمرّر دخل المستخدم غير الموثوق به للدالة unserialize، يمكن أن يؤدي فك السَلسَلة إلى تحميل التعليمات البرمجية وتنفيذها بسبب استنساخ الكائن والتحميل التلقائي وقد يتمكن المستخدم الضار من استغلال ذلك. استخدم تنسيق تبادل بيانات قياسي مثل JSON (باستخدام json_decode()‎ وjson_encode()‎) إذا كنت تحتاج إلى تمرير بيانات مسَلسَلة إلى المستخدم.

الهجمات الممكنة: حقن كائن PHP

ثغرة على مستوى التطبيق يمكن أن تسمح للمهاجم بأداء أنواع مختلفة من الهجمات الخبيثة مثل حقن الشيفرة وحقن SQL واجتياز المسار (Path Traversal) وتطبيق حجب الخدمة (Denial of Service) بالاعتماد على السياق. تحدث الثغرة عندما لا يُعقَّم دخل المستخدم قبل تمريره إلى دالة unserialize. بما أنّ PHP تسمح بسَلسَلة الكائن، يمكن للمهاجمين تمرير سلاسل نصية مسَلسَلة مخصصة إلى استدعاء الدالة unserialize المعرضة للخطر مما يؤدي إلى حقن كائن (أو كائنات) PHP عشوائي في نطاق التطبيق.

يجب تحقيق شرطين لاستغلال ثغرة حقن كائن PHP بنجاح:

• أن يكون للتطبيق صنف ينفّذ تابع PHP سحري (مثل ‎__wakeup أو ‎__destruct) يمكن أن يُستخدم لتنفيذ هجمات ضارة أو بدء سلسلة POP (‏Property Oriented Programming).
• أن يُصرَّح عن جميع الأصناف المستخدمة خلال الهجوم عند استدعاء الدالة unserialize المعرضة للخطر وإلا يجب دعم التحميل التلقائي للصنف لمثل هذه الكائنات.

مثال1 - هجوم اجتياز المسار (Path Traversal Attack):

يظهر المثال التالي صنف PHP مع تابع ‎__destruct القابل للاستغلال:

class Example1
{
    public $cache_file;

    function __construct()
    {
        // ‫بعض الشيفرة هنا...
    }

    function __destruct()
    {
        $file = "/var/www/cache/tmp/{$this->cache_file}";
        if (file_exists($file)) @unlink($file);
    }
}

// ‫بعض الشيفرة هنا…

$user_data = unserialize($_GET['data']);

// ‫بعض الشيفرة هنا...

قد يكون المهاجم في هذا المثال قادرًا على حذف ملف عشوائي عبر هجوم اجتياز المسار مثل طلب المسار التالي:

http://testsite.com/vuln.php?data=O:8:"Example1":1:{s:10:"cache_file";s:15:"../../index.php";}

مثال2 - هجوم حقن الشيفرة (Code Injection attack):

يظهر المثال التالي صنف PHP مع تابع ‎__wakeup القابل للاستغلال:

class Example2
{
    private $hook;

    function __construct()
    {
        // ‫بعض الشيفرة هنا...
    }

    function __wakeup()
    {
        if (isset($this->hook)) eval($this->hook);
    }
}

// ‫بعض الشيفرة هنا…

$user_data = unserialize($_COOKIE['data']);

// ‫بعض الشيفرة هنا...

يمكن أن يكون المهاجم في هذا المثال قادرًا على القيام بهجوم حقن الشيفرة بإرسال طلب HTTP مثل الطلب التالي:

GET /vuln.php HTTP/1.0
Host: testsite.com
Cookie:
data=O%3A8%3A%22Example2%22%3A1%3A%7Bs%3A14%3A%22%00Example2%00hook%22%3Bs%3A10%3A%22phpinfo%28%29%
3B%22%3B%7D
Connection: close

حيث أُنشئ معامل ملف تعريف الارتباط "data" من قِبل السكربت التالي:

class Example2
{
    private $hook = "phpinfo();";
}

print urlencode(serialize(new Example2));

سَلسَلة/ فك سَلسَلة كائن

تعيد الدالة serialize()‎ سلسلة نصية تتضمن تمثيل مجرى بايتات لأي قيمة يمكن تخزينها في PHP. يمكنك استخدام الدالة unserialize()‎ لإعادة تكوين قيمة المتغير الأصلية.

نكتب الشيفرة التالية لسَلسَلة (serialize) كائن:

serialize($object);

نكتب الشيفرة التالية لفك سَلسَلة (Unserialize) كائن:

unserialize($object)

مثال:

$array = array();
$array["a"] = "Foo";
$array["b"] = "Bar";
$array["c"] = "Baz";
$array["d"] = "Wom";

$serializedArray = serialize($array);
echo $serializedArray;

/*
a:4:{s:1:"a";s:3:"Foo";s:1:"b";s:3:"Bar";s:1:"c";s:3:"Baz";s:1:"d";s:3:"Wom";}
*/

الواجهة القابلة للسَلسَلة

لم تعد الأصناف التي تنفّذ هذه الواجهة تدعم التوابع السحرية ‎__sleep()‎ و‎__sleep()‎. يُستدعى تابع السَلسَلة عندما يحتاج كائن إلى السَلسَلة، وهذا لا يشغّل التابع ‎__destruct()‎ وليس له آثار جانبية أخرى ما لم يُبرمج داخل تابع السَلسَلة، عند فك سَلسَلة البيانات يُعرف الصف ويُستدعى تابع unserialize()‎ المناسب كبانٍ بدلًا من استدعاء ‎__construct()‎. إذا كنت تحتاج إلى تنفيذ الباني القياسي فيمكنك القيام بذلك في التابع.

الاستخدام الأساسي

class obj implements Serializable {
    private $data;

    public function __construct() {
        $this->data = "My private data";
    }

    public function serialize() {
        return serialize($this->data);
    }

    public function unserialize($data) {
        $this->data = unserialize($data);
    }

    public function getData() {
        return $this->data;
    }
}

$obj = new obj;
$ser = serialize($obj);

var_dump($ser); 
// string(38) "C:3:"obj":23:{s:15:"My private data";}"

$newobj = unserialize($ser);
var_dump($newobj->getData()); 
// string(15) "My private data"

ترجمة -وبتصرف- للفصول [Object Serialization - Serialization] من كتاب PHP Notes for Professionals book

اقرأ أيضًا

• المقال التالي: الجلسات وملفات تعريف الارتباط ومكتبة cURL في PHP
• المقال السابق: الأصناف (Classes) والكائنات (Objects) في PHP

تستخدم الأصناف والكائنات لجعل الشيفرة أكثر فعالية وأقل تكرارًا عن طريق تجميع الوظائف المتشابهة.

يستخدم الصنف لتعريف الوظائف وبنى المعطيات المستخدمة لإنشاء كائنات، ثم تُنشأ الكائنات باستخدام البنية المعرّفة مسبقًا.

ثوابت الصنف

توفر ثوابت الصنف (Class constants) آلية لحمل القيم الثابتة في البرنامج، أي أنّها توفر طريقة لإعطاء اسم (وتربطه بالتحقق وقت التصريف) لقيمة ما مثل 3.14 أو "Apple"، يمكن أن تُعرَّف ثوابت الصنف باستخدام الكلمة المفتاحية const فقط ولا يمكن استخدام الدالة define لهذا الغرض.

فمثلًا قد يكون من المناسب أن يكون لديك تمثيل مختصر للقيمة π في برنامجك، إليك الصنف التالي مع قيم const يوفر طريقة بسيطة لحمل مثل هذه القيم.

class MathValues {
    const PI = M_PI;
    const PHI = 1.61803;
}

$area = MathValues::PI * $radius * $radius;

يمكن الوصول لثوابت الصنف مثل المتغيرات الساكنة باستخدام عامل العمود المزدوج :: (الذي يسمى عامل دقة النطاق) على الصنف، لكن على عكس المتغيرات الساكنة فإنّ متغيرات الصنف لها قيم ثابتة وقت التصريف ولا يمكن إعادة إسناد قيم لها، (أي أنّ إضافة MathValues::PI = 7 للشيفرة السابقة ستنتج خطأً فادحًا).

تفيد ثوابت الصنف أيضًا في تعريف الأشياء الداخلية للصنف التي قد تحتاج للتغيير لاحقًا (لكن لا تتغير بشكلٍ مستمر بما يكفي لتخزينها في قاعدة بيانات مثلًا)، يمكن الرجوع إليها داخليًا باستخدام عامل تحليل النطاق (Scope Resolution Operator) ‏self الذي يعمل في التنفيذات الساكنة والمستنسخة.

class Labor {
    // الوقت اللازم لبناء عنصر مقدّرًا بالساعات
    const LABOR_UNITS = 0.26;

    // المبلغ الذي يتقاضاه العمّال في الساعة
    const LABOR_COST = 12.75;

    public function getLaborCost($number_units) {
        return (self::LABOR_UNITS * self::LABOR_COST) * $number_units;
    }
}

يمكن أن تحتوي ثوابت الصنف في إصدارات PHP السابقة للإصدار 5.6 على قيم عددية فقط، بينما يمكننا استخدام التعابير مع الثوابت بدءًا من الإصدار 5.6 أي أنّه يمكننا استخدام التعليمات الرياضية والسلاسل النصية مع الربط.

class Labor {

    /** ندفع للعمال في الساعة: الأجر في الساعة * عدد الساعات لإنجاز العمل */
    const LABOR_COSTS = 12.75 * 0.26;

    public function getLaborCost($number_units) {
        return self::LABOR_COSTS * $number_units;
    }
}

بدءًا من الإصدار PHP 7.0، يمكن للثوابت المعرّفة باستخدام define أن تحتوي مصفوفات.

define("BAZ", array('baz'));

تعدّ ثوابت الصنف مفيدة ليس فقط لتخزين المفاهيم الرياضية، فمثلًا إذا كنت تحضّر شطيرة قد يكون من المناسب أن يكون لديك صنف Pie واحد قادر على أخذ أنواع مختلفة من الفاكهة.

class Pie {
    protected $fruit;

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

بعدها يمكننا استخدام الصنف Pie كالتالي:

$pie = new Pie("strawberry");

المشكلة التي تظهر هنا هي أنّه عند استنساخ الصنف Pie لا يوجد إرشادات للقيم المقبولة، فمثلًا عند صنع شطيرة "boysenberry" قد تُكتب مع خطأ إملائي "boisenberry"، بالإضافة إلى ذلك قد لا تريد دعم صنع شطيرة خوخ. لذا سيكون من المفيد أن يكون لدينا قائمة معرّفة مسبقًا تحوي أنواع الفاكهة المقبولة موجودة في مكان ما بحيث يمكن ملاحظتها وليكن صنف نسميه Fruit:

class Fruit {
    const APPLE = "apple";
    const STRAWBERRY = "strawberry";
    const BOYSENBERRY = "boysenberry";
}

$pie = new Pie(Fruit::STRAWBERRY);

يوفر وضع القيم المقبولة في قائمة ثوابت الصنف دليلًا للقيم التي يقبلها التابع، كما يضمن أن لا يقبل المصرّف الأخطاء الإملائية التي قد تحدث، فبينما يقبل المصرّف new Pie('aple')‎ وnew Pie('apple')‎ ستنتج الشيفرة new Pie(Fruit::APLE)‎ خطأ تصريف (compiler error).

كما إنّ استخدام ثوابت الصنف يعني أنّ القيمة الفعلية للثابت يمكن تعديلها في مكان واحد وأيّ شيفرة تستخدم هذا الثابت ستتأثر بهذا التغيير تلقائيًا.

إنّ الطريقة الشائعة للوصول إلى ثابت الصنف هي MyClass::CONSTANT_NAME، لكن يمكن الوصول إليها بالطريقة التالية:

echo MyClass::CONSTANT;
$classname = "MyClass";

// PHP 5.3.0 بدءًا من
echo $classname::CONSTANT; 

تسمى عادةً ثوابت الصنف بأحرف كبيرة مع استخدام الشرطة السفلية _ للفصل بين الكلمات، بالرغم من أنّه يمكن استخدام أي تسمية صحيحة لتسمية ثابت الصنف.

بدءًا من الإصدار PHP 7.1 يمكن تعريف ثوابت الصنف بمرئيات مختلفة عن النطاق العام الافتراضي، أي يمكن تعريف ثوابت صنف خاصة (private) ومرئية (protected) لمنعها من التسرّب غير الضروري إلى النطاق العام، مثال:

class Something {
    const PUBLIC_CONST_A = 1;
    public const PUBLIC_CONST_B = 2;
    protected const PROTECTED_CONST = 3;
    private const PRIVATE_CONST = 4;
}

define مقابل ثوابت الصنف

بالرغم من أنّ هذه البنية صحيحة:

function bar() { return 2; };
define('BAR', bar());

لكن سيظهر خطأ إذا حاولت القيام بذلك مع ثوابت الصنف:

function bar() { return 2; };

class Foo {
    const BAR = bar(); 
    // Constant expression contains invalid operations
}

لكن يمكنك كتابة التالي:

function bar() { return 2; };

define('BAR', bar());

class Foo {
    const BAR = BAR;
}

استخدام ‎::class‎ للحصول على اسم الصنف

قدمت PHP 5.5 الصياغة ‎::class للحصول على اسم الصنف الكامل?? مع مراعاة نطاق فضاء الاسم وتعليمات use.

namespace foo;
use bar\Bar;
echo json_encode(Bar::class); // "bar\\Bar"
echo json_encode(Foo::class); // "foo\\Foo"
echo json_encode(\Foo::class); // "Foo"

تعمل الشيفرة السابقة بشكلٍ صحيح حتى لو لم تُعرَّف الأصناف، وتعدّ هذه الصياغة مفيدة للدوال التي تتطلّب اسم صنف فيمكن استخدامها مع الدالة class_exists مثلًا للتحقق من أنّ صنف ما معرّف. لن تظهر أخطاء في الشيفرة التالية بغض النظر عن القيمة المعادة:

class_exists(ThisClass\Will\NeverBe\Loaded::class, false);

الأصناف المجردة

الصنف المجرد (abstract class) هو الصنف الذي لا يمكن استنساخه، ويمكن له أن يعرّف توابعًا مجردة أي توابع لها تعريف فقط من دون جسم:

abstract class MyAbstractClass {
    abstract public function doSomething($a, $b);
}

يمكن أن توسَّع الأصناف المجردة بصنف ابن يحقق تنفيذ هذه التوابع المجردة، إذ أنّ الهدف الأساسي للصنف المجرد هو تعريف قالب يسمح للأصناف الأبناء بالوراثة منه وفق بنية معينة، إليك المثال التالي الذي ننفذ فيه واجهة Worker بعد تعريفها:

interface Worker {
    public function run();
}

لتسهيل تطوير المزيد من تطبيقات الواجهة Worker ننشئ الصنف المجرد worker المزود بالتابع ‎run()‎ من الواجهة ويحدد بعض التوابع المجردة لتُملأ في الأصناف الأبناء:

abstract class AbstractWorker implements Worker {
    protected $pdo;
    protected $logger;

    public function __construct(PDO $pdo, Logger $logger) {
        $this->pdo = $pdo;
        $this->logger = $logger;
    }

    public function run() {
        try {
            $this->setMemoryLimit($this->getMemoryLimit());
            $this->logger->log("Preparing main");
            $this->prepareMain();
            $this->logger->log("Executing main");
            $this->main();
        } catch (Throwable $e) {
            // تلتقط وتعيد رمي كل الأخطاء حتى يتمكن العامل من تسجيلها
            $this->logger->log("Worker failed with exception: {$e->getMessage()}");
            throw $e;
        }
    }

    private function setMemoryLimit($memoryLimit) {
        ini_set('memory_limit', $memoryLimit);
        $this->logger->log("Set memory limit to $memoryLimit");
    }

    abstract protected function getMemoryLimit();

    abstract protected function prepareMain();

    abstract protected function main();
}

وضعنا في البداية تابعًا مجردًا getMemoryLimit()‎، يحتاج أي صنف يرث الصنف AbstractWorker أن ينفذ هذا التابع ويعيد قيد الذاكرة. ثم يضبط AbstractWorker قيد الذاكرة ويسجّله.

يستدعي الصنف AbstractWorker بعد ذلك التوابع prepareMain()‎ وmain()‎، ثم تُجمّع كل استدعاءات التوابع هذه في كتلة try-catch فإذا رمى أي من التوابع المجردة المعرفة من الصنف الابن استثناءً سنلتقط هذا الاستثناء ونسجّله ونعيد رميه، وهذا يمنع كل الأصناف الأبناء من الاضطرار إلى تنفيذ هذا الإجراء.

لنعرّف صنف ابن يوسّع الصنف AbstractWorker:

class TranscactionProcessorWorker extends AbstractWorker {
    private $transactions;

    protected function getMemoryLimit() {
        return "512M";
    }

    protected function prepareMain() {
        $stmt = $this->pdo->query("SELECT * FROM transactions WHERE processed = 0 LIMIT 500");
        $stmt->execute();
        $this->transactions = $stmt->fetchAll();
    }

    protected function main() {
        foreach ($this->transactions as $transaction) {
        // (1)
        $stmt = $this->pdo->query("UPDATE transactions SET processed = 1 WHERE id ={$transaction['id']} LIMIT 1");
        $stmt->execute();
        }
    }
}

قد يُرمى استثناء PDO أو MYSQL في الموضع (1) لكن يُعالج من قبل AbstractWorker.

كما تلاحظ فإنّ TransactionProcessorWorker كان سهل التنفيذ حيث كان علينا فقط تحديد قيد الذاكرة والقلق بشأن الإجراءات الفعلية التي نحتاج القيام بها. لا نحتاج إلى معالجة الأخطاء في TransactionProcessorWorker لأنّها تُعالج في الصنف AbstractWorker.

ملاحظة مهمة: عند الوراثة من صنف مجرد فإنّ كل التوابع المجردة الموجودة في الصنف الأب يجب أن يعرّفها الابن (أو يعيد التصريح عنها بأنّها توابع مجردة)، كما يجب تعريف هذه التوابع بنفس المرئية (أو بمرئية أقل تحديدًا)، فمثلًا إذا عُرِّف التابع المجرد أنه محمي فإنّ تنفيذه يجب أن يعرّف أنّه محمي أو عام (ولا يمكن تعريفه أنّه خاص).

سيُرمى خطأً فادحًا إذا لم تعرّف توابع الأصناف الآباء المجردة في الصنف الابن كالخطأ التالي:

Fatal error: Class X contains 1 abstract method and must therefore be declared abstract or implement the remaining methods (X::x) in

الربط الساكن المتأخر

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

class Horse {
    public static function whatToSay() {
        echo 'Neigh!';
    }

    public static function speak() {
        self::whatToSay();
    }
}

class MrEd extends Horse {
    public static function whatToSay() {
        echo 'Hello Wilbur!';
    }
}

قد تتوقع أنّ الصنف MrEd سيعيد تعريف الدالة whatToSay()‎ في الصنف الأب لكن عند التنفيذ ستكون النتيجة غير متوقعة:

Horse::speak(); // Neigh!
MrEd::speak(); // Neigh!

المشكلة هي أنّ self::whatToSay();‎ يمكن أن يشير إلى الصنف Horse فقط أي أنّه لن يتأثر بالصنف MrEd، لن نواجه هذه المشكلة إذا بدلنا إلى عامل تحليل النطاق static::‎، وبهذه الطريقة سيتأثر الصنف بالنسخة التي تستدعيه فنحصل على الوراثة التي نتوقعها:

class Horse {
    public static function whatToSay() {
        echo 'Neigh!';
    }

    public static function speak() {
        // ربط ساكن متأخر
        static::whatToSay();
    }
}

Horse::speak(); // Neigh!
MrEd::speak(); // Hello Wilbur!

فضاء التسمية والتحميل التلقائي

يعمل التحميل التلقائي (Autoloading) تقنيًا بتنفيذ رد نداء عندما يُطلب صنف PHP ولا يُعثر عليه، عادةً ما تحاول ردود النداء تحميل هذه الأصناف.

يمكن أن يُفهم التحميل التلقائي بشكلٍ عام أنّه محاولة لتحميل ملفات PHP (خاصةً ملفات الصنف حيث يكون الملف المصدري مخصصًا لصنف معين) من المسارات المناسبة حسب الاسم الكامل المؤهل (FQN) عند الحاجة إلى الصنف.

بفرض لدينا الأصناف التالية: ملف الصنف application\controllers\Base:

<?php
namespace application\controllers { class Base {...} }

ملف الصنف application\controllers\Control:

<?php
namespace application\controllers { class Control {...} }

ملف الصنف application\models\Page:

<?php
namespace application\models { class Page {...} }

تتوضع هذه الأصناف في المجلد المصدر وفقًا لأسمائها الكاملة المؤهلة كالتالي:

• المجلد المصدر
  • applications
    • controllers
      • Base.php
      • Control.php
    • models
      • Page.php

تجعل هذه الطريقة من الممكن الحصول على مسار ملف الصنف برمجيًا وفق الاسم الكامل المؤهل (FQN) باستخدام هذه الدالة:

function getClassPath(string $sourceFolder, string $className, string $extension = ".php") {
    return $sourceFolder . "/" . str_replace("\\", "/", $className) . $extension;
}

لاحظ أنّ / هو الفاصل بين المجلدات في ويندوز.

تسمح لنا الدالة spl_autoload_register بتحميل الصنف الذي نحتاجه باستخدام دالة معرفة من قبل المستخدم:

const SOURCE_FOLDER = __DIR__ . "/src";

spl_autoload_register(function (string $className) {
    $file = getClassPath(SOURCE_FOLDER, $className);
    if (is_readable($file)) require_once $file;
});

يمكن لهذه الدالة أن توسَّع لاستخدام توابع قيم تراجعية (fallback) للتحميل:

const SOURCE_FOLDERS = [__DIR__ . "/src", "/root/src"]);
spl_autoload_register(function (string $className) {
    foreach(SOURCE_FOLDERS as $folder) {
        $extensions = [
            // ؟src/Foo/Bar.php5_int64 هل يوجد لدينا
            ".php" . PHP_MAJOR_VERSION . "_int" . (PHP_INT_SIZE * 8),

            // ؟src/Foo/Bar.php7 هل يوجد لدينا
            ".php" . PHP_MAJOR_VERSION,

            // ؟src/Foo/Bar.php_int64 هل يوجد لدينا
            ".php" . "_int" . (PHP_INT_SIZE * 8),

            // ؟src/Foo/Bar.phps هل يوجد لدينا
            ".phps"

            // ؟src/Foo/Bar.php هل يوجد لدينا
            ".php"
        ];

        foreach($extensions as $ext) {
            $path = getClassPath($folder, $className, $extension);
            if(is_readable($path)) return $path;
        }
    }
});

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

مرئية التوابع والخاصيّات

لدينا ثلاث أنواع للمرئية يمكن استخدامها للتوابع (دوال الصنف/الكائن) والخاصيّات (متغيرات الصنف/الكائن) داخل الصنف مما يوفر تحكم بالوصول لهذه التوابع والخاصيّات.

public: المرئية العامة

يعني التصريح عن تابع أو خاصيّة بأنّهما public أنّه يمكن الوصول إليهما من الصنف الذي صرّح عنهما والأصناف التي ترثه وأيّ كائنات أو أصناف خارجية أو شيفرة خارج هرمية الصنف، مثال:

class MyClass {
    // خاصيّة
    public $myProperty = 'test';

    // تابع
    public function myMethod() {
        return $this->myProperty;
    }
}

$obj = new MyClass();
echo $obj->myMethod();
// test

echo $obj->myProperty;
// test

Protected: المرئية المحمية

يعني التصريح عن تابع أو خاصيّة بأنّهما protected أنّه يمكن الوصول إليهما من الصنف الذي صرّح عنهما والأصناف التي ترثه، ولا يمكن الوصول إليهما من الكائنات أو الأصناف الخارجية أو الشيفرة خارج هرمية الصنف. إذا استخدمتهما شيفرة لا تملك إمكانية الوصول إليهما سيُرمى خطأ. مثال:

class MyClass {
    protected $myProperty = 'test';
    protected function myMethod() {
        return $this->myProperty;
    }
}

class MySubClass extends MyClass {
    public function run() {
        echo $this->myMethod();
    }
}

$obj = new MySubClass();
// MyClass::myMethod(); يستدعي السطر التالي
$obj->run(); 
// test

$obj->myMethod(); // خطأ
// Fatal error: Call to protected method MyClass::myMethod() from context ''

يوضح المثال السابق أنّه يمكن الوصول إلى العناصر المحمية من ضمن نطاقها، أي "الذي يوجد في المنزل يمكن الوصول إليه من داخل المنزل فقط".

Private: المرئية الخاصة

يعني التصريح عن تابع أو خاصيّة بأنّهما private أنّه يمكن الوصول إليهما من الصنف الذي صرّح عنهما فقط (ولا يمكن الوصول إليهما من الأصناف الفرعية).

لاحظ أنّ الكائنات من نفس النوع ستصل إلى العناصر الخاصة والمحمية لبعضها لبعض حتى لو لم تكن نفس النسخ.

class MyClass {
    private $myProperty = 'test';

    private function myPrivateMethod() {
        return $this->myProperty;
    }

    public function myPublicMethod() {
        return $this->myPrivateMethod();
    }

    public function modifyPrivatePropertyOf(MyClass $anotherInstance) {
        $anotherInstance->myProperty = "new value";
    }
}

class MySubClass extends MyClass {
    public function run() {
        echo $this->myPublicMethod();
    }

    public function runWithPrivate() {
        echo $this->myPrivateMethod();
    }
}

$obj = new MySubClass();
$newObj = new MySubClass();

$obj->run(); // (1)
// test

$obj->modifyPrivatePropertyOf($newObj);

$newObj->run();
// new value

echo $obj->myPrivateMethod(); // خطأ
// Fatal error: Call to private method MyClass::myPrivateMethod() from context ''

echo $obj->runWithPrivate(); // خطأ
// Fatal error: Call to private method MyClass::myPrivateMethod() from context 'MySubClass'

في الموضع (1) سيُستدعى MyClass::myPublicMethod()‎ ثم MyClass::myPrivateMethod()‎.

كما تلاحظ يمكن الوصول إلى التابع/الخاصيّة الخاصة فقط من الصنف الذي عرفهما.

الواجهات

الواجهات (Interfaces) هي تعريفات لواجهة برمجة التطبيقات (API) العامة ويجب أن تنفذها الأصناف، فهي تعمل "كعقود" تحدد ما الذي يجب أن تفعله الأصناف دون تحديد كيفية فعله.

يشبه تعريف الواجهة تعريف الصنف لكن نستبدل كلمة interface بكلمة class:

interface Foo {
}

يمكن أن تحتوي الواجهات توابع و/أو ثوابت ولكن ليس سمات، ثوابت الواجهة لها نفس قيود ثوابت الصنف، وتوابع الواجهة مجردة ضمنيًّا:

interface Foo {
    const BAR = 'BAR';

    public function doSomething($param1, $param2);
}

ملاحظة: يجب ألا تصرّح الواجهات عن بواني (constructors) أو هوادم (destructors) لأن تفاصيل التنفيذ هذه على مستوى الصنف.

التطبيق

أي صنف يحتاج لتنفيذ واجهة يجب أن يستخدم الكلمة المفتاحية implements، للقيام بذلك يحتاج الصنف أن يوفر تنفيذًا لكل تابع مصرَّح عنه في الواجهة مع الحفاظ على نفس البصمة، ويمكن للصنف الواحد أن ينفذ أكثر من واجهة واحدة في نفس الوقت.

interface Foo {
    public function doSomething($param1, $param2);
}

interface Bar {
    public function doAnotherThing($param1);
}

class Baz implements Foo, Bar {
    public function doSomething($param1, $param2) {
        // ...
    }

    public function doAnotherThing($param1) {
        // ...
    }
}

لا تحتاج الأصناف المجردة عندما تنفذ الواجهات إلى تنفيذ كل التوابع، وأي تابع لا يُنفَّذ في الصنف الأساسي يجب تنفيذه في الصنف الذي يوسّعه:

abstract class AbstractBaz implements Foo, Bar {
    // تنفيذ جزئي للواجهة المطلوبة...
    public function doSomething($param1, $param2) {
        // ...
    }
}

class Baz extends AbstractBaz {
    public function doAnotherThing($param1) {
        // ...
    }
}

لاحظ أنّ تطبيق الواجهة ميزة موروثة، عند توسيع صنف ينفذ واجهة فأنت لا تحتاج لإعادة التصريح عنها في الصنف الابن لأنّ هذا محقق ضمنيًّا.

ملاحظة: قبل الإصدار PHP 5.3.9 لم يكن بإمكان الصنف أن ينفذ واجهتين بهما تابع بنفس الاسم لأنّ هذا قد يسبب التباسًا، بينما تسمح الإصدارات الأحدث بذلك طالما أنّ التوابع المكررة ليس لها نفس البصمة.

الوراثة

يمكن إنشاء علاقة وراثة بين الواجهات مثل الأصناف باستخدام الكلمة المفتاحية extends، الفرق الأساسي هو أنّ الوراثة المتعددة مسموحة في الواجهات:

interface Foo {
}

interface Bar {
}

interface Baz extends Foo, Bar {
}

أمثلة

إليك مثال بسيط لواجهة مركبة، يمكن للمركبات أن تتحرك إلى الأمام والخلف.

interface VehicleInterface {
    public function forward();
    public function reverse();
    ...
}

class Bike implements VehicleInterface {
    public function forward() {
        $this->pedal();
    }

    public function reverse() {
        $this->backwardSteps();
    }

    protected function pedal() {
        ...
    }

    protected function backwardSteps() {
        ...
    }
    ...
}

class Car implements VehicleInterface {
    protected $gear = 'N';

    public function forward() {
        $this->setGear(1);
        $this->pushPedal();
    }

    public function reverse() {
        $this->setGear('R');
        $this->pushPedal();
    }

    protected function setGear($gear) {
        $this->gear = $gear;
    }

    protected function pushPedal() {
        ...
    }
    ...
}

ثم ننشئ صنفين ينفذان الواجهة: الدراجة والسيارة، يوجد اختلاف كبير داخليًا بين الدراجة والسيارة لكن كلّ منهما مركبة ويجب أن تنفذ نفس التوابع العامة التي توفرها واجهة المركبة VehicleInterface.

تسمح ميزة التلميح عن النوع (Typehinting) للتوابع والدوال أن تطلب واجهات. بفرض أنّه لدينا صنف مرآب للسيارات يحتوي كل أنواع المركبات.

class ParkingGarage {
    protected $vehicles = [];

    public function addVehicle(VehicleInterface $vehicle) {
        $this->vehicles[] = $vehicle;
    }
}

بما أنّ الدالة addVehicle تتطلب متغيرًا ‎$vehicle من النوع واجهة VehicleInterface - ليس تنفيذ حقيقي - يمكننا أن نجعل الدخل من النوع دراجة أو سيارة مما يمكّن الصنف ParkingGarage من معالجتها واستخدامها.

الكلمة المفتاحية Final

تمنع الكلمة المفتاحية Final الأصناف الأبناء من إعادة تعريف تابع مسبوقة بالكلمة final، إذا عُرِّف الصنف أنّه نهائي (final) فلا يمكن توسيعه.

التابع النهائي

class BaseClass {
    public function test() {
        echo "BaseClass::test() called\n";
    }

    final public function moreTesting() {
        echo "BaseClass::moreTesting() called\n";
    }
}

class ChildClass extends BaseClass {
    public function moreTesting() {
        echo "ChildClass::moreTesting() called\n";
    }
}

// Fatal error: Cannot override final method BaseClass::moreTesting()

الصنف النهائي

final class BaseClass {
    public function test() {
        echo "BaseClass::test() called\n";
    }

    // من غير الهام هنا إن عُرِّفت الدالة أنّها نهائية أو لم تُعرَّف
    final public function moreTesting() {
        echo "BaseClass::moreTesting() called\n";
    }
}

class ChildClass extends BaseClass {
}
// Fatal error: Class ChildClass may not inherit from final class (BaseClass)

الثوابت النهائية

لا تستخدم الكلمة المفتاحية final لثوابت الصنف في PHP، على عكس لغة Java. ويمكن استخدام الكلمة المفتاحية const بدلًا منها.

لماذا يجب أن أستخدم الكلمة المفتاحية final؟

• منع حدوث سلسلة وراثة ضخمة.
• تشجيع التكوّن
• إجبار المطور على التفكير بواجهة برمجة التطبيقات العامة للمستخدم
• إجبار المطور على تقليص واجهة برمجة التطبيقات العامة للكائن
• يمكن أن نجعل الصف المعرّف أنّه final موسِّعًا
• تحطم الكلمة المفتاحية extends التغليف
• لا تحتاج إلى المرونة
• بإمكانك تغيير الشيفرة بحريّة

لماذا يجب أن أتجنب استخدام الكلمة المفتاحية final؟

تعمل الأصناف النهائية بشكلٍ فعال فقط في وجود الافتراضات التالية:

• يوجد تجريد (واجهة) ينفذه الصنف النهائي
• كل واجهة برمجة التطبيقات العامة للصنف النهائي هي جزء من تلك الواجهة

التحميل التلقائي

‏بالطبع أنت لا ترغب في استخدام include وrequire في كل مرة تريد استخدام صنف أو وراثته، لأنّ هذا قد يكون سيئًا وسهل النسيان لذا وفرت PHP التحميل التلقائي (autoloading).

ما هو التحميل التلقائي بالضبط؟

يعني التحميل التلقائي أنّك لا تحتاج للحصول على الملف المخزّن فيه الصنف المطلوب إنّما تقوم PHP "تلقائيًا" بتحميله.

كيف يمكن أن أقوم بالتحميل التلقائي في PHP دون شيفرة من طرف ثالث؟

يمكننا استخدام الدالة ‎_autoload‎_ للقيام بالتحميل التلقائي لكن يفضّل استخدام الدالة spl_autoload_register، تستخدم PHP هذه الدوال عندما لا تجد صنف ما معرفًا ضمن النطاق المعطى. إنّ إضافة التحميل التلقائي إلى مشروع موجود لا يشكل مشكلة بما أنّ الأصناف المعرّفة (باستخدام require) ستعمل كما في السابق. ستستخدم الأمثلة التالية دوال مجهولة فإذا كنت تستخدم إصدار PHP ‎‎< 5.3 يمكنك تعريف الدالة وتمرير اسمها كوسيط للدالة spl_autoload_register.

أمثلة

spl_autoload_register(function ($className) {
    $path = sprintf('%s.php', $className);
    if (file_exists($path)) {
        include $path;
    } else {
        // الملف غير موجود
    }
});

تحاول الشيفرة السابقة تضمين اسم الملف الذي هو نفس اسم الصنف ومضافًا إليه اللاحقة "‎.php" باستخدام sprintf، إذا احتجنا لتحميل FooBar فإنّها تبحث عن FooBar.php وتضمّنه. وبالطبع يمكن توسيع هذه الشيفرة لتناسب احتياجات مشروعنا، إذا اُستخدمت _ في اسم الصف للتجميع مثل User_Post وUser_Image فمن الممكن تخزين هذه الأصناف في مجلد اسمه "User" كالتالي:

spl_autoload_register(function ($className) {
    // استبدال بالمحرف / أو \ وذلك حسب نظام التشغيل
    $path = sprintf('%s.php', str_replace('_', DIRECTORY_SEPARATOR, $className) );
    if (file_exists($path)) {
        include $path;
    } else {
        // الملف غير موجود
    }
});

سيُحمّل الصنف User_Post الآن من المسار "User/Post.php" وهكذا.

يمكن أن تتناسب الدالة spl_autoload_register مع الاحتياجات المختلفة، فإذا كانت كل ملفات أصنافك مُسمّاة بالشكل "class.CLASSNAME.php" ستوجد تداخلات مختلفة (UserPostContent => "User/Post/Content.php"‎).

إذا كنت تريد تقنية تحميل تلقائي أكثر تفصيلًا ولا تريد استخدام composer يمكنك أن تعمل دون إضافة مكتبات من طرف ثالث.

spl_autoload_register(function ($className) {
    $path = sprintf('%1$s%2$s%3$s.php',
        realpath(dirname(__FILE__)),
        DIRECTORY_SEPARATOR,
        strtolower(
            // استبدال بالمحرف / أو \ وذلك حسب نظام التشغيل
            str_replace('_', DIRECTORY_SEPARATOR, $className)
        )
    );

    if (file_exists($path)) {
        include $path;
    } else {
        throw new Exception(
        sprintf('Class with name %1$s not found. Looked in %2$s.',
                $className,
                $path
            )
        );
    }
});

في الشيفرة السابقة ‎%1$s للحصول على المسار المطلق و‎%2$s إما / أو \ وذلك حسب نظام التشغيل و‎%3$s لعدم الاهتمام فيما إذا كانت الأحرف صغيرة أو كبيرة عند إنشاء الملفات.

باستخدام المحمّلات التلقائية مثل هذه يمكنك كتابة الشيفرة التالية:

// spl_autoload_register المكان الذي عُرِّف فيه
require_once './autoload.php'; 

$foo = new Foo_Bar(new Hello_World());

استخدام الأصناف:

class Foo_Bar extends Foo {}
class Hello_World implements Demo_Classes {}

ستضمّن هذه الأمثلة الأصناف من foo/bar.php، ‏foo.php، ‏hello/world.php وdemo/classes.php.

‎استدعاء باني أب عند استنساخ ابن

من المشاكل الشائعة للأصناف الأبناء هي أنّه إذا احتوى كل من الأب والابن تابعًا بانيًا ‎__construct()‎ فسيُنفَّذ باني الصنف الابن فقط، قد تحتاج أحيانًا إلى تنفيذ باني الصنف الأب من داخل الصنف الابن عندها يمكنك استخدام عامل تحليل النطاق ‎::parent بالشكل التالي:

parent::__construct();

إليك مثالًا واقعيًا:

class Foo {
    function __construct($args) {
        echo 'parent';
    }
}

class Bar extends Foo {
    function __construct($args) {
        parent::__construct($args);
    }
}

سيؤدي تنفيذ الشيفرة السابقة إلى تنفيذ باني الصنف الأب وبالتالي ستُنفَّذ تعليمة echo.

الربط الديناميكي

يعدّ الربط الديناميكي (ويسمىّ أيضًا إعادة تعريف التابع) مثالًا للتعددية الشكلية وقت التنفيذ والتي تحدث عندما تحتوي عدة أصناف على تنفيذات مختلفة لنفس التابع لكن الكائن الذي سيستدعيه التابع لا يُعرف حتى وقت التنفيذ، ويعد هذا مفيدًا إذا حدد شرط معين أيّ صنف سيُستخدم لأداء وظيفة ما حيث هذه الوظيفة لها نفس الاسم في كلا الصنفين.

interface Animal {
    public function makeNoise();
}

class Cat implements Animal {
    public function makeNoise
    {
        $this->meow();
    }
    ...
}

class Dog implements Animal {
    public function makeNoise {
        $this->bark();
    }
    ...
}

class Person {
    const CAT = 'cat';
    const DOG = 'dog';
    private $petPreference;
    private $pet;

    public function isCatLover(): bool {
        return $this->petPreference == self::CAT;
    }

    public function isDogLover(): bool {
        return $this->petPreference == self::DOG;
    }

    public function setPet(Animal $pet) {
        $this->pet = $pet;
‏    }

    public function getPet(): Animal {
        return $this->pet;
    }
}

if($person->isCatLover()) {
    $person->setPet(new Cat());
} else if($person->isDogLover()) {
    $person->setPet(new Dog());
}

$person->getPet()->makeNoise();

في المثال السابق لا يُعرف الصنف Animal ‏(Dog|Cat) الذي سينفذ التابع makeNoise إلى وقت التنفيذ وفقًا للخاصيّة ضمن الصنف User.

‎$this، ‏self، ‏static ونمط المفردة (singleton)

نستخدم ‎$this للإشارة إلى الكائن الحالي وself للإشارة إلى الصنف الحالي، وبمعنى آخر نستخدم ‎$this->member للعناصر غير الساكنة وself::$member‎ للعناصر الساكنة.

لاحظ الفرق في المثال التالي الذي تستخدم فيه الدالة sayHello()‎ ‏‎$this وتستخدم الدالة ‎sayGoodbye()‎ ‏self:

class Person {
    private $name;

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

    public function getName() {
        return $this->name;
    }

    public function getTitle() {
        return $this->getName()." the person";
    }

    public function sayHello() {
        echo "Hello, I'm ".$this->getTitle()."<br/>";
    }

    public function sayGoodbye() {
        echo "Goodbye from ".self::getTitle()."<br/>";
    }
}

class Geek extends Person {
    public function __construct($name) {
        parent::__construct($name);
    }

    public function getTitle() {
        return $this->getName()." the geek";
    }
}

$geekObj = new Geek("Ludwig");
$geekObj->sayHello();
$geekObj->sayGoodbye();

تشير الكلمة المفتاحية static إلى أي صنف في الهرمية تستدعي عليه التابع، وتسمح بإعادة استخدام أفضل لخصائص الصنف الساكنة عندما تورَّث الأصناف.

إليك المثال التالي:

class Car {
    protected static $brand = 'unknown';

    public static function brand() {
        return self::$brand."\n";
    }
}

class Mercedes extends Car {
    protected static $brand = 'Mercedes';
}

class BMW extends Car {
    protected static $brand = 'BMW';
}

echo (new Car)->brand();
echo (new BMW)->brand();
echo (new Mercedes)->brand();

نتيجة الشيفرة السابقة:

unknown
unknown
unknown

وذلك لأنّ self تشير إلى الصنف Car بغض النظر من أين اُستدعت brand()‎، لذا فأنت تحتاج لاستخدام static للإشارة إلى الصنف الصحيح وذلك بالشكل التالي:

class Car {
    protected static $brand = 'unknown';

    public static function brand() {
        return static::$brand."\n";
    }
}

class Mercedes extends Car {
    protected static $brand = 'Mercedes';
}

class BMW extends Car {
    protected static $brand = 'BMW';
}

echo (new Car)->brand();
echo (new BMW)->brand();
echo (new Mercedes)->brand();

ستنتج هذه الشيفرة الخرج المطلوب والذي هو:

unknown
BMW
Mercedes

نمط المفردة (singleton)

إذا كان لديك كائن مكلّف بإنشاء اتصال مع مورد خارجي أو يمثّل اتصال إلى مورد خارجي معين فأنت تحتاج إلى إعادة استخدام اتصال بقاعدة البيانات حيث لا يوجد تجمّع اتصال أو مقبس إلى نظام آخر، عندها يمكنك أن تستخدم الكلمات المفتاحية static وself في الصنف ليصبح بنمط المفردة. يوجد آراء مختلفة حول نمط المفردة فيما إذا كان يجب استخدامه أو لا ولكن يبقى له استخداماته.

class Singleton {
    private static $instance = null;

    public static function getInstance(){
        if(!isset(self::$instance)){
            self::$instance = new self();
        }
        return self::$instance;
    }

    private function __construct() {
        ….
    }
}

عرّفنا في الشيفرة السابقة خاصيّة ساكنة خاصة ‎$instance لتحمل مرجعية الكائن، وبما أنّها ساكنة فستُشارك بين كل كائنات هذا النوع.

يستخدم التابع getInstance()‎ طريقة التهيئة المُرجأة (lazy instantiation) لتأخير إنشاء الكائنات إلى آخر لحظة ممكنة لأنك لا تريد أن تمتلئ الذاكرة بكائنات غير مستخدمة، وأيضًا تحافظ على الوقت وعلى المعالج عند تحميل الصفحة إذ لا تُحمَّل كائنات غير ضرورية. يتحقق التابع فيما إذا ضُبط الكائن وأُنشئ أم لا وتعيده وهذا يضمن إنشاء كائن واحد فقط من هذا النوع.

كما عرّفنا الباني أنه خاص (private) حتى نضمن أنه من غير الممكن إنشاؤه من الخارج باستخدام الكلمة المفتاحية new. إذا كنت تحتاج للوراثة من هذا الصنف فقط غيّر الكلمات المفتاحية private إلى protected.

لاستخدام هذا الكائن تكتب الشيفرة التالية:

$singleton = Singleton::getInstance();

تعريف صنف أساسي

يتألف الكائن في PHP من متغيرات ودوال، وتنتمي الكائنات إلى صنف يعرّف المتغيرات والدوال التي تحتويها كل كائنات هذا الصنف، صياغة تعريف الصنف هي كالتالي:

class Shape {
    public $sides = 0;

    public function description() {
        return "A shape with $this->sides sides.";
    }
}

عندما يُعرَّف صنف يمكنك الاستنساخ منه بالشكل التالي:

$myShape = new Shape();

يمكن الوصول لمتغيرات ودوال الكائن بالطريقة التالية:

$myShape = new Shape();
$myShape->sides = 6;

print $myShape->description(); 
// A shape with 6 sides

الباني

يمكن أن تعرّف الأصناف تابع باني خاص ‎__construct()‎ يُنفَّذ كجزء من إنشاء الكائن، ويستخدم عادةً لإعطاء القيم الابتدائية لكائن:

class Shape {
    public $sides = 0;

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

    public function description() {
        return "A shape with $this->sides sides.";
    }
}

$myShape = new Shape(6);
print $myShape->description();
// A shape with 6 sides

توسيع صنف آخر

يمكن لتعريفات الصنف أن توسّع تعريفات صنف موجود وتضيف المزيد من المتغيرات والدوال وتعدّل في المتغيرات والدوال المعرفة في الصنف الأب، إليك صنف يوسّع الصنف في المثال السابق:

class Square extends Shape {
    public $sideLength = 0;

    public function __construct($sideLength) {
        parent::__construct(4);
        $this->sideLength = $sideLength;
    }

    public function perimeter() {
        return $this->sides * $this->sideLength;
    }

    public function area() {
        return $this->sideLength * $this->sideLength;
    }
}

يتضمن الصنف Square متغيرات ودوال لكل من الصنفين Square وShape.

$mySquare = new Square(10);
print $mySquare->description()/ // A shape with 4 sides
print $mySquare->perimeter() // 40
print $mySquare->area() // 100

الأصناف المجهولة

قُدِّمت الأصناف المجهولة في الإصدار PHP 7 لتمكين إنشاء نسخة واحدة بسيطة من الصنف، ويمكن لها أن تأخذ وسائط الباني وتوسّع أصناف أخرى وتنفّذ واجهات وتستخدم السمات (traits) مثل الأصناف العادية تمامًا، والنموذج الأساسي لها كالتالي:

new class("constructor argument") {
    public function __construct($param) {
        var_dump($param);
    }
}; // string(20) "constructor argument"

لا يوفر تداخل صنف مجهول ضمن صنف آخر إمكانية الوصول إلى التوابع أو الخاصيّات الخاصة أو المحمية للصنف الخارجي، يمكن الوصول إلى الخاصيات والتوابع المحمية للصنف الخارجي بتوسيعه من قِبل صنف مجهول ويمكن الوصول إلى الخاصيات والتوابع الخاصة للصنف الخارجي بتمريرها إلى باني الصنف المجهول. مثال:

class Outer {
    private $prop = 1;
    protected $prop2 = 2;

    protected function func1() {
        return 3;
    }

    public function func2() {

        // الخاصة $this->prop التمرير عبر الخاصيّة
        return new class($this->prop) extends Outer {
            private $prop3;
            public function __construct($prop) {
                $this->prop3 = $prop;
            }
            public function func3() {
                // (1)
                return $this->prop2 + $this->func1() + $this->prop3;
            }
        };
    }
}

echo (new Outer)->func2()->func3(); // 6

في الموضع (1) الوصول إلى الخاصيّة المحمية Outer::$prop2 والتابع المحمي Outer::func1()‎ والخاصية المحلية self::$prop3 الخاصة من Outer::$prop.

ترجمة -وبتصرف- للفصل [Classes and Objects] من كتاب PHP Notes for Professionals book

اقرأ أيضًا

• المقال التالي: السلسلة Serialization في PHP
• المقال السابق: صيغة JSON وXML في PHP

الدالة json_encode تأخذ المعاملات التالية:

الدالة json_decode فتأخذ المعاملات التالية:

فك ترميز سلسلة نصية بصيغة JSON

تأخذ الدالة json_decode المعامل الأول على شكل سلسلة نصية مرمّزة بصيغة JSON وتحلله إلى متغير PHP، إذا كان كائن JSON هو مصفوفة فهي تعيد كائنًا من ‎\stdClass إذا كان عنصر المستوى الأعلى في الكائن هو قاموس (dictionary) أو مصفوفة مفهرسة، وتعيد قيمًا عددية أو NULL من أجل قيم عددية معينة مثل السلاسل النصية البسيطة "true" و"false" و"null"، وتعيد NULL عند أي خطأ.

تعيد الشيفرة التالية كائنًا بما أنّ عنصر المستوى الأعلى في السلسلة النصية بصيغة JSON هو قاموس JSON:

$json_string = '{"name": "Jeff", "age": 20, "active": true, "colors": ["red", "blue"]}';

$object = json_decode($json_string);
printf('Hello %s, You are %s years old.', $object->name, $object->age);
// Hello Jeff, You are 20 years old.

تعيد الشيفرة التالية مصفوفة بما أنّ عنصر المستوى الأعلى في السلسلة النصية بصيغة JSON هو مصفوفةJSON:

$json_string = '["Jeff", 20, true, ["red", "blue"]]';

$array = json_decode($json_string);
printf('Hello %s, You are %s years old.', $array[0], $array[1]);

يمكنك استخدام الدالة var_dump()‎ للاطلاع على أنواع وقيم كل خاصيّة للكائن الذي فُكَّ ترميزه، فإذا استخدمناها للكائن ‎$object في مثالنا السابق:

var_dump($object);

يكون الخرج:

class stdClass#2 (4) {
    ["name"] => string(4) "Jeff"
    ["age"] => int(20)
    ["active"] => bool(true)
    ["colors"] =>
    array(2) {
        [0] => string(3) "red"
        [1] => string(4) "blue"
    }
}

ملاحظة: حُوِّلت أنواع المتغيرات في JSON إلى مكافئاتها في PHP.

نقوم بتمرير true معاملًا ثانيًا للدالة json_decode()‎ لإرجاع مصفوفة ترابطية من كائنات JSON بدلًا من إرجاع كائن. مثال:

$json_string = '{"name": "Jeff", "age": 20, "active": true, "colors": ["red", "blue"]}';
$array = json_decode($json_string, true);
var_dump($array);

خرج الشيفرة السابقة:

array(4) {
    ["name"] => string(4) "Jeff"
    ["age"] => int(20)
    ["active"] => bool(true)
    ["colors"] =>
    array(2) {
        [0] => string(3) "red"
        [1] => string(4) "blue"
    }
}

ليس للمعامل الثاني ‎$assoc تأثير إذا كان المتغير الذي سيُرجع ليس كائنًا.

ملاحظة: ستفقد التمييز بين مصفوفة فارغة وكائن فارغ إذا كنت تستخدم المعامل ‎$assoc، أي أنّ تنفيذ json_encode()‎ على الخرج المفكوك ترميزه مرةً ثانية سينتج بنية JSON مختلفة.

تعيد الدالة json_decode()‎ القيمة NULL إذا كان عمق السلسلة النصية بصيغة JSON أكثر من 512 عنصر (20 عنصر في إصدارات PHP أقدم من 5.2.3 أو 128 في الإصدار 5.2.3) بالتعاود (recursion)، يمكن التحكم بهذا الحد في الإصدار 5.3 وما بعده باستخدام المعامل الثالث ‎$depth كما هو موضح في الدليل الرسمي للغة PHP:

تنفذ PHP مجموعة عليا من JSON كما ذُكر في RFC 4627 - سترمّز أيضًا وتفك ترميز الأنواع العددية وNULL، تدعم RFC 4627 فقط هذه القيم عندما تكون متداخلة ضمن مصفوفة أو كائن. بالرغم من أن هذه المجموعة العليا متوافقة مع التعريف الموسع لنص JSON في RFC 7159 الأحدث (الذي يهدف إلى التفوق على RFC 4627) وECMA-404 وهذا قد يسبب مشاكل في قابلية التشغيل المتبادل مع محللات JSON التي تلتزم بدقة بالنوع RFC 4627 عند تشفير قيمة عددية.

يعني هذا أنّ السلسلة النصية البسيطة ستعدّ كائن JSON صحيح في PHP مثال:

$json = json_decode('"some string"', true);
var_dump($json, json_last_error_msg());

الخرج:

string(11) "some string"
string(8) "No error"

لكن السلاسل النصية البسيطة التي ليست في مصفوفة أو كائن ليست جزءًا من معيار RFC 4627، أي أن المتفحصات (checkers) على الإنترنت مثل JSLint وJSON Formatter & Validator التي تعمل بالنمط RFC 4627 ستعطيك خطأً.

المعامل الثالث للدالة json_decode()‎ هو ‎$depth يحدد العمق التعاودي (القيمة الافتراضية 512)، أي عدد الكائنات المتداخلة ضمن الكائن الأصلي الذي سيُفَك تشفيره.

المعامل الرابع ‎$options يقبل قيمة واحدة حاليًا وهي JSON_BIGINT_AS_STRING، أي أنّ السلوك الافتراضي للدالة (مع عدم وجود هذا المعامل) يحول القيم الصحيحة الكبيرة إلى أعداد عشرية بدلًا من سلاسل نصية.

لا تُعدّ المتغيرات غير الصحيحة ذات الأحرف الكبيرة للكلمات true و‏false وnull دخلًا صحيحًا.

لدينا المثال التالي:

var_dump(json_decode('tRue'), json_last_error_msg());
var_dump(json_decode('tRUe'), json_last_error_msg());
var_dump(json_decode('tRUE'), json_last_error_msg());
var_dump(json_decode('TRUe'), json_last_error_msg());
var_dump(json_decode('TRUE'), json_last_error_msg());
var_dump(json_decode('true'), json_last_error_msg());

الخرج في الإصدار قبل PHP 5.6:

bool(true)
string(8) "No error"
bool(true)
string(8) "No error"
bool(true)
string(8) "No error"
bool(true)
string(8) "No error"
bool(true)
string(8) "No error"
bool(true)
string(8) "No error"

أما في الإصدارات اللاحقة:

NULL
string(12) "Syntax error"
NULL
string(12) "Syntax error"
NULL
string(12) "Syntax error"
NULL
string(12) "Syntax error"
NULL
string(12) "Syntax error"
bool(true)
string(8) "No error"

ينطبق الأمر أيضًا على false وnull.

لاحظ أنّ الدالة json_decode()‎ تُعيد NULL إذا كان من غير الممكن تحويل السلسلة النصية.

// غير صحيحة json صيغة
$json = "{'name': 'Jeff', 'age': 20 }" ;

$person = json_decode($json);
// null ملاحظة: محاولة الوصول إلى خاصيّة عنصر ليس كائنًا تُرجع
echo $person->name; 

echo json_last_error();
# 4 (JSON_ERROR_SYNTAX)

echo json_last_error_msg();
# unexpected character

ليس من الآمن أن نعتمد فقط على القيمة المُرجعة بأن تكون NULL لاكتشاف الأخطاء، فمثلًا إذا كانت السلسلة النصية بصيغة JSON لا تتضمن شيء إلا "null" فإنّ الدالة json_decode()‎ ستُرجع null حتى في حال عدم حدوث أخطاء.

ترميز سلسلة نصية بصيغة JSON

تحوّل الدالة json_encode مصفوفة PHP (أو كائن ينفذ الواجهة JsonSerializable بدءًا من الإصدار PHP 5.4) إلى سلسلة نصية بترميز صيغة JSON وتعيدها، وفي حال الفشل تعيد FALSE.

$array = [
    'name' => 'Jeff',
    'age' => 20,
    'active' => true,
    'colors' => ['red', 'blue'],
    'values' => [0=>'foo', 3=>'bar'],
];

تُحوَّل عند الترميز أنواع بيانات PHP (السلاسل النصية والأعداد الصحيحة والقيم المنطقية) إلى مكافئاتها في JSON، وتُرمَّز المصفوفات الترابطية ككائنات JSON وعند الاستدعاء مع الوسطاء الافتراضيين تُرمَّز المصفوفات المفهرسة كمصفوفات JSON، ما لم تكن مفاتيح المصفوفة سلسلة عددية مستمرة تبدأ من الصفر، فعندها ستُرمَّز المصفوفة ككائن JSON.

echo json_encode($array);

الخرج:

{"name":"Jeff","age":20,"active":true,"colors":["red","blue"],"values":{"0":"foo","3":"bar"}}

الوسائط

بدءًا من الإصدار PHP 5.3 فإنّ المعامل الثاني للدالة json_encode هو قناع بتي والذي يمكن أن يكون واحد أو أكثر من التالي، ويمكن دمجه كما هو الحال مع أي قناع بتي مع العامل الثنائي OR |.

الإصدار PHP 5.3 ومابعده

JSON_FORCE_OBJECT: يفرض إنشاء كائن بدلًا من مصفوفة.

$array = ['Joel', 23, true, ['red', 'blue']];
echo json_encode($array);
echo json_encode($array, JSON_FORCE_OBJECT);

الخرج:

["Joel",23,true,["red","blue"]]
{"0":"Joel","1":23,"2":true,"3":{"0":"red","1":"blue"}}

JSON_HEX_TAG، ‏JSONHEXAMP، ‏JSON_HEX_APOS، ‏JSON_HEX_QUOT.

تضمن الخيارات السابقة التحويلات التالية عند الترميز:

$array = ["tag"=>"<>", "amp"=>"&", "apos"=>"'", "quot"=>"\""];
echo json_encode($array);
echo json_encode($array, JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT);

الخرج:

{"tag":"<>","amp":"&","apos":"'","quot":"\""}
{"tag":"\u003C\u003E","amp":"\u0026","apos":"\u0027","quot":"\u0022"}

الإصدار PHP 5.3 ومابعده

JSON_NUMERIC_CHECK: يضمن تحويل السلاسل النصية العددية إلى أعداد صحيحة.

$array = ['23452', 23452];
echo json_encode($array);
echo json_encode($array, JSON_NUMERIC_CHECK);

الخرج:

["23452",23452]
[23452,23452]

الإصدار PHP 5.4 ومابعده

JSON_PRETTY_PRINT: يجعل صيغة JSON مقروءة بسهولة.

$array = ['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4];
echo json_encode($array);
echo json_encode($array, JSON_PRETTY_PRINT);

الخرج:

{"a":1,"b":2,"c":3,"d":4}
{
    "a": 1,
    "b": 2,
    "c": 3,
    "d": 4
}

JSON_UNESCAPED_SLASHES: يضمّن هذا الخيار خطوط الهروب المائلة الأمامية / في الخرج:

$array = ['filename' => 'example.txt', 'path' => '/full/path/to/file/'];
echo json_encode($array);
echo json_encode($array, JSON_UNESCAPED_SLASHES);

الخرج:

{"filename":"example.txt","path":"\/full\/path\/to\/file"}
{"filename":"example.txt","path":"/full/path/to/file"}

JSON_UNESCAPED_UNICODE: يضمّن محارف بترميز UTF8 في الخرج بدلًا من السلاسل النصية بترميز يونيكود.

$blues = ["english"=>"blue", "norwegian"=>"blå", "german"=>"blau"];
echo json_encode($blues);
echo json_encode($blues, JSON_UNESCAPED_UNICODE);

الخرج:

{"english":"blue","norwegian":"bl\u00e5","german":"blau"}
{"english":"blue","norwegian":"blå","german":"blau"}

الإصدار PHP 5.5 ومابعده

JSON_PARTIAL_OUTPUT_ON_ERROR: يسمح بمتابعة الترميز حتى لو وُجدت بعض القيم غير قابلة للترميز.

$fp = fopen("foo.txt", "r");
$array = ["file"=>$fp, "name"=>"foo.txt"];
echo json_encode($array); // no output
echo json_encode($array, JSON_PARTIAL_OUTPUT_ON_ERROR);

الخرج:

{"file":null,"name":"foo.txt"}

الإصدار PHP 5.6 ومابعده

JSON_PRESERVE_ZERO_FRACTION: يضمن ترميز الأعداد العشرية كأعداد عشرية دومًا.

$array = [5.0, 5.5];
echo json_encode($array);
echo json_encode($array, JSON_PRESERVE_ZERO_FRACTION);

الخرج:

[5,5.5]
[5.0,5.5]

الإصدار PHP 7.1 ومابعده

JSON_UNESCAPED_LINE_TERMINATORS: عندما يُستخدم مع JSON_UNESCAPED_UNICODE يعود إلى سلوك إصدارات PHP القديمة ولا يتجاوز المحرف الفاصل للأسطر U+2028 والمحرف الفاصل للفقرات U+2029. بالرغم من أن هذه المحارف صحيحة في JSON فهي غير صحيحة في جافاسكربت لذا فقد تغيّر السلوك الافتراضي للخيار JSON_UNESCAPED_UNICODE في الإصدار PHP 7.1.

$array = ["line"=>"\xe2\x80\xa8", "paragraph"=>"\xe2\x80\xa9"];
echo json_encode($array, JSON_UNESCAPED_UNICODE);
echo json_encode($array, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_LINE_TERMINATORS);

الخرج:

{"line":"\u2028","paragraph":"\u2029"}
{"line":" ","paragraph":" "}

تنقيح أخطاء JSON

عندما تفشل إحدى الدالتين json_encode أوjson_decode في التحليل إلى السلسلة النصية المطلوبة فإنّها تعيد false، ولا تنشر PHP أي أخطاء أو تحذيرات في هذه الحالة إنما تقع المسؤولية على المستخدم الذي يجب أن يستخدم الدالتين json_last_error()‎ وjson_last_error_msg()‎ للتحقق من حدوث أخطاء ومعالجتها وفق التطبيق (تنقيحها، عرض رسالة خطأ وغير ذلك).

يظهر المثال التالي خطأً مشهورًا عند العمل مع JSON وهو الفشل في ترميز/فك ترميز سلسلة نصية بصيغة JSON (بسبب تمرير سلسلة نصية بترميز UTF-8 غير صحيح مثلًا).

// غير صحيحة JSON سلسلة نصية بصيغة
$jsonString = json_encode("{'Bad JSON':\xB1\x31}");

if (json_last_error() != JSON_ERROR_NONE) {
    printf("JSON Error: %s", json_last_error_msg());
}

// JSON Error: Malformed UTF-8 characters, possibly incorrectly encoded

json_last_error_msg

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

تعيد هذه الدالة دومًا سلسلة نصية حتى لو لم يحدث خطأ والرسالة الافتراضية في حال عدم حدوث خطأ هي No Error، وتعيد false إذا حدث خطأ ما (غير معروف).

يجب الحذر عند استخدام هذه الدالة في الحلقات لأنّه سيتم تجاوزها في كل حلقة، ويجب استخدامها فقط للحصول على الرسالة للعرض وليس لاستخدامها في تعليمات التحكم.

// لا تكتب هذه الشيفرة
// لأن نتيجة الدالة سلسلة نصية true النتيجة دائمًا
if (json_last_error_msg()){}

// ممارسة سيئة
if (json_last_error_msg() != "No Error"){}

// (يمكنك كتابة هذا (اختبار العدد الصحيح مع إحدى الثوابت المعرفة مسبقًا‎‏
if (json_last_error() != JSON_ERROR_NONE) {
    // لعرض رسالة فقط وليس للاختبار json_last_error_msg استخدمنا
    printf("JSON Error: %s", json_last_error_msg());
}

لم تكن هذه الدالة موجودة في الإصدارات السابقة للإصدار PHP 5.5. إليك تنفيذ الترقيع المتعدد (polyfill):

if (!function_exists('json_last_error_msg')) {
    function json_last_error_msg() {
        static $ERRORS = array(
            JSON_ERROR_NONE => 'No error',
            JSON_ERROR_DEPTH => 'Maximum stack depth exceeded',
            JSON_ERROR_STATE_MISMATCH => 'State mismatch (invalid or malformed JSON)',
            JSON_ERROR_CTRL_CHAR => 'Control character error, possibly incorrectly encoded',
            JSON_ERROR_SYNTAX => 'Syntax error',
            JSON_ERROR_UTF8 => 'Malformed UTF-8 characters, possibly incorrectly encoded'
        );

        $error = json_last_error();
        return isset($ERRORS[$error]) ? $ERRORS[$error] : 'Unknown error';
    }
}

json_last_error()‎

تعيد هذه الدالة عددًا صحيحًا مربوطًا بإحدى ثوابت PHP المعرفة مسبقًا.

استخدام الواجهة JsonSerializable في كائن

الإصدار PHP 5.4 وما بعده

قد تحتاج عند بناء واجهة برمجة التطبيقات REST (‏Representational state transfer) إلى تقليل بيانات كائن ليُمرَّر إلى تطبيق العميل، ولهذا الهدف يوضّح المثال التالي كيفية استخدام الواجهة JsonSerializable.

في هذا المثال يوسّع الصنف User كائن DB model من تقنية ORM الافتراضية (تقنية ربط الكائنات بالعلاقات).

class User extends Model implements JsonSerializable {
    public $id;
    public $name;
    public $surname;
    public $username;
    public $password;
    public $email;
    public $date_created;
    public $date_edit;
    public $role;
    public $status;

    public function jsonSerialize() {
        return [
            'name' => $this->name,
            'surname' => $this->surname,
            'username' => $this->username
        ];
    }
}

نضيف تنفيذ JsonSerializable للصنف بتوفير التابع jsonSerialize()‎.

public function jsonSerialize()

الآن عند تمرير الكائن User في وحدة تحكم التطبيق (controller) أو السكربت إلى الدالة json_encode()‎ ستحصل على مصفوفة معادة بصيغة JSON للتابع jsonSerialize()‎ بدلًا من الكائن بأكمله.

json_encode($User);

تعيد الشيفرة السابقة:

{"name":"John", "surname":"Doe", "username" : "TestJson"}

مثال قيم الخاصيات

سيقلل هذا كمية البيانات المُعادة من النقطة النهائية (endpoint) لواجهة برمجة التطبيقات RESTful ويسمح باستبعاد خاصيّات الكائن من تمثيل JSON.

استخدام الخاصيّات الخاصة والمحمية مع الدالة json_encode()‎

إذا أردت تجنّب استخدام JsonSerializable فمن الممكن استخدام الخاصيّات الخاصة أو المحمية لإخفاء بيانات الصنف من خرج الدالة json_encode()‎ وعندها لا يحتاج الصنف إلى تنفيذ الواجهة JsonSerializable.

ترمّز الدالة json_encode()‎ الخاصيّات العامة فقط من الصنف إلى صيغة JSON.

<?php
    class User {
        // الخاصيّات الخاصة تُستخدم فقط ضمن هذا الصنف
        private $id;
        private $date_created;
        private $date_edit;

        // الخاصيّات المستخدمة في الأصناف الموسّعة
        protected $password;
        protected $email;
        protected $role;
        protected $status;

        // مشاركة هذه الخاصيّات مع المستخدم النهائي
        public $name;
        public $surname;
        public $username;

        // هنا jsonSerialize() لا نحتاج لاستخدام
    }

$theUser = new User();

var_dump(json_encode($theUser));

الخرج:

string(44) "{"name":null,"surname":null,"username":null}"

ترويسة JSON والرد المُعاد

نضيف في الشيفرة التالية ترويسة مع نوع المحتوى JSON:

<?php
    $result = array('menu1' => 'home', 'menu2' => 'code php', 'menu3' => 'about');

// json إرجاع الرد بصيغة
header('Content-Type: application/json'); // تصريح الترويسة

// الترميز
echo json_encode($result, true); 
exit();

الترويسة موجودة لذا يتمكن التطبيق من اكتشاف ما البيانات المُعادة وكيف يجب معالجتها، ولا حظ أنّ ترويسة المحتوى هي فقط معلومات حول نوع البيانات المُعادة.

إذا كنت تستخدم UTF-8 يمكنك كتابة:

header("Content-Type: application/json;charset=utf-8");

مثال jQuery:

$.ajax({
    url:'url_your_page_php_that_return_json'
}).done(function(data){
    console.table('json ',data);
    console.log('Menu1: ', data.menu1);
});

إنشاء ملف XML باستخدام DomDocument

نحتاج لإنشاء ملف XML باستخدام الصنف DOMDocument إلى إنشاء كل الوسوم والخاصيّات باستخدام التابعين createElement()‎ وcreateAttribute()‎ اللذين ينشئان بنية XML باستخدام التابع appendChild()‎.

يتضمن المثال التالي وسوم وخاصيات وقسم CDATA (‏Character Data) وفضاء اسم مختلف للوسم الثاني:

$dom = new DOMDocument('1.0', 'utf-8');
$dom->preserveWhiteSpace = false;
$dom->formatOutput = true;

// إنشاء الوسوم الأساسية دون القيم
$books = $dom->createElement('books');
$book_1 = $dom->createElement('book');

// إنشاء بعض الوسوم مع قيم
$name_1 = $dom->createElement('name', 'PHP - An Introduction');
$price_1 = $dom->createElement('price', '$5.95');
$id_1 = $dom->createElement('id', '1');

// إنشاء وإضافة خاصية
$attr_1 = $dom->createAttribute('version');
$attr_1->value = '1.0';
// إضافة الخاصية
$id_1->appendChild($attr_1);

// الثاني بفضاء اسم مختلف book إنشاء
$namespace = 'www.example.com/libraryns/1.0';

// books تضمين بادئة فضاء الاسم في الوسم
$books->setAttributeNS('http://www.w3.org/2000/xmlns/', 'xmlns:ns', $namespace);
$book_2 = $dom->createElementNS($namespace,'ns:book');
$name_2 = $dom->createElementNS($namespace, 'ns:name');

// name أخرى ووضعه ضمن الوسم DOMNode الذي هو نسخة CDATA إنشاء قسم
$name_cdata = $dom->createCDATASection('PHP - Advanced');
$name_2->appendChild($name_cdata);
$price_2 = $dom->createElementNS($namespace, 'ns:price', '$25.00');
$id_2 = $dom->createElementNS($namespace, 'ns:id', '2');

// XML إنشاء ملف
$books->appendChild($book_1);
$book_1->appendChild($name_1);
$book_1->appendChild($price_1);
$book_1->appendChild($id_1);
$books->appendChild($book_2);
$book_2->appendChild($name_2);
$book_2->appendChild($price_2);
$book_2->appendChild($id_2);

$dom->appendChild($books);

// في سلسلة نصية XML ملف saveXML() يعيد التابع
print_r ($dom->saveXML());

ستنتج الشيفرة السابقة ملف XML التالي:

<?xml version="1.0" encoding="utf-8"?>
<books xmlns:ns="www.example.com/libraryns/1.0">
    <book>
        <name>PHP - An Introduction</name>
        <price>$5.95</price>
        <id version="1.0">1</id>
    </book>
    <ns:book>
        <ns:name><![CDATA[PHP - Advanced]]></ns:name>
        <ns:price>$25.00</ns:price>
        <ns:id>2</ns:id>
    </ns:book>
</books>

قراءة ملف XML باستخدام DOMDocument

يمكن استخدام الصنف DOMDocument بطريقة مشابهة لاستخدام SimpleXML لتحليل XML من سلسلة نصية أو من ملف XML.