قل مرحبا - Saying Hello

¶

في هذا الموضوع سنتعرف على كيفية إنشاء صفحة "Hello" جديدة في التطبيق الذي قمت بتثبيته، ولتحقيق ذلك، يجب عليك القيام بإنشاء action و view لهذه الصفحة:

• سيقوم التطبيق بإرسال ال request الخاص بالصفحة إلى ال action.
• وسيقوم ال action بدوره في جلب ال view التي تعرض كلمة "Hello" إلى المستخدم النهائي.

من خلال هذا البرنامج التعليمي ، ستتعلم ثلاثة أشياء:

1. كيفية إنشاء action ليقوم بإستقبال ال request ومن ثم الرد (respond) عليها.
2. كيفية إنشاء view وإضافة المحتوى الى ال respond.
3. و كيفية إنشاء التطبيق لل requests التي يوجهها لل actions.

إنشاء ال Action

¶

لإنشاء صفحة "Hello"، ستقوم بإنشاء say action والذي بدوره سيقوم بقراءة ال message parameter من ال request، ومن ثم عرض ال message مرة أخرى إلى المستخدم. إذا كان ال request لا يحمل معه ال message parameter فإن ال action سيقوم بطباعة message إفتراضية وهي "Hello".

معلومة: ال Actions هي الكائنات(objects) التي يمكن للمستخدمين من الوصول اليها وتنفيذ ما في بداخلها بشكل مباشر. يتم تجميع هذه ال Actions بواسطة ال controllers. ونتيجة لذلك فإن ال response الراجعة للمستخدم ستكون هي نتيجة التنفيذ الخاصة بال action.

يجب تعريف ال actions داخل ال controller، ولتبسيط الفكرة، سنقوم بتعريف ال say action داخل أحد ال controller الموجود مسبقا وهو ال siteController. هذا ال controller ستجده داخل المسار controllers/siteController.php. ومن هنا سنبدأ بإضافة ال action الجديد:

<?php

namespace app\controllers;

use yii\web\Controller;

class SiteController extends Controller
{
    // ...existing code...

    public function actionSay($message = 'Hello')
    {
        return $this->render('say', ['message' => $message]);
    }
}

في الشيفرة البرمجية السابقة ، تم تعريف ال say action من خلال إنشاء الدالة actionSay داخل الكلاس siteController. يستخدم ال Yii كلمة action ك prefix للدوال للتميز بين الدوال ال action و ال non-action في ال controller، كما يستخدم الإسم الخاص بال action مباشرة بعد ال prefix، ويتم عمل mapping بين ال action method name وال action id ليستطيع المستخدم من الوصول للدالة المنشئة من خلال ال action id.

عندما يتعلق الأمر بتسمية ال action الخاصة بك، يجب عليك أن تفهم كيف يقوم ال Yii بالتعامل مع ال action id، ال action id يجب أن يكون دائما أحرف lower case، وإذا إحتوى ال action id على عدة كلمات فإن الفاصل بينهم سيكون الداش (dashes) مثل create-comment، ويتم ربط ال action id بال action method name من خلال حذف ال dashes من ال IDs، ويتم عمل capitalizing لأول خرف من كل كلمة، وإضافة ال prefix الى الناتج السابق من التحويل. مثال: ال action id المسمى ب create-comment سيتم تحويله الى ال action method name التالي: actionCreateComment.

في المثال السابق، يقوم ال action method على إستقبال parameter يسمى ب $message، والذي يملك قيمة إفتراضية وهي "Hello" (وهي مشابة تماما لطريقة وضع القيم الإفتراضية لل argument في ال PHP). عندما يستقبل التطبيق ال request ويحدد أن ال action المطلوب للتعامل مع الطلب (request) هو say، فإن التطبيق سيقوم بإسناد القيمة الموجودة بال request الى ال parameter الموجود بال action بشرط أن يكون الإسم الموجود بال request هو نفسه الموجود في ال action. ولتبسيط الموضوع يمكن القول أن ال request اذا احتوى على كلمة message وقيمة هذا ال parameter هي "GoodBye"، فإن ال $message الموجودة في ال action ستصبح قيمتها "GoodBye".

من خلال ال action method، يتم استدعاء ال [[yii\web\Controller::render()|render()]] لتقديم الملف الخاص بال view والمسمى هنا ب say. أيضا فإن ال message يتم تمرريرها الى ال view مما يسمح لك باستخدام هذا ال parameter داخل ال view. النتيجة المرجعة لل view تتم معالجتها وإرجاعها من خلال ال action method، وهذه النتائج سيتم إستقبالها من خلال المتصفح الخاص بالمستخدم ليتم عرضها وكأنها (جزء من صفحة Html كاملة).

إنشاء ال View

¶

ال Views هي شيفرات برمجية كتبت ﻹنشاء المحتوى المناسب بنائا على ال response الراجع اليها من خلال ال action. بالنسبة إلى مثال "Hello" ، الآن سنقوم بإنشاء view مسمى ب say، والذي سيقوم بدوره بطباعة ال message التي تم إستلامها من ال action، شاهد المثال:

