البحث في الموقع

اشتهر استخدام منصة Heroku السحابية ضمن مجتمع مطوري Ruby on Rails ونالت فيه شعبية واسعة؛ إلا أن الخدمة لم تقتصر على مطوري Ruby وما يدور حولها بل تجاوزتهم إلى تقديم الدعم للغات برمجة مثل Node.js ،Java و PHP؛ من بين أخرى. توفّر Heroku خطّة اشتراك مجانية يمكن استخدامها لإدارة مشاريع صغيرة جدا أو لأغراض الاختبار. سنشرح في هذا الدرس كيفية الاستفادة من Heroku عبر هذه الخطة لنشر Deploying تطبيقات Laravel. إنشاء حساب على Heroku يجب أولا أن ننشئ حسابا على موقع الخدمة حتى يمكننا الاستفادة منها. التسجيل مجاني ولا يستغرق سوى دقائق. ستُعرَض عليك خلال عملية التسجيل خيارات للغة البرمجة التي تريد استخدامها، اختر PHP؛ مع العلم أن هذا الخيار لا يؤثّر على إمكانية استعمالك للغات برمجة أخرى مستقبلا. تثبيت Heroku Toolbelt الخطوة الثانية بعد إنشاء الحساب هي تثبيت أداة Heroku Toolbelt. تُستخدَم هذه الأداة، التي تعمل عبر سطر الأوامر، لإدارة جوانب عدّة من المشاريع المضافة إلى Heroku؛ ومن ضمنها إدارة عمليّة النشر، تهجير Migrating قاعدة البيانات والتخاطب مع خادوم Heroku. تتوفّر الأداة على وندوز، ماك وتوزيعة أوبونتو لينكس. نفّذ بعد تثبيت الأداة الأمر التالي: $ heroku login heroku-cli: Installing CLI... 21.83MB/21.83MB Enter your Heroku credentials. Email: mail@example.com Password (typing will be hidden): Logged in as mail@example.com انتظر قليلا حتى يكتمل تنزيل عميل Heroku ثمّ أدخل معلومات الاستيثاق الخاصّة بك (عنوان البريد وكلمة السر). نشر تطبيق Laravel على Heroku يمكننا الآن بعد التسجيل في Heroku وتثبيت الأداة Heroku Toolbelt نشرُ مشروع Laravel. نبدأ بإنشاء مشروع Laravel جديد (على الحاسوب الشخصي): $ composer create-project laravel/laravel dev.herokutest.com dev-develop Installing laravel/laravel (dev-develop 083db95...dac46617) - Installing laravel/laravel (dev-develop develop) Cloning develop ... Compiling views Do you want to remove the existing VCS (.git, .svn..) history? [Y,n]? Y Application key [9UCBk7IDjvAGrkLOUBXw43yYKlymlqE3Y] set successfully. ثم ننشئ ملفا باسم Procfile ونضعه في المجلد الجذر لمشروع Laravel. طريقة كتابة اسم الملفّ مهمة جدا (الحرف الأول كبير، ولا وجود لامتداد للملف). يقرأ Heroku هذا الملفّ لتحديد نوع العمليات التي سيجريها بعد نشر التطبيق. في حالة تطبيق Laravel فإن نوع العمليات المطلوب هو وِب web. نحدّد نوع خادوم الوِب المستخدم لتقديم التطبيق (Apache) والمجلّد الذي توجد به ملفات التطبيق المخصّصة للعرض، وهو في حالة Laravel المجلد public. يصبح ملفّ Procfile على النحو التالي: web: vendor/bin/heroku-php-apache2 public هذا فقط مثال على الخيارات المتاحة، يمكنك تغيير هذه الخيارات (خادوم الوِب مثلا) إن أردت ذلك. الخطوة الموالية لإنشاء ملفّ Procfile هي وضع المشروع تحت تصرّف نظام إدارة الإصدارات Git بإنشاء مستودع للمشروع: $ git init Initialized empty Git repository in /home/zeine77/dev.herokutest.com/.git/ $ git add . $ git commit -m "First commit" يسهّل استخدامُ Git كثيرا عمليةَ النشر، فإطار العمل Laravel يأتي مبدئيا بميزات خاصّة بنظام إدارة الإصدارات Git (مثل ملفات gitignore.)؛ كما أن Heroku أيضا يتفاعل مع مستودع Git المحلي لتسهيل النشر. راجع هذه المقالات لمعرفة المزيد عن Git. نحن الآن جاهزون لنشر التطبيق على Heroku. نستخدم Heroku Toolbelt لهذه المهمة: $ heroku create Heroku CLI submits usage information back to Heroku. If you would like to disable this, set `skip_analytics: true` in /home/zeine77/.heroku/config.json Creating app... done, ⬢ nameless-chamber-90421 https://nameless-chamber-90421.herokuapp.com/ | https://git.heroku.com/nameless-chamber-90421.git ينشئ الأمر heroku create اسما جديدا لمشروعك (أعطاني الاسم nameless-chamber-90421) ويعرّف رابطا يمكن عبره الوصول إلى التطبيق. لا يوجد على الرابط - لحد السّاعة - سوى صفحة مبدئية من Heroku. زيادة على الرابط والاسم، أنشأ الأمر السابق مستودع Git بعيدا. مستودع Git بعيد هو مستودع يضم ملفات مشروعك ولكنه يوجد في مكان آخر غير جهازك؛ يمكن دفع التغييرات إلى المشروع البعيد أو جلبها منه. سنكتفي في حالة Heroku بدفع التعديلات إلى المستودع البعيد، كما سنرى بعد قليل. يستخدم Heroku ملفات تسمى buildpacks (حزم بناء) لمعرفة البرامج التي يجب عليه إعدادها على الخادوم بعد تثبيت التطبيق؛ لذا يجب أن نحدّد واحدا. اخترنا ملفّ buildpack الرسمي من Heroku الخاص بتطبيقات PHP؛ نستخدم الأمر config:add في Heroku Toolbelt لتحديد هذا الملف: $ heroku config:add BUILDPACK_URL=https://github.com/heroku/heroku-buildpack-php Setting BUILDPACK_URL and restarting ⬢ nameless-chamber-90421... done, v3 BUILDPACK_URL: https://github.com/heroku/heroku-buildpack-php تستخدم تطبيقات Laravel مفتاح تعميّة Encryption key لتعمية معلومات جلسة المستخدم ومعلومات أخرى؛ توجد قيمة هذا المفتاح في متغيّر البيئة APP_KEY. يوجد المتغيّر APP_KEY في الملفّ env.، إلا أن الملف env. لا يدخل في إطار الملفات التي يتعامل معها Git، نظرا لوجوده في الملفات المحدّدة في gitignore.. سنحتاج إذن لتوليد مفتاح تعميّة لاستخدامه على خادوم Heroku. تُستخدم أداة artisan لتوليد مفتاح تعمية على النحو التالي: php artisan key:generate --show يولّد الأمر أعلاه مفتاح تعميّة ويعرضه على سطر الأوامر؛ إلا أننا نريد أن نخزّن المفتاح على الخادوم؛ نستخدم Toolbelt لهذا الغرض على النحو التالي: heroku config:set APP_KEY=$(php artisan --no-ansi key:generate --show) Setting APP_KEY and restarting ⬢ nameless-chamber-90421... done, v7 APP_KEY: base64:jp40IC7SV5eJ5IhjQYwqk/KXJG0uS+ZhCqSGwkwgELs= يضبط الأمر السابق قيمة المتغيّر APP_KEY على الخادوم لتساوي نتيجة تنفيذ الأمر php artisan --no-ansi key:generate --show. حان الآن وقت النشر فعليا؛ ندفع التغييرات في المستودع المحلي إلى المستودع البعيد باستخدام Git على النحو التالي: $ git push heroku master Counting objects: 103, done. Delta compression using up to 4 threads. Compressing objects: 100% (84/84), done. Writing objects: 100% (103/103), 43.87 KiB | 0 bytes/s, done. Total 103 (delta 5), reused 0 (delta 0) remote: Compressing source files... done. remote: Building source: remote: remote: -----> Fetching set buildpack https://github.com/heroku/heroku-buildpack-php... done remote: -----> PHP app detected remote: remote: ! WARNING: Your 'composer.json' contains a non-'stable' setting remote: for 'minimum-stability'. This may cause the installation of remote: unstable versions of runtimes and extensions during this deploy. remote: It is recommended that you always use stability flags instead, remote: even if you have 'prefer-stable' enabled. For more information, remote: see https://getcomposer.org/doc/01-basic-usage.md#stability remote: remote: -----> Bootstrapping... remote: -----> Installing platform packages... remote: - php (7.0.7) remote: - ext-mbstring (bundled with php) remote: - apache (2.4.20) remote: - nginx (1.8.1) remote: -----> Installing dependencies. (...) remote: -----> Compressing... remote: Done: 15.5M remote: -----> Launching... remote: Released v4 remote: https://nameless-chamber-90421.herokuapp.com/ deployed to Heroku remote: remote: Verifying deploy... done. To https://git.heroku.com/nameless-chamber-90421.git * [new branch] master -> master إن نظرت إلى لوحة التحكّم في Heroku ستجد سجلا بالإجراءات السابقة. هذا كلّ ما في الأمر؛ اكتمل نشرُ تطبيقك الآن ويمكنك الوصول إليه على الرابط المذكور أعلاه. يجب أن تظهر صفحة Laravel المبدئية. تذكّر أن الرابط المنشَأ سابقا موجود فقط لأغراض الاختبار والتجربة، عندما يكون تطبيقك جاهزا لتلقي الجماهير يمكنك استخدام نطاقك الخاص وربطه بالتطبيق. تهجير قاعدة البيانات نشرنا في الخطوات السابقة تطبيق Laravel جديدا؛ إلا أن هذه الخطوات لن تكون كافية إن كان التطبيق يعتمد على قاعدة بيانات. ستحتاج في هذه الحالة إلى التأكد من تنفيذ جميع التهجيرات العالقة بعد كلّ عملية نشر. بما أن التطبيق جديد على Heroku فسنحتاج لتموين Provision قاعدة البيانات؛ نستخدم Toolbelt لهذا الغرض: $ heroku addons:create heroku-postgresql:hobby-dev Creating postgresql-rigid-59415... done, (free) Adding postgresql-rigid-59415 to nameless-chamber-90421... done Setting DATABASE_URL and restarting nameless-chamber-90421... done, v10 Database has been created and is available ! This database is empty. If upgrading, you can transfer ! data from another database with pg:copy Use `heroku addons:docs heroku-postgresql` to view documentation. ينشئ الأمر السابق قاعدة بيانات PostgreSQL معرّفة بالخطة المجانيّة hobby-dev التي تمكننا من إنشاء قاعدة بيانات مجانية على Heroku، على ألا يتجاوز عدد أسطرها العشرة آلاف. توجد خطط أخرى يمكن النظر فيها لإيجاد ما يناسبك إن كنت تريد استخدام Heroku بيئةً للإنتاج. يعود السبب في اختيارنا لقاعدة بيانات PostgreSQL بدلا من MySQL إلى أن دعم الأخيرة على Heroku محدود، ستجد لهذا السبب أن الكثير من التوثيق حول خدمة Heroku يعتمد على قاعدة البيانات PostgreSQL. ثم نفذ الأمر التالي للحصول على المزيد من التفاصيل عن قاعدة البيانات ومن ضمنها الاستيثاق (تأكد من اسم التطبيق): $ heroku config --app nameless-chamber-90421 | grep DATABASE_URL DATABASE_URL: postgres://USERNAME:PASSWORD@HOSTNAME:PORT/DATABASE يظهر في نتيجة الأمر اسمُ المستخدم USERNAME، كلمة السّر PASSWORD، اسم المضيف HOSTNAME، المنفذ PORT واسم قاعدة البيانات DATABASE. لن يكون ضروريا حفظ هذه الإعدادات فالمتغير DATABASE_URL الذي يخزّنها محفوظ تلقائيا في إعدادات الخادوم. يمكنك تسهيل إدارة قاعدتي البيانات على طرفيْ العمل (بيئة التطوير وبيئة الإنتاج) بضبط متغيّر بيئة باسم DATABASE_URL على جهازك المحلي وتخزين إعدادات قاعدة البيانات فيه ثم استخدامه لإعداد اتصال Laravel بقاعدة البيانات. ستحتاج لتثبيت PostgreSQL على جهازك إن لم يكن مثبتا مسبقا. يستعمل Laravel مبدئيا قاعدة بيانات MySQL، لذا يجب أن نعدّه لاستخدام PostgreSQL. نفتح ملفّ إعداد الاتصال بقاعدة البيانات config/database.php ونبحث عن السطر التالي: 'default' => env('DB_CONNECTION', 'mysql'), ثم نعدّله على النحو التالي: 'default' => env('DB_CONNECTION', 'pgsql'), ثم ننتقل إلى المقطع الخاصّ بإعداد PostgreSQL ضمن ملفّ إعداد الاتصال ونعدّله ليصبح كالتالي: 'pgsql' => [ 'driver' => 'pgsql', 'host' => parse_url(getenv("DATABASE_URL"))["host"], 'database' => substr(parse_url(getenv("DATABASE_URL"))["path"], 1), 'username' => parse_url(getenv("DATABASE_URL"))["user"], 'password' => parse_url(getenv("DATABASE_URL"))["pass"], 'charset' => 'utf8', 'prefix' => '', 'schema' => 'public', ], احفظ التعديلات ثم تأكد من أن اتصال التطبيق بقاعدة البيانات (محليّا)؛ يمكنك إنشاء نموذج في Laravel وتهجير مرافق له لغرض اختبار الاتصال بقاعدة البيانات. نفذ بعد التأكد من إعداد قاعدة البيانات التعديلات التي أضفتها إلى منطقة الإدارج في Git ثم أودعها في المستودع وأرسلها إلى المستودع البعيد على الخادوم: $ git add . $ git commit -m "Updated database configuration" $ git push heroku master يمكنك الآن تنفيذ التهجير على قاعدة البيانات على الخادوم عن طريق Toolbelt كالتالي: $ heroku run php artisan migrate --app nameless-chamber-90421 Running `php artisan migrate` attached to terminal... up, run.6981 ************************************** * Application In Production! * ************************************** Do you really wish to run this command? [y/N] y Migration table created successfully. Migrated: 2014_10_12_000000_create_users_table Migrated: 2014_10_12_100000_create_password_resets_table Migrated: 2015_01_30_032004_create_todolists_table.php ترجمة -وبتصرّف- للمقال Deploying a Laravel Application to Heroku لصاحبه W. Jason Gilmore.