<?php
use yii\helpers\Html;
?>
<?= Html::encode($message) ?>

صفحة ال view say يجب أن يتم حفظها داخل المسار التالي: views/site/say.php. عندما يتم إستدعاء الدالة [[yii\web\Controller::render()|render()]] من قبل ال action، فإنه سينظر للمسار على الشكل التالي: views/ControllerID/ViewName.php، بحيث يكون في مثالنا السابق ال ContollerID هو ال site وال viewName هو say.

ملاحظة: في الشيفرة البرمجية أعلاه، تكون ال message مضمنة داخل ال [[yii\helpers\Html::encode()]] قبل أن يتم طباعتها، هذا الأمر ضروري لأن ال parameter التي تأتي من المستخدم النهائي لا يجب الوثوق بها، فهي يمكن أن تحتوي على شيفرات برمجية تستغل الضعف الحاص بك بموضوع الأمان مثل vulnerable to XSS attack عن طريق دمج JS code مع ال parameter.

وبطبيعة الحال، يمكنك وضع المزيد من المحتوى في صفحة ال say view. ويمكن أن يتكون هذا المحتوى من HTML tag و plain text وحتى PHP statements. في الواقع، تعد ال say view مجرد شيفرة برمجية بلغة ال PHP والتي يتم تنفيذها بواسطة [[yii\web\Controller::render()|render()]]. المحتوى الذي سيتم طباعته من خلال ال view سيتم إرجاعه الى التطبيق من خلال ال response، وسيقوم التطبيق بدوره بإخراج هذه النتيجة إلى المستخدم النهائي.

تطبيق المثال

¶

---

بعد إنشاء ال action وصفحة ال view، يمكنك الوصول إلى الصفحة الجديدة عن طريق عنوان URL التالي:

https://hostname/index.php?r=site%2Fsay&message=Hello+World

سينتج عن هذا ال URL صفحة تعرض "Hello World". هذه الصفحة لديها نفس ال Header و ال Footer لصفحات التطبيق الأخرى.

إذا قمت بحذف ال message parameter من ال URL ، فسترى الصفحة تعرض كلمة " Hello " فقط. ويرجع ذلك إلى أن "message" يتم تمريرها ك parameter إلى ال actionSay()، وعندما يتم حذفها، سيتم استخدام القيمة الافتراضية وهي "Hello" بدلاً من ذلك.

معلومة: تتشارك الصفحة الجديدة مع الصفحات الأخرى بالتطبيق بنفس ال Header وال Footer وذلك بسبب الدالة [[yii\web\Controller::render() | render ()]] والتي ستقوم بشكل تلقائي بتضمين النتيجة الخاصة بصفحة ال view say مع صفحة ال Layout، والتي يمكنك أن تجدها داخل المسار التالي: views/layouts/main.php

ال r الموجودة في ال URL أعلاه يتطلب الكثير من الشرح. ولكن باختصار يمكن القوم أنها اختصار ل route ، وهو معرف فريد من نوعه(unique ID) للتطبيق بحيث يقوم بالتأشير على ال action، والصيغة الخاصة بال route هي ControllerID/ActionID. عندما يتلقى التطبيق request، فإنه سيتم التحقق من r parameter، فيقوم باستخدام الجزء ControllerID لتحديد ال controller class المطلوب ليقوم بعمل instance منه، ومن ثم يقوم ال controller باستخدام ال "ActionID" لتحديد ال action المطلوب والذي سيقوم بالعمل الفعلي. في المثال الخاص بنا، فإن ال route هو "site/say"، وهذا ال route يتم معالجته ليستدعي ال controller class المسمى ب SiteController و ال action المسمى ب actionSay داخل هذا ال controller، ونتيجة لذلك سيتم فعليا إستدعاء الدالة SiteController::actionSay() لتقوم بمعالجة ال request كما يلزم.

معلومة: مثل ال actions، تحتوي ال controllers أيضًا على Uniquely IDs يتم تعريفها واستخدامها من خلال التطبيق. تستخدم ال Controllers IDs نفس قواعد التسمية الخاصة بال action IDs، ويتم ذلك من خلال حذف ال dashes و capitalizing أول حرف من كل كلمة، ثم إضافة كلمة Controller الى الإسم الناتج -وهنا الإختلاف عن ال action ID-. مثال: ال controller ID المسمى ب "post-comment" ستم معالجته ليصبح PostCommentController.

الخلاصة

¶

في هذا الموضوع، قمنا بالتعرف على ال controller وال view كأجزاء من MVC architectural pattern، كما قمنا بإنشاء action داخل controller موجود ليستقبل specific request ويتحكم فيه، وقمنا أيضا بإنشاء view لعرض المحتوى. في هذا المثال البسيط، لم نتطرق الى ال model، وقمنا فقط باستخدام ال data بشكل مباشر من خلال ال message parameter.

كما تعرفنا أيضا على ال routes في ال Yii، والتي تعمل بدورها كجسر بين ال user request وال controller actions.

في الموضوع القادم، ستتعلم كيف يمكنك إنشاء model وكيف يمكنك إنشاء صفحة جديدة تحتوي على Html form.