الأحداث Events هي إجراءات يمكن لبرنامج التعرّف عليها ومن ثمّ التعامل معها. يمكن أن نأخذ مثالا على ذاك عملية تسجيل مستخدم في الموقع. عندما يكمل زائر ملء حقول الاستمارة الخاصّة بالتسجيل في موقع فإنه يكون قد فعّل حدثا يمكننا تسميّته "التسجيل في الموقع"؛ نستطيع بعد ذلك التعامل مع هذا الحدث لنقرّر ما التالي. كانت الطريقة القديمة تقضي بكتابة شفرة برمجية مباشرةً في المتحكّم Controller للتعامل مع الحدث؛ إلا أن توسّع التطبيق وزيادة الحاجة للتعامل مع أحداث جديدة يجعل الحاجة أكبر لطريقة جديدة أنظف وأكثر قابلية للتمديد. يستجيب Laravel لهذه الحاجة بالصنف Event والأدوات المساعدة المتعلّقة به. لا تقتصر الأحداث على إرسال البريد؛ إلا أن هذا الأخير وسيلة سهلة لشرح المبدأ. سنرى في هذا الدرس الخطوات اللازمة لتعريف حدث واستخدامه. نفترض أن لدينا جدولا ببيانات الاتصال ببعض الأشخاص؛ ونريد أن نرسل لأحدهم بريدا في كل مرة يُعرَض فيها الرابط contacthandler/id/ حيث id معرّف من نرسل له البريد. سنستخدم في هذا الجدول نفس المشروع الذي أنشأناه في الدرس السابق ونزيد عليه بإنشاء نموذج Model وجدول بيانات لحفظ جهات الاتّصال. تهيئة المشروع لا تدخل الخطوات الواردة في هذا العنوان في صميم إدارة الأحداث في Laravel؛ إلا أننا سنحتاجها للحصول على نتيجة مرئية للمثال الذي نبنيه. سنمرّ على الخطوات دون الكثير من التفاصيل لورودها في دروس سابقة. إنشاء النموذج Contact ننفذ الأمر التالي في مجلّد المشروع لإنشاء نموذج باسم Contact مع ملف التهجير الخاصّ به: php artisan make:model Contact -m نعدّل ملف التهجيرعلى النحو التالي: public function up() { Schema::create('contacts', function (Blueprint $table) { $table->increments('id'); $table->string('name'); $table->string('email')->unique(); $table->string('subject'); $table->text('body'); $table->timestamps(); }); } أضفنا الحقول التي نريد استخدامها في جدول البيانات. ننفذ أمر التهجير لإنشاء الجدول: php artisan migrate بذر البيانات سنحتاج لبيانات اتصّال للتجربة عليها. نستخدم معمل نماذج Model factory لبذر الجدول contacts. ننشئ ملفا باسم ContactFactory.php في المسار /app/factories ونضيف إليه المحتوى التالي: <?php $factory->define(App\Contact::class, function (Faker\Generator $faker){ return [ 'name' => $faker->name, 'email' => $faker->unique()->safeEmail, 'subject' => $faker->word, 'body' => $faker->text ]; }); يستدعي معمل النماذج مكتبة Faker لإدراج بيانات في جدول contacts عبر النموذج Contact. ثم ننشئ صنفا للبذر: php artisan make:seeder ContactTableSeeder نستورد النموذج Contact في صنف البذر ContactTableSeeder ونستخدم معمل النماذج لتوليد بيانات عشوائية: <?php use Illuminate\Database\Seeder; use App\Contact; class ContactTableSeeder extends Seeder { public function run() { Contact::truncate(); factory(Contact::class, 50)->create(); } } نأتي الآن للخطوة الأخيرة قبل تنفيذ أمر البذر وهي تحرير الملف DataBaseSeeder.php ليستدعي الصّنف ContactTableSeeder في الدالة run: $this->call(ContactTableSeeder::class); ثم ننفذ البذر: php artisan db:seed المسار والمتحكم نفتح ملف routes.php لإضافة مسار للرابط contacthandler/id/: Route::get('/contacthandler/{id}', 'HomeController@contactHandler'); يحيل ملف المسارات الطلب على الرابط إلى الدالة contacthandler في المتحكّم HomeController. نذهب للمتحكم ونضيف هذه الدالة: public function contactHandler($id) { } نترك الدالة خاوية لحد الساعة. التعامل مع الأحداث جهزنا المشروع ويمكننا الآن الانتقال إلى الأحداث والتعامل معها. نذكّر بأننا نريد إرسال بريد لصاحب جهة الاتصال عند طلب رابط به معرّفه. مثلا نرسل بريدا إلى جهة الاتصال ذات المعرّف 6 عند زيارة يُعرَض فيها الرابط contacthandler/6/. نحصُل على البريد الإلكتروني الذي سنرسل إليه الرسالة من خلال النموذج Contact؛ إضافة لاسمه وموضوع الرسالة وفحواها. ولدنا هذه البيانات تلقائيا أثناء البذر السابق. تعريف الحدث يتلخّص الأمر في أننا سننفّذ إجراءً عند وقوع الحدث "زيارة رابط المعرّف الخاص بجهة الاتصال". سنسميّ الصنف الموافق للحدث بـ ContactHandlerAction. نستعين بأداة artisan لإنشاء الحدث على النحو التالي: php artisan make:event ContactHandlerAction ستجد أن الأداة أنشأت الملف ContactHandlerAction.php على المسار app/Events وأضافت إليه المحتوى التالي (بعد نزع التعليقات): class ContactHandlerAction extends Event { use SerializesModels; public function __construct() { } public function broadcastOn() { return []; } } سنضيف خاصيّة إلى الصّنف ليصبح كالتالي: class ContactHandlerAction extends Event { use SerializesModels; public $contact; public function __construct($contact) { $this->contact = $contact; } public function broadcastOn() { return []; } } أضفنا متغيّرا جديدا لحفظ بيانات الاتصال واستخدامها عند الحاجة. نعود لدالّة contactHandler في المتحكّم HomeController ونعدّلها لتصبح كما يلي: public function contactHandler($id) { $contact = Contact::find($id); event (new ContactHandlerAction($contact)); return view('mail.success_view'); } نحتاج لاستيراد الصنفين المستخدمين في الدالة (النموذج والحدث) إلى المتحكّم: use App\Contact; use App\Events\ContactHandlerAction; عند استدعاء الدالة contactHandler نأخذ المعطى id المُمرَّر في الرابط ونحيله إلى الدالة find في النموذج Contact من أجل العثور عليه في قاعدة البيانات. في التعليمة التالية يبدأ عمل آلية إدارة الأحداث في Laravel: نستدعي الدالة المساعدة event ونمرّر لها كائنا من الحدث ContactHandlerAction الذي أنشأناه قبل قليل. نستخدم جهة الاتصال التي عثرنا عليها contact$ من أجل بناء الحدث. يعني هذا أننا أطلقنا الحدث “زيارة رابط المعرّف الخاص بجهة الاتصال” وزوّدناه بجهة الاتصال المعنيّة. مالذي يترتّب عن إطلاق الحدث؟ هذا هو ما سنراه الآن. التعامل مع الحدث توجد في Laravel ما تُعرَف بالمستمعات Listeners ومهمتها انتظار وقوع أحداث لتبدأ عملها. نعود لأداة artisan وننفّذ الأمر التالي: php artisan make:listener EmailContactListener --event="ContactHandlerAction" ينشئ الأمر صنفا باسم EmailContactListener للاستماع للأحداث ContactHandlerAction. يوجد الصّنف EmailContactListener في المجلّد /app/Listeners ومحتواه التالي: class EmailContactListener { public function __construct() { // } public function handle(ContactHandlerAction $event) { // } } لاحظ أن الدالة handle تنتظر معطى من نوع ContactHandlerAction. يشغّل المستمِع الدالة handle بعد تلقيه إخطارا بإطلاق الحدث ContactHandlerAction. سنعود بعد قليل للدالة handle بعد أن نعرّف الآلية التي سيُخطَر بها المستمِع بوقوع الحدث. ربط الحدث بآلية التعامل معه يوفّر Laravel مزوّد خدمة خاصًّا بالأحداث اسمه EventServiceProvider يوجد في المجلّد /app/Providers. إن فتحت الملف EventServiceProvider.php ستجد التالي (إن لم يسبق لأحد التعديل عليه): class EventServiceProvider extends ServiceProvider { protected $listen = [ 'App\Events\ContactHandlerAction' => [ 'App\Listeners\EmailContactListener', ], ]; public function boot(DispatcherContract $events) { parent::boot($events); // } } ما يهمّنا هنا هو الخاصيّة listen$. نعدّلها لتصبح على النحو التالي: protected $listen = [ 'App\Events\ContactHandlerAction' => [ 'App\Listeners\EmailContactListener', ], ]; يمكن تعريف أكثر من مستمِع لنفس الحدث (لاحظ أن قيمة App\Events\ContactHandlerAction في الخاصيّة هي مصفوفة Array). تمكننا الآن العودة إلى المنصِت بعد أن أعلمنا Laravel بالرابط بينه والحدث. تنفيذ آلية التعامل مع الحدث نعدّل الدالة handle لتصبح على النحو التالي: public function handle(ContactHandlerAction $event) { $data = [ 'name' => $event->contact->name, 'email' => $event->contact->email, 'subject' => $event->contact->subject, 'body' => $event->contact->body ]; Mail::send('mail.email_view',$data , function($message) use($data) { $message->from('hsoub@academy.com', 'Hsoub Academy'); $message->to($data['email'])->subject($data['subject']); }); if (Mail::failures()){ throw new EmailSendingException; } } نعرّف مصفوفةً باسم data$ تحوي اسم جهة الاتصال، بريدها الإلكتروني، موضوع الرسالة وفحواها. نعثُر على هذه البيانات من الكائن contact الذي مررناه للحدث event عند زيارة الرابط. نستخدم هذه البيانات لجدولة إرسال بريد عبر الدالة Mail::send. تأخذ الدالة Mail::send عرضا View تستخدمه لتنسيق الرسالة والبيانات التي أخذناها من جهة الاتصال. ثم نختبر أخطاء إرسال البريد الإلكتروني بالدالة Mail::failures؛ فإن وجدت أخطاء استخدمنا استثناءً Exception مخصّصًا لمعالجتها. يمكنك الحصول على هذا الاستثناء في الملف المرفق أو مراجعة الدرس الخاص بالاستثناءات. نحن الآن جاهزون تقريبا لتجربة الأحداث والتعامل معها في Laravel. بقي لنا إنشاء بضعة عروض لحاجات تطبيقنا المختلفة: mail.success_view في المتحكّم، mail.email_view لتنسيق الرسالة، إضافة لعروض أخرى قد تحتاجها أثناء تخصيص الاستثناء. يمكنك الحصول عليها في الملف المرفق. بقيت لنا خطوة أخيرة قبل اختبار التطبيق: إعداد Laravel لإرسال البريد. يوفّر Laravel وسيلة لمحاكاة إرسال البريد يمكننا استخدامها للتجربة. ابحث في ملف متغيّرات النظام env. عن المعطى MAIL_DRIVER وعيّن قيمته بـlog: MAIL_DRIVER=log نطلُب بهذه الطريقة من Laravel كتابة البريد في ملفّ السجل بدلا من إرساله. هذه الطريقة مفيدة أثناء الاختبار. افتح الرابط التالي في المتصفّح (ضع اسم المضيف المناسب بدلا من laraveltips): http://laraveltips.dev/contacthandler/45 ملحوظة: لا يتعدّى عدد جهات الاتصال التي أضفناها الخمسين؛ سيؤدي البحث عن جهة اتصال بمعرّف أكبر من 50 إلى خطأ يمكنك التقاطه في استثناء كما فعلنا في درس استخدام الاستثناءات Exceptions المخصَّصة في Laravel. ثم اذهب إلى ملف السجل storage/logs/laravel.log للتأكد من نجاح معالجة الحدث؛ ستجد في آخر الملف ما يشبه التالي: [2016-03-30 22:16:29] local.DEBUG: Message-ID: <8c79163440df2d3b5bbb3efd97ad549f@laraveltips.dev> Date: Wed, 30 Mar 2016 22:16:29 +0000 Subject: distinctio From: Hsoub Academy <hsoub@academy.com> To: fFranecki@example.net MIME-Version: 1.0 Content-Type: text/html; charset=utf-8 Content-Transfer-Encoding: quoted-printable يليه محتوى العرض المستخدم لتنسيق الرسالة (mail.email_view في المثال). إن حدثت مشكلة في إرسال البريد فسيتولّى الاستثناء -إن أعددتَه - إظهار العرض المناسب للزائر؛ وفي حال سريان الأمور على الوجه الأمثل فسيُظهر المتحكّم العرض mail.success_view للدلالة على نجاح الإرسال. الملف المرفق: الأحداث في Laravel.zip ترجمة -وبتصرّف- للمقال Eventing in Laravel 5.1 لصاحبه Bill Keck.

رأينا في درس كيف تنشئ مزود خدمة Service provider في Laravel طريقة عمل مزوّدات الخدمة والآليّة التي تتيح بها مرونة أكبر في التعامل مع الأصناف في Laravel. سنرى في هذا الدّرس كيفيّة الاستفادة من تعليمة inject@ لإعادة استخدام مزوّد خدمة في قالب Blade. استخدمنا في الدرس السابق مزوّد خدمة داخل متحكّم على النحو التالي: public function index(RocketShipContract $rocketship) { $boom = $rocketship->blastOff(); return view('demo.index', compact('boom')); } سنفترض أن لدينا ثلاثة عروض view1 وview2 إضافة للعرض index (كلّها في نفس المجلّد): العرض view1: <!-- تعليمات خاصّة بالعرض view1 --> @include('demo.index') <!-- تعليمات خاصّة بالعرض view1 --> العرض view2: <!-- تعليمات خاصّة بالعرض view2 --> @include('demo.index') <!-- تعليمات خاصّة بالعرض view2 --> العرض index: @extends('layouts.master') @section('content') {{ $boom }} @endsection نلاحظ أن العرض index يُضمَّن في العرضيْن view1 وview2. سنفترض أيضا أن لدينا الدالتين التاليتين في المتحكّم: public function function1(RocketShipContract $rocketship) { $boom = $rocketship->blastOff(); return view('demo.view1', compact('boom')); } public function function2(RocketShipContract $rocketship) { $boom = $rocketship->blastOff(); return view('demo.view2', compact('boom')); } تعمل الطريقة أعلاه دون مشكل؛ ولكن ماذا لو أضفنا مسارا ثالثا يستدعي عرضا آخر يُضمِّن العرض index؟ إذا اتبعنا نفس الطريقة فسنضيف دالة جديدة إلى المتحكّم كالتالي: public function function3(RocketShipContract $rocketship) { $boom = $rocketship->blastOff(); return view('demo.view3', compact('boom')); } يمكن أن نلاحظ بوضوح وجود الكثير من التكرار لاستخدام الصّنف RocketShipContract. لتلافي هذا الوضع يعرّف Laravel حقن الخدمة Service injection. يقوم المبدأ على استخدام التعليمة inject@ التي تتيح استدعاء صنف مّا مباشرة في العرض. بتطبيق هذا المبدأ في الحالة أعلاه نعدّل العرض index ليصبح كالتالي: @inject('boom', 'App\Helpers\Contracts\RocketShipContract') @extends('layouts.master') @section('content') {{ $boom->blastOff() }} @endsection تأخذ التعليمة inject@ معطييْن؛ الأول (boom في المثال) اسم المتغيّر الذي سنحتفظ فيه بكائن من الصّنف الممرّر في المعطى الثاني (RocketShipContract). يمكننا بعد ذلك استخدام المتغيّر واستدعاء الدالة. بالعودة إلى دوال المتحكّم فيمكننا تغييرها كالتالي: public function function1() { return view('view1'); } public function function2() { return view('view2'); } نرى بوضوح أن الطريقة الأخيرة تتيح قابليّةً أكبر لإعادة الاستخدام. حقن الخدمة - كما رأينا - وسيلة مفيدة لإعادة استخدام وظائف من التطبيق وتقديمها في عروض، إلا أنه لا يُنصَح باستخدامها إلا عند الحاجة؛ ومن الضروريّ عدم المبالغة في استخدامها. ترجمة -وبتصرّف- للمقال How to Use @inject in Blade in Laravel 5.1 لصاحبه Bill Keck.

تعتمد بنية Laravel كثيرا على مزوّدي الخدمة Service providers لتحميل الأصناف Classes إلى الذاكرة مع بدء عمل التطبيق أو عند الحاجة إليها. يستخدم Laravel حاويةَ خدمة Service container لإدارة الاعتمادات بين الأصناف: ماهي الأصناف التي يعتمد عليها الصّنف الجديد للعمل؟ كيف يمكنه الحصول على كائن من هذه الأصناف؟ أين يوجد الصّنف وهل سبق لإطار العمل تحميلُه إلى الذاكرة؟ تمكننا بإعداد مزوّد خدمة وتعريفه إضافةُ صنف إلى حاويّة الخدمة ممّا يسهّل بالتالي استخدامه؛ إذ سيتعرّف إطار العمل على ما يحتاجه هذا الصّنف (أي الاعتمادات) وينشئه إن لم يكن موجودا سلفا. سنشرح في هذا الدرس أساسيّات إنشاء مزود خدمة في Laravel. نبدأ بإنشاء مسار سنستخدمه للتوضيح: Route::get('/demo', 'DemoController@index'); ثم ننشئ المتحكّم: php artisan make:controller DemoController ثم نعرّف الدالة index في المتحكّم: public function index() { return view('demo.index'); } تطلب الدالة index تقديم العرض demo.index؛ لذا سننشئ مجلّدا باسم demo في مجلّد العروض وننشئ فيه عرضا باسم index.blade.php. نضيف المحتوى التالي للعرض index: @extends('layouts.master') @section('content') <h1>Demo Page</h1> @endsection يمدّد العرض index عرضا رئيسا باسم master ضمن مجلّد العروض layouts. أنشئ العرض الرئيس إن احتجت لذلك. لم ندخل في صميم الموضوع لحد السّاعة، فقط ضبطنا بعض الإعدادات البدائية. تظهر عند الدخول إلى الرابط demo/ صفحة بها عنوان Demo Page. إعداد مزود خدمة سنشرح في الفقرات المواليّة كيفية إنشاء مزوّد خدمة. نبدأ بإنشاء مجلّد باسم Helpers في مجلّد app ثم ننشئ مجلّدا متفرعا عن Helpers باسم Contracts؛ بداخل الأخير ننشئ ملفّا باسم RocketShipContract.php نضيف إليه المحتوى التالي: <?php namespace App\Helpers\Contracts; Interface RocketShipContract { public function blastOff(); } لاحظ تعريف الصّنف أعلاه. عرّفنا RocketShipContract على أنه واجهة Interface. تعرّف الواجهات في PHP (ولغات برمجيّة أخرى) "عقدا" يجب على الأصناف التي تطبّق الواجهة اتّباعه. يجب على الأصناف التي تنفّذ Implement الواجهة المعرَّفة أعلاه أن تحوي دالة عمومية public باسم blastOff. نأتي الآن بعد تعريف الواجهة إلى الصّنف الذي ينفّذها. تحوي الواجهة خطوطا عريضة يأتي الصّنف المنفّذ لتخصيصها. ننشئ صنفا باسم RocketShip.php في مجلّد Helpers ونضيف إليه المحتوى التالي: <?php namespace app\Helpers; use App\Helpers\Contracts\RocketShipContract; class RocketShip implements RocketShipContract { public function blastOff() { return 'Houston, we have ignition'; } } يمكن أن تعالج في هذا الصّنف الكثير من الأمور، إلا أننا لا نودّ التعقيد. كل ما تفعله هذه الدالة هو إرجاع العبارة Houston, we have ignition. عرفنا الواجهة وكيفيةً لتنفيذها. يأتي الآن دور مزوّد الخدمة الذي سننشئه بالأمر التالي: php artisan make:provider RocketShipServiceProvider ينشئ الأمر ملفّا باسم RocketShipServiceProvider.php في المجلّد. تجد عند فتح الملف ما يلي (بعد نزع التعليقات): <?php namespace App\Providers; use Illuminate\Support\ServiceProvider; class RocketShipServiceProvider extends ServiceProvider { public function boot() { } public function register() { } } عدّل على الملف ليصبح على النحو التالي: <?php namespace App\Providers; use Illuminate\Support\ServiceProvider; use App\Helpers\RocketShip; class RocketShipServiceProvider extends ServiceProvider { protected $defer = true; public function boot() { } public function register() { $this->app->bind('App\Helpers\Contracts\RocketShipContract', function(){ return new RocketShip(); }); } public function provides() { return ['App\Helpers\Contracts\RocketShipContract']; } } أولى التعديلات هي استدعاء الصّنف RocketShip: use App\Helpers\RocketShip; ثم إضافة الخاصّية التاليّة: protected $defer = true; يعني تمكين الخاصيّة defer$ أننا نطلُب ألا يُحمَّل الصّنف إلا عند الضرورة؛ مما يسهِم في الرفع من أداء التطبيق. ثم يأتي دور الدالة register التي تربط بين الواجهة والصّنف الذي ينفّذها. public function register() { $this->app->bind('App\Helpers\Contracts\RocketShipContract', function(){ return new RocketShip(); }); } يتيح هذا الربط إمكانية استخدام الواجهة في أي مكان تريده وسيستخدم مزوّد الخدمة الصنف الذي تربطه بها في دالة register تلقائيا. يزيد هذا الإعداد من مرونة التطبيق؛ فكل ما عليك فعله لتغيير سلوك الواجهة هو تعديل الصّنف المربوط بها. التعديل الأخير هو إضافة الدالة provides التي تُرجع الواجهة. يجب تعريف هذه الدالة عند تمكين الخاصيّة defer. الخطوة الأخيرة من إعداد مزوّد الخدمة هي إضافته إلى ملف إعداد التطبيق config\app.php ضمن مصفوفة providers (أدرجنا بعضا من محتويات الملف في الشفرة أدناه، مزوّد الخدمة الخاص بنا هو الأخير): /* * Application Service Providers... */ App\Providers\AppServiceProvider::class, App\Providers\EventServiceProvider::class, App\Providers\RouteServiceProvider::class, App\Providers\RocketShipServiceProvider::class, استخدام مزود الخدمة نعود الآن للمتحكّم DemoController ونعدّل الدالة index كالتالي: public function index(RocketShipContract $rocketship) { $boom = $rocketship->blastOff(); return view('demo.index', compact('boom')); } لا تنس استيراد الواجهة: use App\Helpers\Contracts\RocketShipContract; نمرّر للدّالة index كائنا من الصنف RocketShipContract (أي الواجهة). سيعرف Laravel تلقائيا أننا نريد الصّنف RocketShip الذي ينفّذ الواجهة. يعود السبب في ذلك إلى الربط الموجود في مزوّد الخدمة. نمرّر النتيجة المتحصّل عليها من استدعاء blastOff إلى العرض لتقديمه. نعدّل العرض لاستخدام المتغيّر الذي ممرناه إليه: @extends('layouts.master') @section('content') {{ $boom }} @endsection تظهر العبارة التاليّة في المتصفّح عند زيارة الرابط demo/: Houston, we have ignition سننشئ لتوضيح المرونة التي تتيحها مزودات الخدمة صنفا آخر ينفّذ الواجهة RocketShipContract. سنسمّي هذا الصنف الجديد RocketLauncher ونضعه في نفس المجلد الذي يوجد به صنف التنفيذ السابق (Helpers): <?php namespace app\Helpers; use App\Helpers\Contracts\RocketShipContract; class RocketLauncher implements RocketShipContract { public function blastOff() { return 'Houston, we have launched!'; } } لم نغيّر الكثير بالمقارنة مع الصنف RocketShip السّابق؛ فقط العبارة. نعود إلى مزوّد الخدمة ونغيّر ربط الواجهة كالتالي: public function register() { $this->app->bind('App\Helpers\Contracts\RocketShipContract', function(){ return new RocketLauncher(); }); } دون أن ننسى استدعاء الصّنف: use App\Helpers\RocketLauncher; ستلاحظ الآن تغير العبارة الظاهرة في المتصفّح عند زيارة الرابط demo/. لم نفعل أمورا معقّدة في الخطوات السّابقة إلا أن بالإمكان رؤية أن التعامل مع الواجهات مباشرة وترك التنفيذ الفعلي للأصناف المربوطة عبر مزوّد الخدمة يضيف الكثير من المرونة إلى بنية التطبيق. يوجد أمران ينبغي الانتباه إليهما عند التعامل مع مزوّدات الخدمة في Laravel: اجعل إضافة مزوّد الخدمة إلى ملف الإعداد config/app.php هي آخر الخطوات؛ بعد تعريف الواجهة ومزوّد الخدمة. إضافة صنف غير موجود إلى ملف الإعداد تؤدي إلى التشويش على عمل artisan. من الأفضل حذف مزوّد الخدمة ثم إنشاء واحد جديد بأداة artisan؛ بدلا من إعادة تسميّته. قد تؤدي إعادة التسميّة إلى عدم تحميل مزوّد الخدمة فلا يتعرّف عليه التطبيق. ترجمة -وبتصرّف- للمقال How to Create a Service Provider in Laravel 5.1 لصاحبه Bill Keck.

يكثُر استخدام المخططات البيانيّة في مواقع الويب لتقريب المعلومة للزّائر. سنرى في هذا الدرس كيفية إنشاء مخطّطات بيانية في تطبيق Laravel باستخدام مكتبة Morris.js. سنفترض أن لديك مشروع Laravel معدًّا وجاهزًا للعمل، وقاعدة بيانات مضبوطة. تتلخّص خطوات هذا الدرس في ما يلي: إنشاء نموذج Model للتطبيق إضافة للتهجيرات Migrations المرتبطة به. إنشاء متحكّمات Controllers وعروض Views لإظهار البيانات للزائر. إنشاء معمل نماذج Model Factory لإضافة بيانات إلى قاعدة البيانات من أجل عرضها على هيئة مخططات بيانية. استخدام Mirror.js لتنسيق البيانات وعرضها في مخطّطات. النموذج نبدأ بإنشاء نموذج نُسمّيه Widget؛ نستخدم الخيار m- لإنشاء تهجير في نفس الوقت: php artisan make:model Widget -m نفتح ملف التهجير ونعدّله ليصبح على النحو التالي: class Widget extends Model { // protected $fillable = ['widget_name']; public $timestamps = false; } أعطينا القيمة false للمتغيّر timestamps$ حتى لا يُملأ الحقلان created_at وupdated_at تلقائيا في جدول البيانات. سنتستخدم معمل النماذج في ما بعد لملْء هذين الحقلين. ننتقل لملف التهجير ونضيف حقلا جديدا باسم widget_name إلى الجدول في قاعدة البيانات؛ تصبح الدالة up على النحو التالي: public function up() { Schema::create('widgets', function (Blueprint $table) { $table->increments('id'); $table->string('widget_name')->unique(); $table->timestamps(); }); } انتهينا الآن من العمل على النموذج والتهجير. يمكنك مراجعة مقال كيف تنشئ نموذجا Model في Laravel للمزيد. نفذ التهجير بالأمر التالي في مجلد المشروع: php artisan migrate تهيئة التطبيق سنحتاج لمسارات للوصول إلى صفحات الموقع، عروض لإظهار البيانات، ومتحكمات للربط بين المسارات، النماذج والعروض. سنستخدم الأمر التالي الذي يُنشئ نموذجا للمستخدمين مع مسارات وعروض جاهزة لتسجيل المستخدمين في قاعدة البيانات وللولوج إلى التطبيق: php artisan make:auth نفتح ملفّ العرض app.blade.php الموجود في المجلّد resources/views/layouts لتحريره. هذا هو المخطّط الرئيس لعروض Blade الذي أنشأه الأمر السابق. ابحث عن التعليق التالي: <!-- Left Side Of Navbar --> والذي توجد أسفله العناصر اليسرى من القائمة العلوية. سنضيف رابطين جديدين إلى القائمة، الأول للائحة بجميع التسجيلات الموجودة في الجدول widgets (كما فعلنا في درس استخدام الاستثناءات Exceptions المخصَّصة في Laravel) والثاني لصفحة المخطَّط البياني: <li><a href="{{ url('/widgets') }}">Widgets</a></li> <li><a href="{{ url('/charts') }}">Chart</a></li> المسارات أضفنا أعلاه رابطين؛ إلا أن المسارات التي تتولى الإجابة عنهما غير موجودة حتى الآن. نفتح ملف routes.php الموجود على المسار app\Http لإضافتها: Route::group(['middleware' => 'web'], function () { Route::auth(); Route::get('/charts', 'HomeController@charts'); }); Route::group(['middleware' => 'web'], function () { Route::auth(); Route::get('/widgets', 'HomeController@widgets_list'); }); Route::group(['middleware' => 'web'], function () { Route::auth(); Route::get('/widget/{id}', 'HomeController@widget_detail'); }); جعلنا المسارات محمية لكي يصل إليها المستخدمون المسجّلون فقط. الجديد هنا (مقارنة مع درس الاستثناءات المخصّصة المُشار إليه أعلاه) هو إضافة المسار charts/ الذي تتولى دالة charts في المتحكّم HomeController الإجابة عنه. بالنسبة للمسارين الآخرين فأحدهما (widgets/) يعرض أسماء جميع التسجيلات في الجدول widgets والآخر ({widget/{id/) يعرض اسم التسجيلة ذات المعرّف id. المتحكم يوجد لدينا متحكّم واحد ناتج عن تطبيق أمر artisan الأخير. هذا المتحكّم هو HomeController. نفتح ملف المتحكّم HomeController.php الموجود على المسار app/Http/Controllers لتحريره. نضيف الدوال المذكورة في ملف المسارات السابق: public function widgets_list() { $widgets = Widget::Paginate(10); return view('widgets.widgets',array('widgets' => $widgets)); } public function widget_detail($id) { $widget = Widget::find($id); return view('widgets.widget_detail', array('widget_name' => $widget->widget_name)); } public function charts() { $yearCounts = Widget::select(DB::raw('year(created_at) as year'), DB::raw('count(widget_name) as `count`')) ->groupBy('year')->get(); $chartData = (sizeof($yearCounts) > ) ? $yearCounts : null; if ($chartData) { return view('widgets.widgets_chart',array('chartData' => $chartData)); } else { return view('widgets.nowidgets'); } } تبحث الدالة widgets_list عن محتويات الجدول widgets باستخدام دوال النموذج Widget. لاحظ أننا نريد تقسيم النتائج إلى صفحات بحيث تحوي كل صفحة عشرة نتائج، لذا استدعينا الدالة Paginate في الصّنف (النموذج) Widget. نُرسل ما عثرنا عليه إلى العرض widgets الموجود في مجلّد widgets ضمن مجلد العروض resources/views. في الدالة widget_detail نبحث عن التسجيلة ذات المعرّف id ونظهرها في العرض widget_detail ضمن مجلد widgets السابق. نأتي الآن للدالة charts التي تهيّئ البيانات لعرضها على هيئة مخطط بياني. نريد أن نعثُر على عدد التسجيلات المدرجة في جدول قاعدة البيانات مجموعة حسب السنة؛ على النحو التالي مثلا: year-|--count 2016 | 16 2015 | 12 2014 | 15 2013 | 11 يمكّننا استعلام SQL التالي من الحصول على ما نريد: SELECT COUNT(widget_name) AS count, YEAR(created_at) AS year FROM widgets GROUP BY year; يمكن أن ننفّذ هذا الاستعلام باستخدام الواجهة DB كالتالي: DB::select('SELECT COUNT(widget_name) AS count, YEAR(created_at) AS year FROM widgets GROUP BY year;'); أو على النحو التالي: Widget::select(DB::raw('year(created_at) as year'), DB::raw('count(widget_name) as `count`')) ->groupBy('year')->get(); نحصُل في كلتا الحالتين على مصفوفة Array من عمودين بناتج تنفيذ الاستعلام. راجع مقال استخدام Eloquent ORM للتعامل مع قاعدة البيانات في Laravel 5 حول الموضوع. لا تنس استيراد النموذج Widget والواجهة DB قبل استخدامهما في المتحكّم: use App\Widget; use DB; نفحص المصفوفة المتحصَّل عليها؛ في حال وجود نتائج نرسلها إلى العرض widgets_chart ضمن المجلد resources/views/widgets؛ وإلا نظهر العرض nowidgets الموجود في نفس المجلّد. سنؤخّر الحديث عن العروض إلى أن ننشئ معمل نماذج لملْء جدول قاعدة البيانات. معمل النماذج وبذر قاعدة البيانات تحدثنا في درس عن استخدام معمل النماذج Model factory لتوليد بيانات الاختبار، سنعمل بنفس المبدأ هنا. ننشئ ملفا باسم WidgetFactory.php على المسار database/factories ونضيف إليه المحتوى التالي: <?php $factory->define(App\Widget::class, function (Faker\Generator $faker){ return [ 'widget_name' => $faker->unique()->word, 'created_at' => $faker->dateTimeBetween($startDate = '-4 years', $endDate = 'now') ]; }); تنشئ الشفرة السابقة تسجيلا في جدول البيانات widgets بتوليد محتويات الحقلين widget_name وcreated_at. لاحظ أننا نستخدم مكتبة Faker. حدّدنا تاريخ created_at بالمجال من قبل أربع سنوات إلى الآن. يأتي الآن دور بذر البيانات. ننشئ صنفا لبذر الجدول widgets: php artisan make:seeder WidgetTableSeeder نفتح الملف database/seeds/WidgetTableSeeder.php ونحرّر الدالة run ليصبح كالتالي: public function run() { Widget::truncate(); factory(Widget::class, 50)->create(); } نحذف محتوى الجدول لكي لا يحصُل تعارض مع البيانات الجديدة التي سنولّدها؛ ثم نستخدم معمل النماذج لإدراج 50 تسجيلة. لا تنس استيراد النموذج Widget: use App\Widget; يمكننا الآن تنفيذ الأمر التالي لبذر البيانات في الجدول: php artisan db:seed --class=WidgetTableSeeder توجد طريقة أخرى هي التي سنستخدمها. نحرّر الملف DataBaseSeeder.php الموجود على نفس مسار WidgetTableSeeder.php ونضيف ما يلي إلى الدالة run: Widget::unguard(); $this->call(WidgetTableSeeder::class); Widget::reguard(); نطلُب نزع الحماية عن الجدول قبل بذره ثم نعيدها إليه. يؤدي النداء call مهمّة البذر. يتيح الملف DataBaseSeeder إمكانية تنفيذ أصناف بذر عدّة بنفس الأمر التالي: php artisan db:seed بقيت الخطوة الأخيرة وهي إنشاء العروض. العروض نأتي الآن للعروض التي ورد ذكرها في المتحكّم دون أن تكون أنشئت. ستجد العروض في الملف المرفق. نشير إلى استخدام التعليمة التاليّة في العرض widgets: {!! $widgets->render() !!} تظهر هذه التعليمة روابط للتنقل بين التسجيلات إذا كان عددها يفوق العشرة. هذا ناتج عن استخدامنا للدالة Paginate في المتحكم أعلاه. نأتي الآن لشرح العرض widgets_chart الذي يتضمن المخطّط البياني الذي نهدف لإنشائه في هذا الدرس. @extends('layouts.app') @section('content') <div class="container"> <div class="row"> <div class="col-md-10 col-md-offset-1"> <div class="panel panel-default"> <div class="panel-heading">Chart</div> <div class="panel-body"> <div id="chart" style="height: 250px;"> </div> </div> </div> </div> </div> </div> <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/morris.js/0.5.1/morris.css"> <script src="//ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script> <script src="//cdnjs.cloudflare.com/ajax/libs/raphael/2.1.0/raphael-min.js"></script> <script src="//cdnjs.cloudflare.com/ajax/libs/morris.js/0.5.1/morris.min.js"></script> <script> var data = <?php echo json_encode($chartData) ?>; Morris.Line({ element: 'chart', data: data, xkey: 'year', ykeys: ['count'], labels: ['widgets created'] }); </script> @endsection يمدّد العرضُ العرض الرئيس layouts.app ويعرّف محتوى المقطع content. يوجد في هذا المقطع العنصُر التالي ذي المعرّف chart: <div id="chart" style="height: 250px;"> </div> سيُعرَض المخطّط البياني في هذا العنصُر. تأتي بعد ذلك اعتماديات مكتبة Morris: <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/morris.js/0.5.1/morris.css"> <script src="//ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script> <script src="//cdnjs.cloudflare.com/ajax/libs/raphael/2.1.0/raphael-min.js"></script> <script src="//cdnjs.cloudflare.com/ajax/libs/morris.js/0.5.1/morris.min.js"></script> وأخيرا السكربت الذي سيرسُم المخطّط: <script> var data = <?php echo json_encode($chartData) ?>; Morris.Line({ element: 'chart', data: data, xkey: 'year', ykeys: ['count'], labels: ['widgets created'] }); </script> يستقبل السكربت البيانات التي أرسلتها الدالة charts المعرّفة في المتحكم HomeController ويحوّلها إلى صيغة JSON التي تستخدمها مكتبة Morris: var data = <?php echo json_encode($chartData) ?>; ثم نستدعي الدالة Line في مكتبة Morris: Morris.Line({ element: 'chart', data: data, xkey: 'year', ykeys: ['count'], labels: ['widgets created'] }); نمرّر للدالة معرّف العنصُر الذي سنرسم في المخطّط (المعطى element)، البيانات التي نودّ رسمها (data)، عنصُر المصفوفة الذي سيكون في المحور الأفقي للمخطّط (xkey) والعنصُر-أ و العناصر- الذي سيكون على المحور العمودي (ykeys)؛ إضافة للصيقة Label تظهر في المخطّط. نذهب الآن لرابط المشروع؛ بالنسبة لي الرابط هو: http://laraveltips.dev نسجّل مستخدما جديدا (register) ثم نضغط على الرابط Chart لنجد النتيجة التالية (قد يختلف المخطّط البياني عن الموجود في الصورة بسسب أن البيانات مولَّدة عشوائيا). الملف المرفق: laravelchart.zip ترجمة -وبتصرّف- للمقال Charts in Laravel 5.1 with Morris.js لصاحبه Bill Keck.

لم تعد الصور الرمزيّة لحسابات المستخدمين أمرًا جديدًا ويندر أن تجد برنامجًا لا يسمح لمستخدميه بعرض صورة للمستخدم في صفحته الشّخصية مثلًا أو نحو ذلك، وقد ظهرت من عدّة سنوات فكرة أن يكون للمستخدم صورة رمزية يمكنه استخدامها في الكثير من المواقع والخدمات دون أن يحتاج في كلّ مرّة إلى اختيارها ورفعها، وهذا ما تمّ فعلًا في مشروع أطلق عليه اسم Gravatar اختصارًا للصورة الرمزيّة المتعارف عليها عالميًّا Globally Recognized Avatar. إنّ إضافة صورة Gravatar إلى شريط التصفّح في مشروع مبني بـ Laravel من أكثر الأعمال سهولة فلا تتطلب العملية أكثر من 4 خطوات بسيطة، ويعود الفضل في هذا إلى فريق CreativeOrange، الذين يمكن زيارة صفحة مشروعهم لقراءة الإرشادات الأصليّة، فيما إذا طرأت تغييرات ما. الخطوة الأولى لنقم بتحميل نسخة من الحزمة المطلوبة باستخدام Composer عبر سطر الأوامر: composer require creativeorange/gravatar ~1.0 أو من الممكن التعديل على ملف composer.json وإضافة اسم الحزمة والإصدار المطلوب إلى لائحة الحزم المطلوبة: "require": { "creativeorange/gravatar": "~1.0" } وفي حال تعديل الملف، فيتوجّب علينا أن نقوم بتنفيذ الأمر التّالي من سطر الأوامر ليتمّ تحديث المشروع وتحميل الحزمة: composer update الخطوة الثانية نحتاج الآن لإضافة مزوّد خدمة Service Provider إلى ملف app/config/app.php في مصفوفة providers بالشّكل: 'providers' => [ // Other Service Providers // ... App\Providers\AppServiceProvider::class, // ... // Other Service Providers ], ملاحظة: لا تنس الفاصلة في نهاية السطر إن لم تدرج السطر في نهاية المصفوفة. نلاحظ فيما سبق بأننا استخدمنا الصيغة الخاصة بـ PHP 5.6 وهي الصيغة القياسية لمصفوفة providers في الإصدار 5.* من Laravel. الخطوة الثالثة لنقم الآن بإضافة إختصار في مصفوفة aliases في ملف app.php ذاته: 'aliases' => [ // ... 'Gravatar' => Creativeorange\Gravatar\Facades\Gravatar::class, // ... ], نلاحظ بأن كلّ ما احتجنا لإضافته في الخطوتين السابقتين هو سطر واحد فقط، وهذا من الأمور المميّزة في معمارية Laravel، حيث أنّ حزّم Service Providers كأحجار البناء في التطبيق البرمجيّ ويمكن ملاحظة مدى سهولة استخدامها في البرنامج، فلا يتطلّب الأمر أكثر من سطرين. أصبح الآن بالإمكان استخدام الصفّ Gravatar في البرنامج بسهولة من خلال الواجهة التي حصلنا عليّها، الأمر الذي يمكن القيام به على النحو التالي: use Gravatar; لكن لن نحتاج لاستخدامه بهذا الشكل في مثالنا. الخطوة الرابعة من المحتمل أن الاستخدام الأسهل للإضافة Gravatar يكون عبر إدراجها مباشرة في عرض View، كالصّفحة الرّئيسية كأن تكون عنصر قائمة في شريط التصفّح الرئيسي العلويّ. سنحتاج بداية للتحقّق فيما إذا قد تمّ تسجيل الدخول أولًا أم لا، ويمكن ذلك باستخدام ()Auth::check المتاحة للاستخدام دومًا عند الحاجة لها، كما في الشّكل: @if (Auth::check()) // أظهر العنصر @endif تستخدم الشّيفرة السابقة الصّيغة القياسية لنظام القوالب Blade والذي نحتاج لمعرفة استخدامه عند اختيار إطار العمل Laravel، وتسمح صيغة blade بالمزج ما بين شيفرات HTML و PHP بسهولة عند الاستخدام، دون الحاجة لاستخدام وسوم البدء الخاصّة بـ PHP، من خلال إدراج التعليمات ما بين الأقواس {{ .. }} كما يظهر في الكود البرمجيّ التالي: @if (Auth::check()) <li> <img src="{{ Gravatar::get(Auth::user()->email) }}" style="height:50px; width:50px; border-radius:50%;"> </li> @endif والآن لنأخذ الجزء الأهمّ ما بين الأقواس ولنقم بتوضيحه: Gravatar::get(Auth::user()->email) يؤدّي استدعاء التابع ()get من الصنفّ Gravatar إلى إعادة مسار نصيّ بصيغة URL لصورة gravatar بعد أن نقوم بتزويده ببريد إلكترونيّ، ونظرًا لأنّا نرغب بعرض صورة حساب المستخدم النشط في البرنامج فإنّ بالإمكان الحصول على البريد الإلكتروني للحساب من الكائن object الذي يعيده استدعاء التابع ()Auth::user الذي يحمل معلومات عن المستخدم صاحب جلسة العمل النشطة. قد لا يكون قياس الصّورة التي نحصل عليها مناسبًا لنا، ولحلّ هذه المشكلة يمكن تغيير القياس الافتراضيّ المطلوب من خلال تعديل قيمة المتغيّر size في المصفوفة default في الملف vendor/creativeorange/gravatar/config/gravatar.php: 'default' => array( 'size' => 80, 'fallback' => 'mm', 'secure' => false, 'maximumRating' => 'g', 'forceDefault' => false, 'forceExtension' => 'jpg', ), وهناك العديد من القيم الافتراضية التي يمكن تغييرها لتتناسب مع احتياجاتنا في هذا الملف، كالصّورة الافتراضيّة التي يتم عرضها في حال لم يكن للمستخدم صورة Gravatar، أو طلب الصورة بصيغة مختلفة عن JPG، وغير ذلك. ترجمة -وبتصرّف- للمقال Laravel 5.1 Gravatar Plugin لصاحبه Bill Keck.

يستخدم Laravel الصنف Handler الموجود على المسار app/Exceptions للتعامل مع جميع الاستثناءات. يحوي هذا الصّنف دالتين: report وrender. تُستخدَم دالة report لتسجيل الاستثناءات أو إرسالها إلى خدمة خارجية؛ أما الدالة render فتُستخدَم لاعتراض الاستثناءات وإرسال إجابة مناسبة إلى المتصفّح ليعرضها للزّائر. ملحوظة: اعتمدنا العروض، المسارات والمتحكّم الذي أنشأناه في درس كيف تستخدم PHPUnit لاختبار تطبيقات Laravel وبنينا عليها لتطبيق الخطوات الواردة هنا. يمكنك تجربة الدّرس على مشروعك الخاص أو استخدام الملفّ المرفَق الذي يمثّل الحصيلة النهائية لهذا الدرس. إن استخدمت الملفّ المرفق فستحتاج لتسجيل مستخدم أولا عبر رابط register والدخول إلى الموقع حتى يظهر بقية المحتوى (سنترك لك اكتشاف الآلية المستخدمة في ذلك. كلمة السّر: المسارات المحميّة). تخصيص رسائل الاستثناءات يُعدّ ErrorException أحد أكثر الاستثناءات انتشارا ويظهر مثلا عند إضافة معرف كائن غير موجود إلى مسار URL، أو عند طلب خاصيّة غير موجودة في الكائن. عند محاولة دخول المسار التالي دون أن تكون التسجيلة ذات المعرّف 56 موجودة في جدول البيانات widgets: laravel.dev/widget/56 فستظهر في المتصفّح صفحة خطأ كالتالي: صفحة الخطأ هذه مفيدة للمطوّرين إلا أننا لا نرغب في أن يراها زوار الموقع؛ لذا يجب علينا التعامل مع هذا الاستثناء وقت حدوثه وعرض رسالة مغايرة للزائر. نعدّل دالة render في ملف Handler.php لتصبِح على النحو التالي: public function render($request, Exception $e) { switch($e){ case ($e instanceof ErrorException): return $this->ErrorException($e); break default: return parent::render($request, $e); } } ثم نضيف الدالة التالية إلى الملف: protected function renderErrorException($e) { return response()->view('errors.404', [], 404);/* } يمكنك أن تلاحظ أننا أضفنا عبارة switch إلى الدالة من أجل تحديد نوعيّة الاستثناء فإن كان من نوع ErrorException استدعينا الدالة renderErrorException وإلا نترك الدالة المبدئية تتكفّل بالموضوع. استخدمنا عبارة switch هنا لتسهيل إضافة معالَجات خاصّة في ما بعد لأنواع أخرى من الاستثناءات. نستخدم في الدالة renderErrorException عرضا خاصّا سميناه 404. يحوي مجلد العروض في Laravel مجلّدا خاصّا لعروض الأخطاء errors؛ ننشئ فيه العرض 404 ذي المحتوى التالي مع إضافة اللاحقة blade.php.: @extends('layouts.app') @section('content') <div class="alert alert-danger alert-dismissible alert-important" role="alert"> <button type="button" class="close" data-dismiss="alert" aria-label="Close"><span aria-hidden="true">×</span></button> <strong>Oh Snap!</strong> We can't find what you are looking for... </div> @endsection بقي لنا استيراد صنف الاستثناءات ErrorException في ملف Handler.php: use ErrorException; هذا كل ما نحتاجه. نعود الآن لنرى الرابط السابق: laravel.dev/widget/56 إن لم يكن الكائن ذو المعرّف موجودا فستظهر رسالة الخطأ التالية: تخصيص الاستثناءات استخدمنا في الفقرة السابقة استثناءً موجودا وخصّصنا النتيجة التي يعرضها للزائر. نريد في هذه الفقرة إنشاء استثناء مخصَّص لتلبية حاجة خاصّة بمشروعنا. سنفرض مثلا أننا نريد إظهار رسالة خطأ للزائر عند تصفّح الرابط /create/widget/، سنسمّي الاستثناء الجديد WidgetCreateException. نبدأ بإنشاء ملف WidgetCreateException.php في المجلّد Exceptions: <?php namespace App\Exceptions; class WidgetCreateException extends \Exception { } لاحظ مساحة الأسماء Namespace. لا نريد أن نعقّد الأمور، لذا سنترك الصّنف على ماهو عليه دون إضافة معالجات خاصّة، حتى نفهم المبدأ. نعود للملف Handler.php ونعدّله باستيراد الصّنف الذي أنشأناه للتّو: use App\Exceptions\WidgetCreateException; ثم نعدّل دالّة render كالتالي: public function render($request, Exception $e) { switch($e) { case ($e instanceof ErrorException): return $this->renderErrorException($e); break; case ($e instanceof WidgetCreateException): return $this->renderWidgetCreateException($e); break; default: return parent::render($request, $e); } } ونضيف أيضا الدالة التالية: protected function renderWidgetCreateException($e) { return response()->view('errors.widgetcreate', [], 404); } يعني هذا أنه في حالة ظهور استثناء من نوع WidgetCreateException فسنستدعي الدالة renderWidgetCreateException التي تُظهر العرض widgetcreate. بقي لنا الآن إنشاء ملف العرض widgetcreate.blade.php في المجلّد errors التابع لمجلد العروض: @extends('layouts.app') @section('content') <div class="alert alert-danger alert-dismissible alert-important" role="alert"> <button type="button" class="close" data-dismiss="alert" aria-label="Close"><span aria-hidden="true">×</span></button> <strong>Yes!</strong> You threw a Widget Creation Exception... </div> @endsection سننشئ لتجربة صنف الاستثناء الجديد داالةً في المتحكّم المناسب (HomeController في حالتي) كما يلي: public function create() { throw new WidgetCreateException; } لا تنس استيراد الصنف WidgetCreateException في المتحكم: use App\Exceptions\WidgetCreateException; وإضافة مسار لـ/create/widget في ملف routes.php: Route::group(['middleware' => 'web'], function () { Route::auth(); Route::get('/create/widget', 'HomeController@create'); }); نجرّب عمل الاستثناء بزيارة المسار التالي: http://laranew.dev/create/widget لاحظ النتيجة: قدّمنا في هذا المقال أساسيات تخصيص الاستثناءات في Laravel؛ ما زال يوجد الكثير لتعلمّه في هذا الإطار انطلاقا من هذه الأساسيات. حمل الملف المرفق لهذا الدرس. ترجمة -وبتصرّف- للمقال Handling Exceptions and Custom Exceptions in Laravel 5.1 لصاحبه Bill Keck.