البرمجة: اطار العمل لارافيل Laravelhttps://academy.hsoub.com/programming/php/laravel/page/2/?d=2البرمجة: اطار العمل لارافيل Laravelarرفع الملفّات وإدارتها في تطبيقات Laravelhttps://academy.hsoub.com/programming/php/laravel/%D8%B1%D9%81%D8%B9-%D8%A7%D9%84%D9%85%D9%84%D9%81%D9%91%D8%A7%D8%AA-%D9%88%D8%A5%D8%AF%D8%A7%D8%B1%D8%AA%D9%87%D8%A7-%D9%81%D9%8A-%D8%AA%D8%B7%D8%A8%D9%8A%D9%82%D8%A7%D8%AA-laravel-r392/

يتوفّر إطار العمل Laravel على واجهة تطبيقات برمجيّة API موّحّدة للتعامل مع الملفات. تأتي واجهة التطبيقات هذه مجهّزة مبدئيا بتعريفات Drivers تمكّن من إدارة الملفات على نظام الملفات المحلّي، خادوم FTP أو على خدمتي Amazon S3 وRackspace السّحابيتين. سنعرض في هذا الدرس لأساسيّات إدارة الملفات: رفعها Upload، تخزينها والعثور عليها في الإصدار 5.3 من إطار العمل Laravel.

laravel3.png

أقراص التخزين في Laravel

تُضبَط إعدادات تخزين الملفات ضمن الملف config/filesystems.php عن طريق ما يُسمّيه Laravel الأقراص Disks. يُمثّل كل قرص تعريفا، مسارا للتخزين وإعدادات خاصّة بالقرص. يعرّف ملفّ الإعداد مبدئيا ثلاثة أقراص public، local وs3: 

'disks' => [

    'local' => [
        'driver' => 'local',
        'root' => storage_path('app'),
    ],

    'public' => [
        'driver' => 'local',
        'root' => storage_path('app/public'),
        'visibility' => 'public',
    ],

    's3' => [
        'driver' => 's3',
        'key' => 'your-key',
        'secret' => 'your-secret',
        'region' => 'your-region',
        'bucket' => 'your-bucket',
    ],

],

يستخدم القرصُ local في المثال المبدئي أعلاه التعريفَ local (نظام الملفات المحلّي) ومسار التخزين storage/app. بالنسبة للقرص s3 فهو يستخدم التعريف s3 (خدمة Amazon S3) ويتطلّب قيما ضرورية للولوج إلى الخدمة.
يشبه القرص public القرصَ local؛ إلا أنّ بينهما فرقًا جوهريًّا: هذا القرص مهيّأ للملفات التي نريد إتاحتها للعموم. تُخزَّن ملفات هذا القرص على المسار storage/app/public. يمكن ملاحظة أن المسار storage/app/public يوجد خارج المجلّد public الذي يحوي ملفّات المشروع المتاحة للعموم. نستخدم أمر Artisan التالي لجعل ملفات القرص public متاحة على الوِب: 

 
php artisan storage:link

ينشئ الأمر وصلة رمزيّة على المسار public/storage ويجعلها تحيل إلىstorage/app/public الذي هو مسار تخزين القرص public. سنرى بعد قليل كيف نصل إلى الملفات الموجودة في هذا القرص.

ملحوظة: يتطلّب استخدام التعريفيْن s3 وrackspace تثبيت الحزمتييْن التاليّتيْن على التوالي (عن طريق composer): 

league/flysystem-aws-s3-v3 ~1.0
league/flysystem-rackspace ~1.0

رفع ملفات وعرض روابطها في Laravel 5.3

سنهيّئ في بقيّة الدرس مشروع Laravel 5.3 للعمل عليه. سيكون هدفنا رفع صورة في المتصفّح ثم عرض هذه الصورة في صفحة الوِب.
نضيف مسارين إلى ملف مسارات الوِب routes/web.php: 

Route::get('image-upload','ImageController@imageUpload');
Route::post('image-upload','ImageController@imageUploadPost');

يتلقّى الإجراء get طلبات عرض الصفحة، في ما نستخدم الإجراء post لتخزين الصّورة المحمَّلة في الصفحة التي سننشئها بعد قليل.

الخطوة التاليّة هي إنشاء المتحكّم ImageController وكتابة الدالتين imageUpload وimageUploadPost: 

 
php artisan make:controller ImageController

كلّ ما تفعله الدالة imageUpload هو استدعاء العرض image-upload: 

public function imageUpload()
{
    return view('image-upload');
}

بالنسبة للدالة imageUploadPost فستستقبل الصورة المحمّلة من المتصفّح، تخزّنها ثم ترسلها إلى image-upload الذي يعرضها: 

public function imageUploadPost(Request $request)
{
  // TODO:
  return view('image-upload')
          ->with('message', "Image uploaded successfully")
          ->with('path', $imagePath);
}

الدالة غير مكتملة لحد الساعة، فكل ما يظهر منها هو استدعاء القالب وتمرير رسالة إليه تفيد بنجاح رفع الصورة، إضافة إلى متغيّر يمثّل رابط الصورة. استقبال الصورة، تخزينها والحصول على رابط تخزينها سيكون محلّ التعليق TODO.
ننشئ القالب image-upload قبل العودة إلى الدالة imageUploadPost.

ننشئ الملف image-upload.blade.php على المسار resources/views ونضع فيه المحتوى التالي: 

<!DOCTYPE html>
<html>
<head>
        <title>Laravel 5.3 Image Upload example</title>
</head>
<body>
<div>
    @if (isset($path))
        <p>{{ $message }}</p>
        <img src="{{ url($path) }}">
    @endif

    <form action="{{ url('image-upload') }}" enctype="multipart/form-data" method="POST">
            {{ csrf_field() }}
            <div>
                    <div>
                            <input type="file" name="image" />
                    </div>
                    <div>
                            <button type="submit">Upload</button>
                    </div>
            </div>
    </form>
</div>
</body>
</html>

نتحقّق أولا، عن طريق الدالة isset، من وجود متغيّر باسم path في المعطيات الممرّرة إلى القالب. يمثّل المتغيّر path مسار الصورة التي نعرضها في حال وجود المتغيّر path. ثم يأتي دور استمارة الرّفع التي ترسل طلبا بإجراء POST إلى المسار image-upload. نحدّد نوع المُدخَل input الذي نريد استقبال الصورة عن طريقه بالنوع file ونحدّد اسمه بـimage.

نستطيع الآن العودة إلى الدالة imageUploadPost لإكمالها: 

public function imageUploadPost(Request $request)
{
  // TODO:
  return view('image-upload')
          ->with('message', "Image uploaded successfully")
          ->with('path', $imagePath);
}

نستقبل الطلب في المعطى request؛ حيث يمكننا تطبيق الدالة file للحصول على الصورة التي حمّلها المتصفّح بتحديد اسم المُدخَل input الذي استقبلها في صفحة الوٍب: 

 
$request->file('image');

نطبّق على الملف الدالة store لتخزينه: 

 
$image = $request->file('image')->store('images', 'public');

تأخذ الدالة store معطَيَيْن، الأول منهما هو اسم المجلّد حيثُ نريد تخزين الملفّ والثاني اسم القرص الذي نريد استخدامه. إن لم نحدّد اسمَ القرص فسيُستخدَم القرص المبدئي المعرّف بالتعليمة default ضمن ملف الإعداد config/filesystems (تأخذ التعليمة مبدئيا القيمة local).

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

خزّنا الآن الصورة على القرص المتاح للعموم. الخطوة التاليّة هي الحصول على مسارها من أجل إرساله إلى القالب image-upload لعرضه. نستخدم الدالة url ضمن الصنف Storage والتي يمكن تطبيقها على أقراص تستخدم أحد التعريفيْن local أو s3: 

 
$imagePath = Storage::url($image);

لا ننسى استيراد الصّنف Storage: 

 
use Illuminate\Support\Facades\Storage;

أصبحت دالة المتحكّم مكتملة على النحو التالي: 

public function imageUploadPost(Request $request)
{
  $image = $request->file('image')->store('images','public');
  $imagePath = Storage::url($image);

  return view('image-upload')
          ->with('message', "Image uploaded successfully")
          ->with('path', $imagePath);
}

لا ننسى إنشاء الوصلة الرمزية: 

 
php artisan storage:link

نشغّل خادوم التطوير المضمَّن في Laravel: 

 
php artisan serve

ثم نفتح المتصفّح لزيارة المسار http://localhost:8000/image-upload. نختار صورة لرفعها ثم نضغط على الزّر Upload. يخزّن Laravel الصّورة في المجلّد storage/app/public، ثم يطلُب عرض القالب image-upload مع تمرير رابط الصّورة في المتغيّر path، إضافة إلى رسالة في المتغيّر message تفيد بنجاح الرّفع.

ملحوظة: يختار Laravel عند استخدام الدالة store اسما مميّزا للملف بتطبيق دالة تجزئة Hash عليه. إن أردت اختيار الاسم الذي يُخزَّن به الملف فيمكنك ذلك بالدالة storeAs:

  • تخزين الملف في القرص المبدئي: 

    $image = $request->file('image')->storeAs('images','fileName');

     

  • تخزين الملف مع تحديد القرص: 

     
$image = $request->file('image')->storeAs('images','fileName','public');

العمليّات على الملفات المرفوعة

يوفّر Laravel الصّنفَ Storage للتعامل مع الملفات والأقراص.

إضافة ملفات إلى التخزين

تُستخدَم الدالة put في الصّنف Storage لتخزين ملفات على النحو التالي: 

 
Storage::put('images', $fileContents);

يُمثّل المعطى الأوّل الممرَّر إلى الدالة اسمَ المجلّد الذي تريد حفظ الملفّ فيه والثاني محتوى الملفّ. تستخدم الدالة أعلاه القرص المبدئي (التعليمة default في ملف الإعداد). إن أردت استخدام قرص مغاير فيمكنك الاستعانة بالدالة disk: 

 
Storage::disk('public')->put('images', $fileContents);

يُحدَّد المجلّد المُمرَّر إلى الدالة put (المعطَى الأول) اعتمادا على المسار الجذر للقرص المستخدَم؛ أي أن المقصود بالمجلّد images في المثال السابق هو المجلد storage/app/public/images؛ نظرا لكون storage/app/public هو المسار الجذر للقرص public. يُعيَّن المسار الجذر بالتعليمة root أثناء إعداد الأقراص في ملف الإعداد config/filesystems.

استرجاع ملف من التخزين

يتيح الصّنف Storage الدالة get لاسترجاع محتوى ملف مخزّن في القرص المبدئي: 

 
$contents = Storage::get('images/file.jpg');

يمكن تحديد القرص المستهدَف باستدعاء الدالة disk قبل تطبيق get.

يتوفّر الصّنف Storage على الدالة exists التي تتيح التأكد من وجود الملفّ: 

 
$exists = Storage::disk('s3')->exists('file.jpg');

الحصول على بيانات ملفّ

استخدم الدالة size على النحو التالي لمعرفة حجم ملفّ موجود في القرص المبدئي: 

 
$size = Storage::size('file1.jpg');

أو بتحديد القرص المستهدَف: 

 
$size = Storage::disk('s3')->size('file1.jpg');

يمكن على نفس المنوال معرفة تاريخ آخر تعديل على الملف على صيغة ختم زمني Timestamp: 

$time = Storage::lastModified('file1.jpg');

 

]]>392Mon, 27 Mar 2017 10:13:02 +0000مقدمة إلى نظام الإشعارات Notifications في Laravelhttps://academy.hsoub.com/programming/php/laravel/%D9%85%D9%82%D8%AF%D9%85%D8%A9-%D8%A5%D9%84%D9%89-%D9%86%D8%B8%D8%A7%D9%85-%D8%A7%D9%84%D8%A5%D8%B4%D8%B9%D8%A7%D8%B1%D8%A7%D8%AA-notifications-%D9%81%D9%8A-laravel-r390/

يضيف الإصدار 5.3 من Laravel نظاما للإشعارات Notifications يمكن من خلاله إخطار المستخدم بحدوث شيء ما. تُستخدَم الإشعارات، التي تكون عادة على هيئة بلاغات قصيرة، لإعلام مستخدم التطبيق بوقوع أمر ما؛ على سبيل المثال “صدور فاتورة”، “تسجيل مستخدم”، “إعادة تعيين كلمة السّر” أو “نشر درس”؛ حسب طبيعة التطبيق الذي تعمل عليه.

1.png

يتيح نظام الإشعارات في Laravel 5.3 وسائط عدّة (تُسمّى قنوات Channels) لتوصيل الإشعار: البريد الإلكتروني، الرسائل النصية القصيرة SMS (بالاعتماد على خدمة Nexmo) وخدمة Slack. يمكن أيضا تخزين الإشعارات في قاعدة البيانات من أجل عرضها في واجهة الوِب.

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

تهيئة المشروع

نبدأ أولا بتهيئة المشروع الذي سنعمل عليه. أنشئ مشروع Laravel 5.3 جديدا، إن لم يكن لديك واحد جاهز واضبط إعدادات قاعدة البيانات. نستخدم نفس الإعدادات المذكورة في فقرة تهيئة بيئة التطوير من درس أساسيات التخبئة في Laravel؛ مع التعديل عليها قليلا. سنضيف صنفا لبذر المستخدمين: 

 
php artisan make:seeder UsersTableSeeder

ونعدّل صنف البذر على النحو التالي لإضافة مستخدمَيْن إلى قاعدة البيانات: 

public function run()
{
    $user1 = [
      'name' => 'Med Ahmed Eyil',
      'email' => 'medeyil@laravel.com',
      'password' => Hash::make('1234'),
    ];
    $user2 = [
      'name' => 'Fatima Benziane',
      'email' => 'fbenziane@laravel.com',
      'password' => Hash::make('4567'),
    ];

    User::create($user1);
    User::create($user2);
}

ثم ننفّذ البذر: 

php artisan db:seed

يصبح لدينا الآن نموذجان، واحد للمستخدمين وآخر للمنشورات.

ننتقل إلى ملف المسارات routes/web.php ونضيف المسار التالي: 

Route::get('/notify/{user_id}/{post_id}', 'PostsController@notify');

يعني هذا أنه عند زيارة الرابط notify/user_id/post_id/ (حيث user_id وpost_id معرّفا المستخدم والمنشور على التوالي) سيطلُب Laravel تنفيذ الدالة notify في المتحكم PostsController. نعدّل المتحكّم PostsController لإضافة هذه الدالة: 

public function notify($user_id,$post_id) {
    $user = User::find($user_id);
    $post = Post::find($post_id);

    // todo
}

سنعود لاحقا لإكمال الدالة notify التي تكتفي لحد الساعة بالعثور على المستخدم والمنشور الممررَيْن إليها في المعطيات.

الإشعارات

هدفنا هو التالي: يطلُب المتصفح الرابط notify/1/2/ (مثلا) فيُرسَل إشعار عبر البريد إلى المستخدم ذي المعرف 1 يخبره أن المنشور ذا المعرف 2 قد أُضيف إلى الموقع. سنحتاج لبلوغ هذا الهدف لإشعار “إضافة منشور”. ننفذ الأمر التالي لإنشاء هذا الإشعار: 

php artisan make:notification NewPost

ستلاحظ بعد تنفيذ الأمر أعلاه ظهور مجلد جديد باسم Notifications (إن لم يكن موجودا سلفا) متفرع عن المجلد app وبداخله صنف باسم NewPost.php (نزعنا التعليقات للاختصار): 

<?php

namespace App\Notifications;

use Illuminate\Bus\Queueable;
use Illuminate\Notifications\Notification;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Notifications\Messages\MailMessage;

class NewPost extends Notification
{
    use Queueable;

    public function __construct()
    {
    }

    public function via($notifiable)
    {
        return ['mail'];
    }

    public function toMail($notifiable)
    {
        return (new MailMessage)
                    ->line('The introduction to the notification.')
                    ->action('Notification Action', 'https://laravel.com')
                    ->line('Thank you for using our application!');
    }

    public function toArray($notifiable)
    {
        return [
        ];
    }
}

يمدّد الصنف NewPost الصنفَ Notification الذي يحوي التعليمات الضرورية للتعامل مع الإشعارات. تظهر الدالة المشيّدة Constructor وثلاث دوال أخرى:

  • via: تعرّف القنوات التي نريد إرسال الإشعارات عبرها. توجد قناة البريد mail مبدئيا. تمكن إضافة قناة أخرى من تلك المتوفرة. يستخدم Laravel جميع القنوات المذكورة في المصفوفة المرجَعة، بمعنى؛ إن حددت مثلا القناتين mail وdatabase في المصفوفة فإن الإشعار سيُرسَل عبر البريد ويُخزَّن أيضا في قاعدة البيانات.
  • toMail: هذه الدالة خاصّة بالتعامل مع قناة البريد الإلكتروني. تنشئ الدالة toMail كائنا من صنف MailMessage لتخصيص بريد إلكتروني. سنعود لهذا الصنف بعد قليل.
  • toArray: إن حدّدت قناة للإشعارات في الدالة via دون أن تنشئ دالة خاصّة للتعامل معها فسيستدعي Laravel الدالة toArray. تجدر الإشارة إلى أن الدوال المخصّصة للتعامل مع قنوات الإشعارات تبدأ بـto متبوعة باسم القناة. مثلا toMail للبريد الإلكتروني (تأتي مبدئيا) وtoDatabase لتخصيص الإشعار عبر قناة قاعدة البيانات.

نعدّل الصنف NewPost قليلا بحيث نمرّر للمشيّد معطى من نوع Post (نزعنا أجزاء الصنف التي لم يطرأ عليها تعديل): 

<?php

// استدعاء الأصناف، أضفنا إليه الصنف Post
use App\Post;

class NewPost extends Notification
{

    // أضفنا خاصيّة post إلى الصنف
    protected $post;

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

// بقية شفرة الصّنف
}

نعود إلى الدالة notify في المتحكم ونعدّلها لتصبح على النحو التالي: 

public function notify($user_id,$post_id) {
    $user = User::find($user_id);
    $post = Post::find($post_id);

    $user->notify(new NewPost($post));
}

لا تنس استدعاء الصنف NewPost في المتحكم: 

 
use App\Notifications\NewPost;

استدعينا الدالة notify من الكائن user$ ومررنا إليها صنفا جديدا من الإشعار NewPost.

سنحتاج قبل تجربة إرسال الإشعار إلى ضبط البريد الإلكتروني في ملف النظام env.. ستجد في الملف عند فتحه الإعدادات التالية: 

MAIL_DRIVER=smtp
MAIL_HOST=mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null

يقترح Laravel مبدئيا موقع https://mailtrap.io الذي يوفر خدمة لمحاكاة إرسال بريد إلكتروني وعرضه. نحصُل بالتسجيل في الموقع على صندوق بريد للاختبار. ندخل إلى صندوق البريد (Demo inbox).

01_mailtrap_credentials.png

ننسخ قيم Username وPassword ونضيفها إلى الإعدادات في ملف env. على النحو التالي: 

MAIL_DRIVER=smtp
MAIL_HOST=mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME="be7c7d3972da27"
MAIL_PASSWORD="5f445b7bdca027"
MAIL_ENCRYPTION=null

يمكننا الآن اختبار الإشعار بتشغيل خادوم التطبيق والذهاب إلى المسار http://localhost:8000/notify/1/2. إن نظرت في صندوق البريد على موقع mailtrap فستجد رسالة جديدة:

02_email_notification.png

لاحظ العنوان البريدي الذي يُوجّه إليه الإشعار medeyil@laravel.com. إن عدلت المسار الذي تطلُبه إلى التالي http://localhost:8000/notify/2/2 ونظرت في الإشعار الذي يصل إلى البريد فستجد أن المرسَل إليه To تبدّل إلى fbenziane@laravel.com الذي هو بريد المستخدم ذي المعرف 2.

03_email_notification.png

هل تساءلت كيف يعرف نظام الإشعارات البريد الإلكتروني الذي يجب إرسال الإشعار إليه، أي البريد الإلكتروني الخاصّ بالمستخدِم؟

تخصيص الإشعار عبر البريد الإلكتروني

يمكن تطبيق الإشعارات على أي نموذج Eloquent في النظام، بشرط أن يستخدم النموذجُ السّمةَ Trait المسمّاة Notifiable. إن نظرنا إلى النموذج User الذي يأتي مبدئيا مع المشروع فسنلاحظ التالي: 

 
use Illuminate\Notifications\Notifiable;

و 

use Notifiable;

يتيح استخدام هذه السمة في النموذج إمكانية استدعاء الدالة notify: 

$user->notify(new NewPost($post));

التي تأخذ معطى عبارة عن كائن من صنف Notification.

بالنسبة لكيفية معرفة نظام الإشعارات ببريد المستخدم فالإجابة هي أن كل قناة إشعار تتطلّب وجود خاصيّات Properties معيّنة في النموذج الذي يستدعي الدالة notify. في حالة قناة البريد الإلكتروني فإن الخاصيّة المنتظرة هي - منطقيا - عنوان البريد email.

بالعودة إلى الصنف NewPost لاحظ دالة التعامل مع البريد الإلكتروني: 

public function toMail($notifiable)
{
    return (new MailMessage)
                ->line('The introduction to the notification.')
                ->action('Notification Action', 'https://laravel.com')
                ->line('Thank you for using our application!');
}

ترجع هذه الدالة كائنا من صنف MailMessage. إن تنبهت جيدا فستدرك أن العبارات الواردة في الشفرة أعلاه هي نفسها الموجودة في البريد المرسَل إلى المستخدم:

  • الدالة line تدرج فقرة في بريد الإشعار.
  • الدالة action تدرج زرًّا وتحدّد النص الذي يظهر على الزرّ ورابط الصفحة التي تزورها عند النقر على هذا الزرّ.

توجد دوال أخرى لتخصيص الإشعار أكثر:

  • subject لتخصيص موضوع البريد الإلكتروني.
  • from لتحديد بريد المرسِل.
  • attach لإضافة ملف مرفَق.
  • priority لتحديد الأولوية (1 تعني أولوية قصوى).

نخصّص في ما يلي البريد السّابق: 

public function toMail($notifiable)
{
    return (new MailMessage)
                ->subject('New post: '. $this->post->title)
                ->line('Don\'t miss our new post ' .$this->post->title)
                ->action('View the post', 'https://laravel.com')
                ->line('Thank you for your visit!')
                ->from('hsoub@academy.com');
}

نحصل بزيارة الرابط http://localhost:8000/notify/1/2 على النتيجة أدناه.

04_email_notification.png

بالنسبة لاسم التطبيق الذي يظهر في الإشعار فيمكن تعديله عن طريق التعليمة name في ملف الإعداد config/app.php. تأخذ التعليمة مبدئيا القيمة Laravel.

إن أردت تخصيصا أكبر للبريد ومظهره فيمكنك ذلك بنشر قالب Blade الخاص بالبريد الإلكتروني للإشعار ومن ثم تخصيصه. نفذ الأمر التالي لنشر القالب: 

 
php artisan vendor:publish --tag=laravel-notifications

ستجد القالب على المسار resources/views/vendor/notifications/email.blade.php؛ حيث يمكنك التعديل عليه بما تراه مناسبا.

]]>390Sun, 12 Mar 2017 11:18:00 +0000كيف تستخدم منشئ الاستعلامات Query builder للتخاطب مع قاعدة البيانات في Laravelhttps://academy.hsoub.com/programming/php/laravel/%D9%83%D9%8A%D9%81-%D8%AA%D8%B3%D8%AA%D8%AE%D8%AF%D9%85-%D9%85%D9%86%D8%B4%D8%A6-%D8%A7%D9%84%D8%A7%D8%B3%D8%AA%D8%B9%D9%84%D8%A7%D9%85%D8%A7%D8%AA-query-builder-%D9%84%D9%84%D8%AA%D8%AE%D8%A7%D8%B7%D8%A8-%D9%85%D8%B9-%D9%82%D8%A7%D8%B9%D8%AF%D8%A9-%D8%A7%D9%84%D8%A8%D9%8A%D8%A7%D9%86%D8%A7%D8%AA-%D9%81%D9%8A-laravel-r398/

يأتي Laravel بإطار العمل Eloquent مضمّنا مبدئيا؛ وهو ما يتيح بناء نماذج تُعالّج فيها البيانات وتُطبّق عليها القواعد التي تحكُم سير التطبيق. يُيسّر Eloquent كثيرا من الأمور على المطوِّر؛ إلا أنّه يمكن أن يكون أحيانا غير مناسب لتعقيد المشروع الذي تعمل عليه. يوفّر Laravel آلية للتعامل مع قواعد البيانات مباشرة دون الحاجة لربط كائنات التطبيق بجداول قاعدة البيانات. تُسمى هذه الآلية منشئ الاستعلامات Query builder. كانت الاستعلامات المعدّة بمنشئ الاستعلامات ترجع النتائج، في الإصدارات السابقة (قبل الإصدار 5.3) من Laravel، على هيئة مصفوفة Array؛ إلا أن الأمر تغيّر في الإصدار 5.3 وأصبحت أغلب دوالّ بناء الاستعلامات ترجع نتيجة من نوع Collection (مجموعة).

2.png

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

أيهما أستخدم.. Eloquent أم منشئ الاستعلامات؟

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

  • التحقق المُستَتِر Dirty check: تحديث الحقول التي تغيّرت قيمتها فقط دون غيرها، عند تنفيذ استعلامات UPDATE.
  • ربط النماذج بأحداث Events؛ مثلا لإشعار المستخدمين أو تحديث إحصائيات عند إنشاء مستخدم جديد.
  • إدارة الحذف اللطيف Soft delete: تعليم تسجيلة على أنها محذوفة بدلا من حذفها فعلا.
  • تنفيذ آليات التحميل الحثيث Lazy loading (طلب البيانات عند الحاجة إليها).

يمكن - بالطبع - تطبيق هذه الآليات بنفسك دون الاعتماد على Eloquent؛ إلا أن ذلك سيأخذ وقتا. من الجيد أن يكون لديك سبب مقنع للوقت الذي ستمضيه في هذه المهمة بدلا من التركيز على أمور *قد* تكون أهم. سيكون مثاليّا جدا الحصولُ على كلّ هذه التسجيلات بدون دفع ثمن، إلا أن الأمور في الواقع ليست مثالية. الثمن الذي تدفعه مقابل التسهيلات التي يتضمّنها Eloquent - وأطر عمل ORM الأخرى، بغضّ النظر عن لغة البرمجة - هو سرعة تنفيذ الاستعلامات. على الجهة الأخرى، تمكّن كتابة الاستعلامات من الوصول إلى أقصى سرعة ممكنة في التنفيذ، مقابل التضحية بالجهد والوقت أثناء التطوير.

لا يوجد مانع من مزج جميع الوسائل المتاحة أمامك؛ بل إن الأمر محبّذ. مثلا؛ استخدم Eloquent عندما تتعامل مع كيانات منفردة (استمارة تسجيل على موقع مثلا)، الجأ لمنشئ الاستعلامات في المهامّ التي تتطلب وقتا للتنفيذ (كيانات بالجملة Batch processing أو إعداد تقارير على سبيل المثال) واكتب استعلامات SQL مباشرة عندما تكون أمام استعلام شديد التعقيد.

الجديد في Laravel 5.3

نستخدم منشئ الاستعلامات في المثال التالي للحصول على كافة المستخدمين (جدول users في قاعدة البيانات): 

DB::table('users')->get();

تكافئ التعليمة السابقة في نتيجتها تنفيذ الاستعلام التالي:  

SELECT * FROM users;

كانت النتيجة، في الإصدارات السابقة من Laravel، من نوع Array (مصفوفة)؛ إلا أن هذا الأمر تغيّر في الإصدار 5.3 لتصبح النتيجة من نوع Collection (مجموعة). يعني هذا أنه للوصول إلى العنصر الأول في مجموعة المستخدمين السابقة فإننا يمكن أن نكتب: 

DB::table('users')->get()->first();

بدلا من: 

DB::table('users')->get()[0];

يجعل هذا التغيير من منشئ الاستعلامات متناسقا في نوع النتيجة مع Eloquent الذي يرجع مجموعة كائنات؛ كما أنه يمكّن من استخدام الدوال الموجودة مبدئيا للتعامل مع المجموعات؛ ومن بينها الدالة all التي ترجع مصفوفة مكافئة للمجموعة؛ مثلا ترجع التعليمة التالية مصفوفة بالمستخدمين: 

DB::table('users')->get()->all();

إن كان لديك تطبيق مبني على اعتبار أن منشئ الاستعلامات يُرجع النتائج على هيئة مصفوفات، فأسهل طريقة لتعديل الشفرة المصدرية للتوافق مع تغيير نوع النتيجة إلى مجموعة بدلا من مصفوفة؛ هي استخدام الدالة all.

ملحوظة 1: لا ينطبق التغيير المذكور أعلاه (إرجاع مجموعة بدلا من مصفوفة) على دوال الصنف DB التي تتعامل مع استعلامات SQL مباشرة. مثلا؛ ترجع التعليمة التالية مصفوفة: 

DB::select('SELECT name FROM users WHERE id = ?', [1]);

ملحوظة 2: انتبه عند استخدام استعلامات SQL مباشرة من ثغرات الحَقن SQL injection. استخدم ربط المتغيّرات Binding (كما في الملحوظة 1) بدلا من تمرير المتغيّر مباشرة كما في الاستعلام التالي: 

DB::select("SELECT name FROM users WHERE id = '$id' "]);

قد يمثل الاستعلام الأخير خطرا إن لم يُتحقّق من المتغيّرid$ قبل استخدامه في الاستعلام. يتحقّق Laravel تلقائيا من المُدخلات عند ربط المتغيّرات كما في استعلام الملحوظة 1.

راجع مقال استخدام Eloquent ORM للتعامل مع قاعدة البيانات في Laravel 5.

]]>398Wed, 08 Mar 2017 09:02:00 +0000تخصيص التّصفيح Pagination في Laravelhttps://academy.hsoub.com/programming/php/laravel/%D8%AA%D8%AE%D8%B5%D9%8A%D8%B5-%D8%A7%D9%84%D8%AA%D9%91%D8%B5%D9%81%D9%8A%D8%AD-pagination-%D9%81%D9%8A-laravel-r391/

يعدّ التصفيح Pagination (إعداد الصفحات) إحدى المهامّ الشائعة في مواقع الوِب، وهو ما دعا Laravel لتضمين هذه الوظيفة مبدئيا في إطار العمل. كانت تخصيص التصفيح في الإصدارات الأولى من Laravel بسهولة إعداد قالب Blade؛ إلا أن الأمر تغيّر في الإصدار 5.0، إذ عمل إطار العمل على تسهيل نظام التصفيح الذي يستخدمه لتمكن إعادة استخدامه في مشاريع لا تعتمد على إطار العمل Laravel. صاحب هذه العمليّة تعقيد في إمكانيّة تخصيص التصفيح.

3.png

يأتي الإصدار 5.3 لتصحيح هذه الوضعية وإعادة الأمور إلى نصابها.

تهيئة المشروع

سنهيّئ مشروع Laravel 5.3 للعمل عليه. نبدأ بالتثبيت: 

 
composer create-project --prefer-dist laravel/laravel laravel53pagination "5.3.*"

يأتي المشروع مبدئيا بنموذج للمستخدم User، سنعمل من أجل الشرح على هذا النموذج. نبدأ بإعداد مسار للمستخدمين في ملف المسارات الخاصّ بالوِب routes/web.php: 

Route::get('users', function () {
    return view('users.index')
        ->with('users', User::paginate(5));
});

يطلُب المسار users/ عند زيارته عرضَ القالب index.blade.php الموجود في المجلّد users ضمن مجلد القوالب resources/views. نمرّر للقالب المتغيّر users الذي يتلقّى نتيجة استدعاء الدالة paginate للحصول على المستخدمين المسجلين في قاعدة البيانات. ما يميّز هذه الدالة عن بقيّة الدوال الأخرى التي يمكن استدعاؤها في النموذج هي أنها توفّر إمكانية تطبيق الدالة links في قالب Blade من أجل إنشاء الصفحات، كما سنرى الآن.

ليس لدينا لحد الساعة المجلد users ولا الملف index.blade.php، ننشئ المجلد والملف بحيث يصبح مسار ملف القالب resources/views/users/index.blade.php ثم نفتحه ونضيف إليه المحتوى التالي: 

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8"  >
<title> Document </title>
<link rel="stylesheet" href="/css/app.css">
<style type="text/css"> body { padding: 10em;}</style>
</head>
<body>
@foreach ($users as $user)
    <li>{{ $user->name }}</li>
@endforeach

{{ $users->links() }}
</body>
</html>

لدينا في أعلى الملف بضعة تعليمات للتنسيق، ثم تأتي في جسم المستند body التعليمة التكرارية foreach التي تمرّ على المستخدمين وتعرض أسماءهم، وفي الأخير الدالة links التي تحدثنا عنها أعلاه. يمكننا استدعاء هذه الدالة على المتغيّر users نظرا لأننا استخدمنا الدالة paginate في ملف المسارات للحصول على المستخدمين. تتكفّل الدالة links بإنشاء الصفحات عبر تقسيم المستخدمين على مجموعة من خمسة عناصر (مرّرنا المعطى 5 للدالة paginate في ملف المسارات).

بقي لنا بذر جدول المستخدمين حتى يمكننا تجربة ما أنجزناه لحد الآن: 

 
php artisan make:seeder UsersTableSeeder

نستعين بمكتبة Faker لتوليد مستخدمين وهميين وبذر الجدول: 

public function run()
{
  User::unguard();

  // نستخدم Faker لتوليد البيانات
  $faker = Faker\Factory::create();

  // إنشاء 20 مستخدما
  foreach(range(1, 20) as $index) {
      User::create([
          'name' => $faker->name,
          'email' => $faker->safeEmail,
          'password' => $faker->password,
      ]);
  }

  User::reguard();
}

لا تنس استيراد النموذج: 

 
use App\User;

ثم نعدّل DatabaseSeeder لإضافة ملف البذر الذي أنشأناه للتو: 

 
$this->call(UsersTableSeeder::class);

يمكننا الآن تنفيذ التهجيرات (تهجير المستخدم يأتي مبدئيا مع المشروع): 

 
php artisan migrate

ثم بذر قاعدة البيانات: 

 
php artisan db:seed

ثم تشغيل خادوم التطوير: 

 
php artisan serve

تظهر عند زيارة الرابط http://localhost:8000/users قائمة بالمستخدمين مقسّمة على صفحات من خمسة مستخدمين.

01_pagination.png

عند النقر على رقم الصّفحة ينقلك إلى مجموعة جديدة من المستخدمين.

تخصيص التصفيح في Laravel

يوجد القالب المبدئي لروابط الصفحات على المسار vendor/laravel/framework/src/Illuminate/Pagination/resources/views إن أردت تخصيصه فسيتوجّب عليك نشره بالأمر التالي: 

 
php artisan vendor:publish --tag=laravel-pagination

وستجد بضعة قوالب على المسار ressources/views/vendor/pagination.
يستخدم اثنان من هذه القوالب (bootstrap-4.blade.php وsimple-boostrap-4.blade.php) الإصدار 4 من Bootstrap والذي ما زال قيد التطوير؛ أما الآخران فأحدهما هو القالب المبدئي default.blade.php والآخر (simple-default.blade.php) نسخة مبسّطة منه لا تحوي سوى أزرار سابق ولاحق للتنقل بين الصفحات.

أدناه الشفرة الخاصّة بالقالب المبدئي: 

@if ($paginator->hasPages())
    <ul class="pagination">
        {{-- Previous Page Link --}}
        @if ($paginator->onFirstPage())
            <li class="disabled"><span>«</span></li>
        @else
            <li><a href="{{ $paginator->previousPageUrl() }}" rel="prev">«</a></li>
        @endif

        {{-- Pagination Elements --}}
        @foreach ($elements as $element)
            {{-- "Three Dots" Separator --}}
            @if (is_string($element))                    <li class="disabled"><span>{{ $element }}</span></li>
            @endif

            {{-- Array Of Links --}}
            @if (is_array($element))
                @foreach ($element as $page => $url)
                    @if ($page == $paginator->currentPage())
                        <li class="active"><span>{{ $page }}</span></li>
                    @else
                        <li><a href="{{ $url }}">{{ $page }}</a></li>
                    @endif
                @endforeach
            @endif
        @endforeach

        {{-- Next Page Link --}}
        @if ($paginator->hasMorePages())
            <li><a href="{{ $paginator->nextPageUrl() }}" rel="next">»</a></li>
        @else
            <li class="disabled"><span>»</span></li>
        @endif
    </ul>
@endif
  • تتيح الدالة hasPages التحقق من وجود صفحات لعرضها.
  • نتحقّق بالدالة onFirstPage من أننا على الصفحة الأولى.
  • يمكن بالدالة hasMorePages معرفة ما إذا كان لدينا مزيد من الصفحات لعرضها.
  • تطبع الدالتان previousPageUrl وnextPageUrlعلى التوالي رابطي الصفحة السابقة واللاحقة للصفحة الحالية التي نحصل عليها بالدالة currentPage.

سنعدّل الآن القالب بحيث نضع كلمة Previous (السابق) مكان الرمز »، على ألا تظهر عندما نكون على الصفحة الأولى.

02_pagination.png

نضع بنفس الطريقة كلمة Next (التالي) مكان «، على ألا تظهر عندما نكون على الصفحة الأخيرة.

03_pagination.png

نحصُل على الشفرة التاليّة: 

@if ($paginator->hasPages())
    <ul class="pagination">
        {{-- Previous Page Link --}}
        @if (!$paginator->onFirstPage())
            <li><a href="{{ $paginator->previousPageUrl() }}" rel="prev">Previous</a></li>
        @endif

        {{-- Pagination Elements --}}
        @foreach ($elements as $element)
            {{-- "Three Dots" Separator --}}
            @if (is_string($element))
                <li class="disabled"><span>{{ $element }}</span></li>
            @endif

            {{-- Array Of Links --}}
            @if (is_array($element))
                @foreach ($element as $page => $url)
                    @if ($page == $paginator->currentPage())
                        <li class="active"><span>{{ $page }}</span></li>
                    @else
                        <li><a href="{{ $url }}">{{ $page }}</a></li>
                    @endif
                @endforeach
            @endif
        @endforeach

        {{-- Next Page Link --}}
        @if ($paginator->hasMorePages())
            <li><a href="{{ $paginator->nextPageUrl() }}" rel="next">Next</a></li>
        @endif
    </ul>
@endif

احفظ التعديلات ثم أعد تنزيل الصفحة للحصول على نتيجة مشابهة لتلك الظاهرة في الصورتين أعلاه.

]]>391Thu, 02 Mar 2017 11:42:00 +0000أساسيات التخبئة Cache في Laravelhttps://academy.hsoub.com/programming/php/laravel/%D8%A3%D8%B3%D8%A7%D8%B3%D9%8A%D8%A7%D8%AA-%D8%A7%D9%84%D8%AA%D8%AE%D8%A8%D8%A6%D8%A9-cache-%D9%81%D9%8A-laravel-r389/

يوفّر Laravel واجهة تطبيقات برمجية موّحدة للتعامل مع أنظمة تخبئة Cache مختلفة مثل Memcached وRedis.

سنعرض في هذا المقال لكيفية إعداد التخبئة في Laravel ومبدأ عملها ثم نتطرق للدالة المساعدة cache التي أضيفت إلى إطار العمل بداية من الإصدار 5.3.

laravel-cache.png

تهيئة بيئة التطوير

يُحدَّد اسم النظام المستخدَم في التعليمة CACHE_DRIVER ضمن ملف env.. تأخذ التعليمة CACHE_DRIVER مبدئيا القيمة file التي تعني أن الكائنات Objects المخبَّأة ستخزن ضمن ملف ضمن نظام التشغيل. تُضبَط إعدادات نظام التخبئة المستخدَم في الملف config/cache.php، بعد تعيينه بالتعليمة السابقة.

نفترض أنك لديك مشروع Laravel بالإصدار 5.3 للتطبيق عليه. ننفذ الخطوات التالية لتهيئة مثال نعتمد عليه في ما بعد للشرح.

إنشاء نموذج والتهجير المصاحب له وبذره

نستخدم artisan لإنشاء نموذج Eloquent مع التهجير المصاحب له على النحو التالي: 

php artisan make:model Post -m

نفتح ملف التهجير لضبط الحقول في جدول البيانات بإضافة حقل جديد يُسمّىtitle (العنوان): 

public function up()
{
    Schema::create('posts', function (Blueprint $table) {
        $table->increments('id');
        $table->string("title");
        $table->timestamps();
    });
}

يمكننا الآن تنفيذ التهجير: 

php artisan migrate

الخطوة التالية هي بذر الجدول الحصول على بيانات للتطبيق عليها. ننشئ ملف البذر: 

php artisan make:seeder PostsTableSeeder

ثم نعدل عليه: 

class PostsTableSeeder extends Seeder
{
    public function run()
    {
    Model::unguard();

    // نستورد faker لبذر الجدول
    $faker = Faker\Factory::create();

    // ننشئ 10 تسجيلات في الجدول
    foreach(range(1, 10) as $index) {
        Post::create([
            'title' => $faker->sentence(5),
        ]);
    }

    Model::reguard();
    }
}

نعدّل ملف بذر قاعدة البيانات لإضافة ملف بذر الجدول posts إليه: 

public function run()
{
    $this->call(PostsTableSeeder::class);
}

ثم ننفذ البذر: 

php artisan db:seed --class=PostsTableSeeder

لدينا الآن جدول بيانات بـ10 تسجيلات. أكملنا إعداد النموذج الذي نريد العمل عليه، الخطوة الموالية هي إعداد المتحكم والمسارات.

المتحكم والمسارات

نستعين بأداة artisan لإنشاء متحكم على النحو التالي: 

 
php artisan make:controller PostsController

ننشئ في المتحكم PostsController دالة باسم index نستخدمها للحصول على جميع المنشورات الموجودة في جدول البيانات posts بصيغة JSON: 

public function index() {
    $posts = Post::all();
    return response()->json($posts);
}

لا تنس استيراد النموذج Post: 

 
use App\Post;

ثم ننتقل إلى إعداد المسارات. سنضيف مسارا باسم posts/ إلى ملف مسارات واجهةالوب routes/web.php: 

 
Route::get('/posts', 'PostsController@index');

يمكننا الآن تنفيذ الأمر php artisan serve من مجلد المشروع لتشغيل الخادوم الخاص ببيئة التطوير ثم الذهاب إلى الرابط http://localhost:8000/posts لرؤية جميع المنشورات المحفوظة في الجدول.

إعداد التخبئة واستخدامها

تُضبَط التخبئة - كما أسلفنا - في الملفين env. وconfig/cache.php. يحوي الصنف Illuminate\Support\Facades\Cache الكثير من الدوال الثابتة Static التي تتعامل مع التخبئة.

إضافة قيمة إلى التخبئة

تُستخدَم الدالة Cache::put لإضافة قيمة إلى التخبئة. تأخذ الدالة ثلاثة معطيات: 

Cache::put('key', 'value', 10);
  • مفتاح key يمثل اسم المتغير. لا يمكن أن تحمل قيمتان في النظام نفس المفتاح.
  • قيمة المفتاح value.
  • مدة زمنية معبَّر عنها بالدقائق (10 في المثال أعلاه)، وتمثل المدة التي سيحتفظ النظام فيها بقيمة المفتاح ضمن التخبئة.

تمكن أتمتة إضافة المفاتيح إلى التخبئة بالدالة remember. تبحث هذه الدالة أولا عن قيمة المفتاح في التخبئة، وترجعها إن وجدته؛ فإن لم تجده تنشئ المفتاح وتعطيه القيمة التي ترجعها دالة الإغلاق Closure الممررة في المعطى الثالث.
سنستخدم الدالة remember في دالة index التي أضفناها سابقا إلى المتحكم. نعدّل الدالة index على النحو التالي: 

public function index() {
    $posts = Cache::remember('posts', 5, function() {
        return Post::all();
    });
    return response()->json($posts);
}

لا ننسى استدعاء الصنف Cache: 

 
use Illuminate\Support\Facades\Cache;

تعني الشفرة أعلاه أننا عند طلب الدالة index فإنها ستبحث عن المنشورات الموجودة في التخبئة، فإن وجدتها ترجعها وإلا فإنها تنشئها باستدعاء الدالة all من النموذج Post؛ وتحتفظ بها في التخبئة لمدة خمس دقائق؛ ثم ترجع النتيجة.

بهذا تكون جميع الطلبات التي ترد إلى المسار posts/ تمر عبر التخبئة؛ سنضيف لأغراض التوضيح مسارا جديدا (ضمن routes/web.php) لنعدل عن طريقه على إحدى التسجيلات الموجودة في جدول المنشورات: 

 
Route::get('/edit/post/{id}', 'PostsController@edit');

ونعدّل المتحكم بإضافة الدالة edit التالية: 

public function edit($id) {
    $post = Post::find($id);
    $post->title = "New title for ".$id;
    $post->save();
    $posts = Post::all();
    return response()->json($posts);
}

ما يحدث هو التالي: تظهر عند زيارة الرابط posts/ المنشورات مع المرور على نظام التخبئة؛ أما عند زيارة المسار edit/post/id/ فسنعدّل على المنشور ذي المعرف id، ثم نعرض المنشورات المخزنة في الجدول مباشرة، دون البحث عنها في التخبئة.

يظهر في الصورة المتحركة التالية الفرق بين استخدام التخبئة وطلب المنشورات مباشرة من الجدول:

01_laravel_cache.gif

  • تكون التخبئة فارغة عند زيارة المسار posts/ لأول مرة. في هذه الحالة يطلب Laravel المنشورات مباشرة من جدول البيانات، يعرضها ثم يضيفها إلى التخبئة.
  • نطلب الرابط edit/post/1/ الذي يغيّر عنوان المنشور ذي المعرف 1 ليصبح New title for 1؛ ثم يعرض المنشورات بطلبها مباشرة من جدول قاعدة البيانات. لاحظ تغير عنوان المنشور.
  • نعود للرابط posts/ قبل انقضاء المدة المحددة في دالة التخبئة (5 دقائق)، نلاحظ أن التعديل الذي أجريناه لا يظهر في المنشورات المعروضة.

ملحوظة: يجب التأكد في التطبيقات الموجهة لبيئة الإنتاج من تناسق عمليات التعديل على قاعدة البيانات والتخبئة. بمعنى أنه يجب أن ينعكس التعديل على قيمة في جدول البيانات مباشرة على القيمة المحفوظة في التخبئة.

العمليات على التخبئة

  • الحصول على قيمة من التخبئة: 

    Cache::get('key');

    يمكن إرجاع قيمة مبدئية في حال عدم وجود المفتاح في التخبئة: 

    Cache::get('key', 'default');

    تبحث الدالة أعلاه عن قيمة المفتاح key في التخبئة، فإن لم تجدها ترجع القيمة المبدئية default.

  • التحقق من وجود مفتاح في التخبئة: 

    if (Cache::has('key')){
    Cache::get('key');
} else {
    Cache::put('key', $values, 10);
}

    نتحقق في الشفرة أعلاه من وجود قيمة للمفتاح key ونرجعها إن وجدت؛ وإلا نضيف قيمة جديدة للمفتاح في التخبئة.

  • نزع مفتاح من التخبئة: 

     
    Cache::forget('key');

    كما يمكن استخدام الدالة pull التي تبحث عن قيمة في التخبئة، ثم تحذفها بعد الحصول عليها: 

    Cache::pull('key');

    يشبه الأمر تنفيذ الدالتين get وforget بالتتالي.

    توجد طريقة أخرى لحذف محتوى التخبئة قبل انتهاء المدة المحددة له بتنفيذ أمر artisan التالي: 

    php artisan cache:clear

     

الدالة المساعدة cache

يحتوي إطار العمل Laravel على الكثير من دوال PHP المساعدة؛ بعضها مستخدَم في وظائف إطار العمل نفسه. تعمل الدوال المساعدة Helper functions على الرفع من الإنتاجية والابتعاد عن تكرار الشفرات البرمجية بتجميع وظائف اعتيادية وإتاحة الوصول إليها حيث دعت الحاجة.
يضيف الإصدار 5.3 دالة مساعدة جديدة باسم cache يمكن استخدامها في أي جزء من المشروع من أجل تسهيل التخاطب مع نظام التخبئة، بدلا من الصّنف Illuminate\Support\Facades\Cache.

نحصل على قيمة المتغير key (المفتاح) باستخدام الدالة المساعدة cache على النحو التالي: 

cache('key');

تكافئ التعليمة أعلاه استخدام الصنف Cache على النحو التالي: 

Cache::get('key');

يمكن أيضا تمرير مصفوفة بالمفاتيح وقيمها إلى الدالة cache؛ ونحدّد المدة الزمنية التي نريد أن تستغرقها التخبئة: 

cache(['title' => 'Hsoub Academy'], 5);

إن طلبنا في الخمس دقائق القادمة قيمة المفتاح title في الدالة cache فسنجد القيمة Hsoub Academy.

نستخدم الدوال الموجودة في الصنف Cache في الدالة المساعدة cache بنفس الطريقة:

  • إضافة مفتاح إلى التخبئة: 

    cache()->put('key', 'value', 10);

    أو 

     
    cache(['key' => 'value'],10);

    البحث عن قيمة المفتاح في التخبئة، وإضافته إليها إن لم يوجد بها: 

    cache()->remember('key', 5, function() {
    //
});

     

  • الحصول على قيمة مفتاح من التخبئة ثم حذفه منها بعد ذلك: 

    cache()->pull('key');

     

  • حذف مفتاح من التخبئة: 

    cache()->forget('key');

     

نعيد كتابة الدالة index في المتحكم PostsController بالدالة المساعدة cache بدلا من الصنف Cache: 

public function index() {

    $posts = cache()->remember('posts', 5, function() {
        return Post::all();
    });
    return response()->json($posts);

}

يمكن ملاحظة أنك لا تحتاج لاستيرد صنف جديد؛ فالدالة المساعدة متوفرة في جميع المشروع.

]]>389Tue, 28 Feb 2017 06:00:00 +0000كيف تتجنب مشكل N+1 في Laravel باستخدام التحميل النّشط Eager Loadinghttps://academy.hsoub.com/programming/php/laravel/%D9%83%D9%8A%D9%81-%D8%AA%D8%AA%D8%AC%D9%86%D8%A8-%D9%85%D8%B4%D9%83%D9%84-n1-%D9%81%D9%8A-laravel-%D8%A8%D8%A7%D8%B3%D8%AA%D8%AE%D8%AF%D8%A7%D9%85-%D8%A7%D9%84%D8%AA%D8%AD%D9%85%D9%8A%D9%84-%D8%A7%D9%84%D9%86%D9%91%D8%B4%D8%B7-eager-loading-r433/

مقدمة

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

laravel3.png

لقد كانت ثلاث حلقات من نوع foreach تستعلم عن صفةattribute معينة وعن الصّفات المتعلقة بها. كانت هذه الحلقات تعمل بشكل جيّد حتى أصبح هناك ما يقارب من 5500 عُنصر في قاعدة البيانات. إليك ما كان يحصل: 

$main_object = MainObject::all();

foreach($main_object as $object) {
    echo $object->some_property;

    foreach($object->related_object as $related) {
        echo $related->some_property;
        echo $related->another_property;
    }

    foreach($object->another_related as $another) {
        echo $another->some_property;
        echo $another->another_property;
    }
}

إذا كانت $main_object = MainObject::all(); تقوم بإرجاع 5500 نتيجة، فإنّ أوّل حلقة foreach سوف تُنفَّذ 5500 مرة وكذلك الحال بالنّسبة للحلقتين الثانية والثالثة. عند استعمال ما يُسمى بمخطّط الكائن العلائقيّة ORM ، يقوم أغلب المطورين بكتابة استعلامات قواعد بيانات غير فعّالة، ويُصعّب استخدام الـORM مُهمّة اكتشاف هذه الأخطاء. تُسمّى هذه المشكلة بمشكلة N+1 وأعتقد بأنّ المُطوّر السّابق لم ينتبه لذلك. ولنتفادى هذه المشكلة سنقوم باستعمال التحميل النّشط(eager loading).

ما هو التحميل النّشط(eager loading)؟

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

Figure1_stores_model.png

يوجد لدينا نموذج علاقة كائنيّة مُعزّزة enhanced entity-relationship model يحتوي على ثلاث وحدات/كائنات مترابطة. يمكننا قراءة هذا النموذج كالتالي: كل عضو(member) يمكنه أن يملك أكثر من متجر(store) ولكن المتجر الواحد ينتمي إلى عضو واحد فقط. كل متجر يمكن أن يحتوي على أكثر من مُنتَج(product) ولكن المنتَج الواحد ينتمي إلى متجر واحد فقط.
الخطوة التّالية هي إنشاء نماذج eloquent لهذه الوحدات/الكائنات.
عضو(member): 

<?php namespace App;

use Illuminate\Database\Eloquent\Model;

class Member extends Model {

    /**
     * The attributes that are mass assignable.
     *
     * @var array
     */
    protected $fillable = ['username', 'email', 'first_name', 'last_name'];

    public function stores() {
        return $this->hasMany('App\\Store');
    }
}

متجر(store): 

<?php namespace App;

use Illuminate\Database\Eloquent\Model;

class Store extends Model {

    /**
     * The attributes that are mass assignable.
     *
     * @var array
     */
    protected $fillable = ['name', 'slug', 'site', 'member_id'];

    public function  member() {
        return $this->belongsTo('App\\Member');
    }

    public function products() {
        return $this->hasMany('App\\Product');
    }
}

مُنتَج(product): 

<?php namespace App;

use Illuminate\Database\Eloquent\Model;

class Product extends Model {

    /**
     * The attributes that are mass assignable.
     *
     * @var array
     */
    protected $fillable = ['name', 'short_desc', 'long_desc', 'price', 'store_id', 'member_id'];

    public function  store() {
        return $this->belongsTo('App\\Store');
    }
}

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

Figure2_storelist_mockup.png

قد ينتهي بك المطاف بشيء كهذا في المتحكم(controller) الخاص بك: 

<?php namespace App\Http\Controllers;

use App\Repositories\StoreRepository;

class StoresController extends Controller {

    protected $stores;

    function __construct(StoreRepository $stores) {
        $this->stores = $stores;
    }


    public function index() {
        $stores = $this->stores->all();

        return \View::make('stores.index')->with('stores', $stores);
    }
}

في الـView تريد أن تظهر تلك البيانات: 

@foreach($stores as $store)
    <h1>{{ $store->name }}</h1>
    <span>Owner: {{ $store->member->first_name . ' ' . $store->member->last_name }}</span><br>

    <h2>Products:</h2>
    @foreach($store->products as $product)
        <h3>{{$product->name}}</h3>
        <span>{{$product->short_desc}}</span><br/><br/>
        <span>Price: {{$product->price}}</span>
        <br/>
        <?php Debugbar::info('Product displayed'); ?>
    @endforeach
    <br/>
    ========================
    <br/>
@endforeach

وتكون النتيجة كالتالي:

Figure3_n_plus_one_problem.png

في هذا المثال، قُمت بإعطاء قاعدة البيانات 5 أعضاء و3 متاجر و4 منتجات. الاستعلام الأول هو لجلب جميع المتاجر من قاعدة البيانات وهذا هو الجزء “+1” من المشكلة N+1. وفي هذا المثال تحديدًا، فإنّ الحرف “N” يُمثّل عدد المتاجر التي سيقوم الاستعلام الأول بإرجاعها، وسيتم تنفيذ استعلام select *from بنفس العدد على جداول المنتجات والأعضاء. ولأنّ هناك 3 متاجر، فهذا يعني بأنّنا سنقوم بإجراء 3 استعلامات على جدول الأعضاء و3 استعلامات أخرى على جدول المنتجات، وبالتالي يصبح عدد الاستعلامات التي تمّ تنفيذها بالكامل هو 3+3+1.
تخيّل معي الآن ماذا كان سيحصل لو كان هناك 5 آلاف أو 10 آلاف متجر؟ سيكون هناك من 10 آلاف إلى 20 ألف استعلام في كلّ مرّة يزور أحدهم تلك الصفحة. وماذا لو كان هناك 10 آلاف أو 100 ألف زائر خلال 24 ساعة فقط؟ سيكون ذلك بمثابة كابوسٍ مرعبٍ بلا شك. يظهر الآن وبكلّ وضوح بأنّ هذه الطّريقة غير مجدية وقاتلة للأداء(performance killer). لن يهم أي قاعدة بيانات تستخدم أو قوّة الخادوم فستكون هناك دائمًا نقطة ما لن يستطيع العتاد القوي التعامل معها. يمكنك تحسين الأداء عن طريق التخزين المؤقت(caching) للاستعلامات؛ باستخدام Redis على سبيل المثال. سيعمل ذلك جيّدًا ولكن بشكل مؤقّت. ستقوم بتلك الطّريقة فقط بتأخير النّهاية الحتميّة التي ستكلّفك الكثير من المال والوقت وقد تخسر أيضًا الكثير من المستخدمين.
وهنا يأتي دور التّحميل النّشط. فاستعمال التحميل النّشط في Laravel يُعدّ أمرًا في غاية السهولة. فعن طريق استخدام تابع with تقوم بتحديد العلاقات التي تريد أن يتمّ تحميلها تحميلاً نشطًا: 

$stores = Store::with('member','products')->get();

باستعمال التحميل النّشط، قمنا بتقليص عدد الاستعلامات من 7 إلى 3 فقط، كما توضح الصورة التالية:

Figure4_n_plus_one_problem_eager.png

وحتى لو كان هناك 10 آلاف مُدخل للمتجر، فإنّ عدد الاستعلامات لن يتغير وسيبقى 3 فقط. وكما ترى، فإنّ استخدام التّحميل النّشط بالشّكل المناسب قد يُحسّن من الأداء بصورة كبيرة. وحتى نرى تحسّنًا فعليًا، فإنّه يجب أيضًا أن يكون هناك مؤشّر/فهرس(index) على حقول المُعرّفات(id fields) في جداول الأعضاء والمنتجات. فمع وجود الكثير من السجلات(records) فإنّ تنفيذ in( ‘1’, ‘2’, … ) على حقول غير مفهرسة(non-indexed) قد يأخذ بعض الوقت.

بعد هذه المقدمة السّريعة عن التحميل النّشط، لنرى كيف يمكننا استعمال العلاقات(relations) مع المستودعات(repositories).

تمديد فئة المستودع

سأريك الآن طريقة واحدة لكيفية استعمال العلاقات (relations) في فئات المستودع. هذا مثال لنتيجة نهائية: 

function __construct(StoreRepository $stores) {
    $this->stores = $stores;
}


public function index() {
    $stores = $this->stores->with('member', 'products')->all();

    ....
}

فكما ترى في الأعلى، هناك تابع with ليمكننا من سلسلة نموذج العلاقات. هذا التابع سيكون شبيها بالتّابع with الخاصة بمُنشئ الاستعلامات في Laravel(Laravel’s Query Builder). 

public function with($relations) {
    if (is_string($relations)) $relations = func_get_args();

    $this->with = $relations;

    return $this;
}

نحتاج الآن لربط كل علاقة(relation) إلى النموذج: 

protected function eagerLoadRelations() {
    if(!is_null($this->with)) {
        foreach ($this->with as $relation) {
            $this->model->with($relation);
        }
    }

    return $this;
}

ما تبّقى علينا الآن هو تحديث تابع المستودع all() (وأي توابع أخرى تريدها) لتستخدم التحميل النّشط: 

public function all($columns = array('*')) {
    $this->applyCriteria();
    $this->newQuery()->eagerLoadRelations();
    return $this->model->get($columns);
}

وكما ذكرت مسبقًا، يمكنك إضافة علاقات متعدّدة داخل وسيلة with(). وهذا مثال على StoresController: 

<?php namespace App\Http\Controllers;

use App\Repositories\StoreRepository;

class StoresController extends Controller {

    protected $stores;

    function __construct(StoreRepository $stores) {
        $this->stores = $stores;
    }

    public function index() {
        $stores = $this->stores->with('member', 'products')->all();

        return \View::make('stores.index')->with('stores', $stores);
    }
}

يمكنك في الـView أن تعرض أيّ بيانات بالطريقة التي تريدها. لأغراض التّجريب سيكون التالي كافيًا: 

@foreach($stores as $store)
    <h1>{{ $store->name }}</h1>
    <span>Owner: {{ $store->member->first_name . ' ' . $store->member->last_name }}</span><br>

    <h2>Products:</h2>
    @foreach($store->products as $product)
        <h3>{{$product->name}}</h3>
        <span>{{$product->short_desc}}</span><br/><br/>
        <span>Price: {{$product->price}}</span>
        <br/>
        <?php Debugbar::info('Product displayed'); ?>
    @endforeach
    <br/>
    ========================
    <br/>
@endforeach

يوجد الآن 3 استعلامات فقط كما هو متوقع:

Figure5_eager_loading.png

خاتمة

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

ترجمة -وبتصرّف- للمقال Using Repository Pattern In Laravel 5 – Eloquent Relations And Eager Loading لصاحبه Mirza Pasic

]]>433Tue, 20 Dec 2016 21:00:00 +0000التعديلات التي طرأت على هيكلة مشاريع Laravel بدءا من الإصدار 5.3https://academy.hsoub.com/programming/php/laravel/%D8%A7%D9%84%D8%AA%D8%B9%D8%AF%D9%8A%D9%84%D8%A7%D8%AA-%D8%A7%D9%84%D8%AA%D9%8A-%D8%B7%D8%B1%D8%A3%D8%AA-%D8%B9%D9%84%D9%89-%D9%87%D9%8A%D9%83%D9%84%D8%A9-%D9%85%D8%B4%D8%A7%D8%B1%D9%8A%D8%B9-laravel-%D8%A8%D8%AF%D8%A1%D8%A7-%D9%85%D9%86-%D8%A7%D9%84%D8%A5%D8%B5%D8%AF%D8%A7%D8%B1-53-r388/

يتغيّر إطار العمل Laravel باستمرار بإدراج تحديثات جديدة على كلّ إصدار من أجل تحسين تجربة التطوير وإضافة ميزات جديدة تسهّل عمل المطوّر. سنتناول في هذا الدرس، الأول من سلسلة مكونة من ستة أجزاء، التغييرات الحاصلة في هيكلة مشاريع في الإصدار 5.3 من إطار العمل Laravel.

larave-53.png

سنستخدم لأغراض الشرح مشروعي Laravel؛ الأول يعمل بالإصدار 5.2 والثاني بالإصدار 5.3 (الأخير أثناء كتابة هذا المقال). ننشئ المشروعين بمدير الاعتمادات composer على النحو التالي:

  • بالنسبة للإصدار 5.2: 

    composer create-project --prefer-dist laravel/laravel laravel52 "5.2.*"

     

  • بالنسبة للإصدار 5.3: 

    composer create-project --prefer-dist laravel/laravel laravel53 "5.3.*"

     

يظهر الإصدار المستهدَف في كل من الأمرين أعلاه (5.2 و5.3 على التوالي).

ملف المسارات Routes

تعدّ المسارات الخطوة الأولى في معالجة الطلبات التي يتلقاها التطبيق. في الإصدارات السابقة من Laravel (قبل 5.3) كانت المسارات تُضبَط في الملف app/Http/routes.php بغضّ النظر عن طبيعة الطلبات التي تتعامل معها. إن بحثت عن هذا الملف في الإصدار الجديد فلن تجده؛ إذ أنه اختفى مع إنشاء مجلّد جديد باسم routes يوجد في جذر المشروع ويحوي ملفّين:

  • ملف web.php: يحوي هذا الملف المسارات الخاصّة بواجهة الوِب. تعتمد المسارات الموجودة في هذا الملفّ على وسيط برمجي Middleware يحمل نفس الاسم (web) ويوفّر خاصيّات مثل حالة الجلسة Session state (الاحتفاظ ببيانات العميل لاستخدامها في الطلبات الواردة منه أثناء صلاحية الجلسة) والحماية من هجمات تزوير الطلب عبر الموقع Cross-site request forgery, CSRF.
  • ملف api.php: يتوجّه هذا الملف للتطبيقات التي توفّر واجهة تطبيقات برمجية Application programming interface. تعتمد المسارات الموجودة في الملف api.php على وسيط برمجي أخف من السابق (يُسمّى هذا الوسيط api)؛ إذ لا يحتوي على الخاصيّات الموجودة في الوسيط web والتي لا تحتاجها واجهات التطبيقات البرمجية.

يمكن القول إن الملف web.php معدّ للتعامل مع الطلبات ذات الحالة Stateful، بينما الملف api.php معدّ للطلبات عديمة الحالة Stateless.

من الجيد الانتباه إلى أن جميع المسارات المذكورة في الملف api تُطبَّق عليها لاحقة api. لو نظرنا إلى الملف api.php المبدئي فسنجد أن محتواه على النحو التالي: 

<?php

use Illuminate\Http\Request;


Route::get('/user', function (Request $request) {
    return $request->user();
})->middleware('auth:api');

وبالنسبة للملف web.php: 

<?php


Route::get('/', function () {
    return view('welcome');
});

إن نفذنا أمر سرد مسارات المشروع فستكون على النحو التالي:

01_route_list.png

لاحظ كيف أن Laravel أضاف تلقائيا اللاحقة api إلى المسار user/ مع تحديد الوسيط البرمجي المستخدم بـ api, auth:api.

فلنضف مسارا باسم user/ إلى الملف web.php: 

Route::get('/user', function () {
    return "1,2,3,4";
});

ثم نسرُد المسارات المتوفرة:

02_route_list.png

يظهر المسار الجديد في القائمة، ولكن بدون اللاحقة api، ومع تحديد الوسيط بـweb.

تغيير الهيكلة المبدئية للمجلدات

تخَلّص الإصدار 5.3 من Laravel من مجلدات كانت تأتي مبدئيا مع إطار العمل. يمكن ملاحظة هذا الأمرحيث تظهر، في الصورة أدناه، المجلدات الفرعية من المجلد app لكل من الإصدارين 5.2 (في اليسار) و5.3 (في اليمين).

03_folders_structure.png

نلاحظ إخفاء المجلدات Listeners، Jobs، Events و Policies. لا يعني الإخفاء المبدئي لهذه الملفات أن الوظائف المرتبطة بها لم تعد موجودة؛ بل يتعلّق الأمر بالتخفيف من المجلدات الموجودة مبدئيا وإنشائها فقط عند الحاجة لذلك. مثلا؛ إن أردنا إنشاء حدث Event باسم ContactHandlerAction فسنفّذ الأمر التالي: 

 
php artisan make:event ContactHandlerAction

إن نفذت الأمر أعلاه فستجد أن Laravel أنشأ مجلدا فرعيا في app باسم Events وأنشأ داخله الملف ContactHandlerAction.php.

04_events_folder.png

نفس الشيء بالنسبة للمستمعات Listeners: 

php artisan make:listener EmailContactListener --event="ContactHandlerAction"

05_listeners_folder.png

يظهر جليا أن Laravel 5.3 تخفّف من مجلداتٍ مبدئيا؛ إلا أنه ينشئها إن احتاج إليها.

]]>388Tue, 22 Nov 2016 11:11:00 +0000المسترجعات Accessors والمعدلات Mutators في Laravelhttps://academy.hsoub.com/programming/php/laravel/%D8%A7%D9%84%D9%85%D8%B3%D8%AA%D8%B1%D8%AC%D8%B9%D8%A7%D8%AA-accessors-%D9%88%D8%A7%D9%84%D9%85%D8%B9%D8%AF%D9%84%D8%A7%D8%AA-mutators-%D9%81%D9%8A-laravel-r365/

المسترجِعات Accessors والمعدِّلات Mutators في Laravel هي مجموعة دوالّ مخصّصة يعرّفها المستخدم لتهيئة خواص النماذج Models. تُستخدم المسترجعات لتهيئة خواصّ النموذج عند طلب الحصول عليها من قاعدة البيانات، بينما تُستخدَم المعدّلات لتهيئة الخواصّ قبل حفظ النموذج في القاعدة.

تعريف مسترجع

تُسمى الدوال المسترجعة بالصيغة ()getFooAttribute حيث Foo هو اسم الخاصيّة التي نريد تهيئتها في الدالة، مع الانتباه إلى حالة الحرف الأول من الخاصية (حرف كبير Uppercase). سيستدعي Laravel تلقائيا هذه الدالة في كلّ مرة تبحث فيها عن قيمة الخاصيّة foo. لا يقتصر استخدام المسترجعات على سلاسل المحارف، بل يمكنك استخدامها لتهيئة أي نوع من البيانات تواريخ، أثمان، …إلخ.

سنفترض أن لدينا نموذجا باسم Member (عضو) يحوي الخاصيّات التاليّة: 

first_name
last_name
email
password
last_visit
settings
created_at
updated_at

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

$user = App\Member::create([
    'first_name'  => 'mirza',
    'last_name'   => 'pasic',
    'email'       => 'mirza.pasic@bosnadev.com',
    'password'    => '!supersecretpassword!',
    'last_login'  => Carbon\Carbon::now(),
    'settings'    => ['two_factor_aut' => false, 'session_time' => 1200],
    'created_at'  => Carbon\Carbon::now(),
    'updated_at'  => Carbon\Carbon::now()
]);

يمكننا استخدام المسترجعات لتهيئة مُدخلات المستخدم: 

use Illuminate\Database\Eloquent\Model;

/**
* Class Member
* @package App
*/
class Member extends Model
{
    /**
    * التأكد من تهيئة الاسم الشخصي بعد الحصول على النموذج من قاعدة البيانات
    * 
    * @param $value
    * @return string
    */
    public function getFirstNameAttribute($value)
    {
        return ucfirst($value);
    }

    /**
    * التأكد من تهيئة الاسم العائلي بعد الحصول على النموذج من قاعدة البيانات
    * 
    * @param $value
    * @return string
    */
    public function getLastNameAttribute($value)
    {
        return ucfirst($value);
    }
}

سيعمل المسترجعان getFirstNameAttribute و getLastNameAttribute على تهيئة الحقلين first_name (الاسم الشخصي) وlast_name (الاسم العائلي) على التوالي لجعل الحرف الأول في كلّ واحد منهما يُكتب كبيرا (Uppercase)، بغضّ النظر عن الطريقة التي أدخلهما بها المستخدم.

يمكن أيضا استخدام المسترجعات لدمج خاصيّتين في النموذج لتكوّنا واحدة جديدة. يمكن مثلا تعريف الاسم الكامل full_name بناء على الاسم الشخصي والاسم العائلي: 

/**
* Get members full name
* 
* @return string
*/
public function getFullNameAttribute()
{
  return ucfirst($this->first_name) . ' ' . ucfirst($this->last_name);
}

ثم يمكننا استخدامه كما لو كان فعلا يوجد حقل باسم full_name في النموذج: 

$member = App\Member::find(1);

echo $member->full_name;

يمكنك إن أردت استخدام المسترجعات على أنواع بيانات أخرى. مثلا، لتهيئة التاريخ. نستخدم في المثال التالي الدالة getLastLoginAttribute لتهيئة تاريخ آخر دخول (الحقل last_login) بحيث يظهر بالصيغة d.m.Y (يمثّل الحرف d اليوم، الحرفm الشهر وY السنة مكتوبة بأربعة أرقام): 

/**
 * Custom format for the last login date
 * 
 * @param $value
 * @return string
 */
public function getLastLoginAttribute($value)
{
    return \Carbon\Carbon::parse($value)->format('d.m.Y.');
}

ثم نستخدم الحقل last_login كما في المثال التالي: 

$member = App\Member::find(1);
echo $member->last_login;

يظهر الحقل كما يلي: 

11.07.2016.

تعريف معدل

تشبه آلية تسميّة المعدِّل تعريفَ المسترجع، مع فرق إحلال set مكان get. إذا أردنا تعريف معدِّل للخاصيّة foo فسيكون اسمُه setFooAttribute. نعود لمثال النموذج Member السابق. نريد الآن أن نتأكد من تهيئة اسم العضو قبل حفظ النموذج في قاعدة البيانات: 

/**
* التأكد من تهيئة الاسم الشخصي **قبل** حفظ النموذج
* 
* @param $value
* @return string
*/
public function setFirstNameAttribute($value)
{
    $this->attributes['first_name'] = ucfirst($value);
}

/**
* التأكد من تهيئة الاسم العائلي **قبل** حفظ النموذج
* 
* @param $value
* @return string
*/
public function setLastNameAttribute($value)
{
    $this->attributes['last_name'] = ucfirst($value);
}

ربما لاحظت أن الدالة لا ترجِع أية قيمة. ما يحدُث هو أننا نضبُط الخاصيّة بالقيمة التي نريد مباشرة. نتأكد بهذه الطريقة أن الاسمين الشّخصي والعائلي سيكونان مهيأيْن دائما بالصيغة التي نريد.

أمثلة على المسترجعات والمعدلات

رأينا في الفقرات السابقة أمثلة لاستخدامات سهلة للمسترجعات والمعدّلات؛ إلا أن هذه الدوال يمكن أن تُستخدَم لأمور أكثر تخصيصا كما سنرى في الأمثلة التالية.

حماية كلمات السّر

يمكن استخدام المعدِّلات لتجزئة كلمة السّر Password hashing قبل حفظها في قاعدة البيانات؛ مثلا: 

public function setPasswordAttribute($value) {
    $this->attributes['password'] = Hash::make($value);
}

تتأكد بهذه الطريقة أن كلمة السّر لن تُحفَظ أبدا بصيغتها المقروءة في قاعدة البيانات، وهو ما يعدّ إجراء أمنيًّا أساسيا. استخدمنا في المثال السابق صنف Hash الذي يوفّره Laravel مبدئيا، ولكن يمكنك استخدام دوال تعميّة إن أردت، مثل ()bcrypt.

الترميز بصيغة Json

إن نظرت إلى نموذج Member السابق فستجد أنه يحوي خاصيّة باسم settings تُستخدَم لحفظ تفضيلات العضو الشخصيّة وخيارات أخرى يتيحها التطبيق. يمكن استخدام مصفوفة لإدارة هذه الخيارات وحفظها في قاعدة البيانات بصيغة Json. تتيح قواعد بيانات مثل PostgreSQL نوع البيانات Json في حقول الجدول منذ زمن، كما أن MySQL أتاحت نوع البيانات هذا في الإصدار 5.7.8.

ملحوظة: دعم نوع البيانات Json في MySQL لا زال في بداياته، وقد تواجه مشاكل عند استخدامه.

بالنسبة لخاصيّة settings فسنحتاج لمعدِّل يخزّن البيانات بصيغة Json في القاعدة ومسترجِع لتحويل Json إلى مصفوفة من سلسلة محارف: 

/**
* Make sure that we get an array from JSON string 
*
* @param $value
* @return array
*/
public function getSettingsAttribute($value) {
    return json_decode($value, true);
}


/**
* Encode an array to a JSON string
* 
* @param $value
*/
public function setSettingsAttribute($value)
{
    $this->attributes['settings'] = json_encode($value);
}

المثال كاملا

في ما يلي الخطوات اللازمة لإنشاء مثال عملي يعتمد على النموذج المقدّم في هذا الدرس. نفترض وجود Laravel مثبّت بقاعدة بيانات مضبوطة.

إنشاء التهجير والنموذج 

php artisan make:model Member -m
Model created successfully.
Created Migration: 2016_07_04_020531_create_members_table

التعديل على التهجير 

public function up()
    {
        Schema::create('members', function (Blueprint $table) {
            $table->increments('id');
            $table->string('first_name');
            $table->string('last_name');
            $table->string('email');
            $table->string('password');
            $table->date('last_login');
            $table->string('settings');
            $table->timestamps();
        });
    }

التعديل على النموذج

في ما يلي الشفرة الكاملة للنموذج Member مع المسترجعات والمعدِّلات. 

<?php  namespace App;

use Illuminate\Support\Facades\Hash;
use Illuminate\Database\Eloquent\Model;

/**
* Class Member
* @package App
*/
class Member extends Model
{
    /**
    * @var array
    */
    protected $fillable = ['first_name', 'last_name', 'email', 'password', 'last_login', 'settings', 'created_at', 'updated_at'];

    /**
    * التأكد من تهيئة الاسم الشخصي بعد الحصول على النموذج من قاعدة البيانات
    *
    * @param $value
    * @return string
    */
    public function getFirstNameAttribute($value)
    {
        return ucfirst($value);
    }

    /**
    * التأكد من تهيئة الاسم العائلي بعد الحصول على النموذج من قاعدة البيانات
    *
    * @param $value
    * @return string
    */
    public function getLastNameAttribute($value)
    {
        return ucfirst($value);
    }

    /**
    * الاسم الكامل للعضو
    *
    * @return string
    */
    public function getFullNameAttribute()
    {
        return ucfirst($this->first_name) . ' ' . ucfirst($this->last_name);
    }

    /**
    * تهيئة تاريخ آخر زيارة
    *
    * @param $value
    * @return string
    */
    public function getLastLoginAttribute($value)
    {
        return \Carbon\Carbon::parse($value)->format('d.m.Y.');
    }

    /**
    *  التأكد من تهيئة الاسم الشخصي **قبل** حفظ النموذج
    *
    * @param $value
    * @return string
    */
    public function setFirstNameAttribute($value)
    {
        $this->attributes['first_name'] = ucfirst($value);
    }

    /**
    * التأكد من تهيئة الاسم العائلي **قبل** حفظ النموذج
    *
    * @param $value
    * @return string
    */
    public function setLastNameAttribute($value)
    {
        $this->attributes['last_name'] = ucfirst($value);
    }

    /**
    * تهيئة كلمة السّر **قبل** حفظها
    *
    * @param $value
    */
    public function setPasswordAttribute($value) {
        $this->attributes['password'] = Hash::make($value);
    }

    /**
    * الحصول على مصفوفة من حقل بصيغة 
    * Json
	*
    * @param $value
    * @return array
    */
    public function getSettingsAttribute($value) {
        return json_decode($value, true);
    }


    /**
    * الترميز بصيغة 
    * Json
	* قبل حفظ الحقل
    * @param $value
    */
    public function setSettingsAttribute($value)
    {
        $this->attributes['settings'] = json_encode($value);
    }

}

استخدام النموذج 

Route::get('members', function() {
    $user = App\Member::create([
        'first_name'  => 'mirza',
        'last_name'   => 'pasic',
        'email'       => 'mirza.pasic@bosnadev.com',
        'password'    => '!supersecretpassword!',
        'last_login'  => Carbon\Carbon::now(),
        'settings'    => ['two_factor_aut' => true, 'session_time' => 1200],
        'created_at'  => Carbon\Carbon::now(),
        'updated_at'  => Carbon\Carbon::now()
    ]);

    $member = App\Member::find(1);
    echo $member->last_login . '<br>';
    echo $member->full_name . '<br>';
});

ترجمة -وبتصرّف- للمقال Laravel Accessors and Mutators لصاحبه Mirza Pasic.

]]>365Mon, 24 Oct 2016 03:04:00 +0000نشر تطبيقات Laravel على منصة Herokuhttps://academy.hsoub.com/programming/php/laravel/%D9%86%D8%B4%D8%B1-%D8%AA%D8%B7%D8%A8%D9%8A%D9%82%D8%A7%D8%AA-laravel-%D8%B9%D9%84%D9%89-%D9%85%D9%86%D8%B5%D8%A9-heroku-r357/

اشتهر استخدام منصة Heroku السحابية ضمن مجتمع مطوري Ruby on Rails ونالت فيه شعبية واسعة؛ إلا أن الخدمة لم تقتصر على مطوري Ruby وما يدور حولها بل تجاوزتهم إلى تقديم الدعم للغات برمجة مثل Node.js ،Java و PHP؛ من بين أخرى.

توفّر Heroku خطّة اشتراك مجانية يمكن استخدامها لإدارة مشاريع صغيرة جدا أو لأغراض الاختبار. سنشرح في هذا الدرس كيفية الاستفادة من Heroku عبر هذه الخطة لنشر Deploying تطبيقات Laravel.

deploy-laravel-to-heroku.png

إنشاء حساب على 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 ستجد سجلا بالإجراءات السابقة.

01_Laravel_Heroku.png

هذا كلّ ما في الأمر؛ اكتمل نشرُ تطبيقك الآن ويمكنك الوصول إليه على الرابط المذكور أعلاه. يجب أن تظهر صفحة Laravel المبدئية.

02_Laravel_Heroku.png

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

تهجير قاعدة البيانات

نشرنا في الخطوات السابقة تطبيق 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.

]]>357Sat, 08 Oct 2016 17:20:00 +0000تثبيت Homestead وإعداده لتشغيل تطبيقات Laravelhttps://academy.hsoub.com/programming/php/laravel/%D8%AA%D8%AB%D8%A8%D9%8A%D8%AA-homestead-%D9%88%D8%A5%D8%B9%D8%AF%D8%A7%D8%AF%D9%87-%D9%84%D8%AA%D8%B4%D8%BA%D9%8A%D9%84-%D8%AA%D8%B7%D8%A8%D9%8A%D9%82%D8%A7%D8%AA-laravel-r361/

إن كنت تخطّط لتطوير مشروع على Laravel فإطار العمل - ولغة البرمجة PHP - لن يكونا كلّ ما تحتاجه للبدء في العمل؛ بل ستكون بحاجة إلى برنامج لإدارة قاعدة البيانات (مثلا MySQL أو PostgreSQL)، خادوم وِب (Nginx أو Apache) وربما تقنيات أخرى حسب الحاجة. قد يمثّل إعداد بيئة عمل بكلّ هذه التقنيات الكثير من العمل المرهق بالنسبة لك؛ خصوصا إن كنت ممّن يفضّل كتابة الشفرة البرمجية بدلا من التعامل مع مشاكل الإعدادات.

مثّل ظهور الآلات الافتراضية Virtual machines, VM وانتشارها في السنوات الأخيرة فرصة للتغلب على الكثير من مشاكل الإعدادات. الآلات (الأجهزة) الافتراضية هي مجموعة برمجيات تعمل على نظام تشغيل لمحاكاة عمل جهاز فعلي. يمكن بهذه الطريقة مثلا، تشغيل أوبونتو لينكس داخل وندوز أو العكس. كما تمكن تجربة نظام مخصّص للخواديم داخل حاسوب شخصي؛ زيادة على أمور أخرى كثيرة. تتيح الآلات الافتراضية إعداد نظام تشغيل مخصّص، تثبيت برامج عليه، إعدادها؛ ثم توزيع النظام بعد ذلك للمهتمين للبدء في استعماله كما هو. استفاد مطورو Laravel من تقنية الآلات الافتراضية وأنشؤوا نظاما مخصّصا معدّا بجميع ما تحتاجه للبدء في التطوير على Laravel؛ أعطى فريق Laravel لهذه الآلات الافتراضية اسم Homestead. تستخدم Homestead برنامج إدارة الإعدادات Vagrant لتشغيلها.

تأتي آلة Homestead معدّة بنظام تشغيل أوبونتو 14.04، لغة البرمجة PHP 7، خادوم وِب Nginx، نظامي إدارة قواعد بيانات MySQL وPostgreSQL وأدوات متفرقة أخرى. لا يتطلّب إعداد Vagrant لتشغيل Homestead الكثير من الوقت، كما أنه يعمل على OSX، لينكس ووندوز.

تثبيت Homestead

الخطوة الأولى لتثبيت Homestead هي تثبيت VirtualBox وVagrant على التوالي. يمكن من موقعي البرنامجيْن الحصولُ على مثبّتات Installers سهلة لأنظمة التشغيل المختلفة. افتح بعد تثبيت VirtualBox وVagrant سطر الأوامر ونفّذ الأمر التالي (قد  يستغرق تنزيل الآلة الافتراضية وقتا، حسب سرعة اتصالك بالإنترنت): 

$ vagrant box add laravel/homestead
==> box: Loading metadata for box 'laravel/homestead'
    box: URL: https://atlas.hashicorp.com/laravel/homestead
This box can work with multiple providers! The providers that it
can work with are listed below. Please review the list and choose
the provider you will be working with.

1) virtualbox
2) vmware_desktop

Enter your choice: 1
==> box: Adding box 'laravel/homestead' (v0.4.4) for provider: virtualbox
    box: Downloading: https://vagrantcloud.com/laravel/boxes/homestead/versions/0.4.4/providers/virtualbox.box
==> box: Successfully added box 'laravel/homestead' (v0.4.4) for 'virtualbox'!

يثبت الأمر أعلاه صندوق Homestead. يُستخدَم المصطلح صندوق Box للإشارة إلى حزمة في Vagrant. يعدّ مجتمع Vagrant آلات افتراضية بأنظمة تشغيل ثُبتت عليها برامج مختلفة - حسب الغرض - لتكون الآلة جاهزة للعمل فورا. يمكنك الحصول على لائحة بالآلات الافتراضية الشائعة الاستخدام التي يشرف مجتمع Vagrant على صيانتها عبرهذا الرابط.

ثم ننتقل لتثبيت Homestead باستنساخ مستودع Github في المجلّد الشخصي للمستخدم كالتالي: 

cd ~
git clone https://github.com/laravel/homestead.git Homestead

ثم ننفذ، بعد نسخ المستودع، الأمر التالي الذي ينشئ ملفّ الإعداد Homestead.yaml ضمن مجلّد مخفي باسم homestead.: 

 
bash init.sh

ملحوظة: يجب تنفيذ الأمر من داخل المجلد Homestead.

إعداد Homestead

تحدّد التعليمة provider في ملفّ الإعداد homestead/Homestead.yaml. المزوّد الذي سيستخدمه Vagrant؛ إما virtualbox أو vmware_desktop. في حالتنا اخترنا virtualbox.

الخطوة التالية هي إعداد مجلّد المشروع الذي ستتشاركه مع الآلة الافتراضية. تتطلّب مشاركةُ مجلد المشروع تحديد مكان مفتاح SSH العمومي الخاص بك. تُستخدَم التعمية Encryption المعتمدة على المفاتيح العموميّة والخصوصيّة لتأمين تشارك المجلّد مع الآلة الافتراضية.

افتح ملفّ Homestead.yaml الموجود في مجلّد homestead. وحدّد مكان السّطر التالي: 

 
authorize: ~/.ssh/id_rsa.pub

إن كنت تعمل على لينكس أو OS X فلن تحتاج - على الأرجح - للتعديل على هذا السطر، نظرا لكون الملفات الخاصة بمفاتيح SSH تُخزَّن عادة في مجلّد باسم ssh. ضمن مجلّد المستخدم. إن استخدمتَ مجلدا مخصّصا لمفاتيح SSH فسيتوجّب عليك تحديث المسار بمقتضى ذلك. أما إذا كنت تستخدم وندوز فستحتاج إلى تحديث السطر ليوافق صيغة المسارات في وندوز، مثلا كالتالي: 

 
authorize: c:/Users/wjgilmore/.ssh/id_rsa.pub

ملحوظة: استخدم برنامج PuTTY على وندوز لتوليد مفاتيح التعميّة.

نحتاج الآن لتعديل قائمة المجلدات في ملفّ إعداد Homestead لتعيين مسار التطبيق. توجد فقرتان في ملفّ الإعدادات تتوليان التعامل مع مجلدات التطبيق وهما folders وsites. تبدو الفقرتان مبدئيا على النحو التالي: 

folders:
    - map: ~/Code
    to: /home/vagrant/Code

sites:
    - map: homestead.app
    to: /home/vagrant/Code/Laravel/public

تعرفّ الخاصيّة map في الفقرة folders المسار الذي توجد عليه ملفات مشروع Laravel الذي تعمل عليه. القيمة المبدئية لهذه الخاصيّة هي Code/~؛ بمعني أن Homestead يتوقّع وجود ملفات مشروعك ضمن مجلّد باسم Code متفرّع من المجلّد الشخصي للمستخدم. يمكنك تغيير قيمة هذه الخاصيّة حسب رغبتك؛ لكن تذكر أن المسار يجب أن يحيل إلى المجلد الجذر لمشروع Laravel. بالنسبة للخاصية to في الفقرة folders فتعرّف مسار المجلّد الذي ستُزامن معه محتويات المجلّد المعرَّف في الخاصيّة map السابقة. يمكن للآلة الافتراضية قراءة محتويات المجلد المعرَّف على المسار to عكس محتويات المجلّد المعرَّف في map. نتيجة لهذا الإعداد يُزامن محتوى المجلد الأخير (المعرَّف في to) تلقائيا مع محتوي المجلّد الأول (المعرَّف في map)؛ لتتمكن الآلة الافتراضية من قراءته.

ملحوظة: من الأفضل ألا تحتوي أسماء المجلدات على مسافات.

توجد في الفقرة sites خاصيتان تحملان نفس الاسميْن السابقيْن، map وto. تعرّف الخاصيّة map في الفقرة sites اسم النطاق الذي ستستخدمه للوصول إلى التطبيق؛ في المثال أعلاه تصل إلى التطبيق بكتابة homestead.app في شريط عنوان المتصفح. أما الخاصيّة to فتعرّف مجلّد الوِب الجذر في مشروع Laravel، وهو مبدئيا المجلّد public الموجود في المجلّد الجذر للمشروع.

ملحوظة: المسارات المحدّدة في خاصيّة to في كلتا الحالتين هي بالنسبة لمجلدات موجودة داخل الآلة الافتراضية.

سننشئ مجلّدا باسم app.homestead نخصّصه للمشروع الذي سنعمل عليه؛ نضيف مسار هذا المجلّد إلى الخاصية map في الفقرة folders التي تصبح كالتالي: 

folders:
    - map: /home/zeine77/Documents/projects/app.homestead
    to: /home/vagrant/Code

ثم ننشئ داخل المجلد app.homestead مجلدا باسم Laravel وداخل هذا الأخير مجلدا باسم public حتى نوافق مسار المجلد home/vagrant/Code/Laravel/public/ الذي يشير إليه اسم النطاق (الخاصيّة to في الفقرة sites).

ملحوظة: تذكّر أن المجلّد home/vagrant/Code/ هو نسخة طبق الأصل من المجلّد home/zeine77/Documents/projects/app.homestead/، ولكنه موجود داخل الآلة الافتراضية. يعني هذا أن المجلّد /Laravel/public المستخدَم في الخاصيّة to من الفقرة sites (القيمة /home/vagrant/Code/Laravel/public/) يجب أن يكون موجودا في الأصل (أي في المجلّد home/zeine77/Documents/projects/app.homestead/). هذا هو السبب الذي جعلنا ننشئ المجلد Laravel/public بالطريقة المذكورة أعلاه.

سننشئ الآن داخل المجلّد public ملفا باسم index.php ونضع فيه الشفرة التالية: 

 
<?php echo "Hello from Homestead!"; ?>

احفظ الملفّ ثم أغلقه. يعني هذا أننا عند تشغيل الآلة الافتراضية والدخول إلى العنوان homestead.app ستظهر لدينا العبارة !Hello from Homestead.

الخطوة الأخيرة قبل الانتقال لتشغيل الآلة الافتراضية هي تعديل ملف المضيفات ليتعرّف النظام على العنوان homestead.app. يوجد ملف المضيفات على المسار etc/hosts/ بالنسبة للينكس و C:\Windows\System32\drivers\etc\hosts بالنسبة لوندوز. أضف السّطر التالي إلى الملفّ: 

 
192.168.10.10       homestead.app

ملحوظة: تأكّد من موافقة العنوان (192.168.10.10 في السطر أعلاه) لعنوان IP الموجود في بداية الملفّ Homestead.yaml.

حان الوقت - بعد إكمال الخطوات المشروحة أعلاه - لتشغيل الآلة الافتراضية وتجربة عمل الإعدادات. ننتقل إلى المجلد Homestead (حيثُ نسخنا المشروع من Github) ثم ننفّذ الأم التالي: 

 
$ vagrant up

يستغرق تشغيل الآلة الافتراضية بعض الوقت وتظهر مخرجات الأمر: 

Bringing machine 'default' up with 'virtualbox' provider...
==> default: Importing base box 'laravel/homestead'...
==> default: Matching MAC address for NAT networking...
==> default: Checking if box 'laravel/homestead' is up to date...
(...)
==> default: Preparing network interfaces based on configuration...
    default: Adapter 1: nat
    default: Adapter 2: hostonly
==> default: Forwarding ports...
    default: 80 (guest) => 8000 (host) (adapter 1)
    default: 443 (guest) => 44300 (host) (adapter 1)
    default: 3306 (guest) => 33060 (host) (adapter 1)
    default: 5432 (guest) => 54320 (host) (adapter 1)
    default: 22 (guest) => 2222 (host) (adapter 1)
(...)
==> default: nginx stop/waiting
==> default: nginx start/running, process 1940
==> default: php7.0-fpm stop/waiting
==> default: php7.0-fpm start/running, process 1959
(...)
==> default: Running provisioner: shell...
default: Running: /tmp/vagrant-shell20160628-13381-s5ikfi.sh

يمكنك الآن فتح المتصفّح وتجربة عمل الإعدادت بزيارة الرابط http:homestead.app. إن جرت الأمور على ما يُرام فستظهر العبارة التالية في المتصفّح: 

 
Hello from Homestead !

إن تعذّر تشغيل الآلة الافتراضية (خطأ في مخرجات الأمر vagrant up) فتأكد من ملف الإعداد Homestead.yaml. إن اشتغلت الآلة ولم تستطع إظهار محتوى الصفحة فتأكد من إعدادات المضيف، وخصوصا عنوان IP وموافقته للعنوان الموجود في ملفّ الإعداد Homestead.yaml؛ ينبغي التأكد كذلك من المسارات ومن حالة كتابة الأحرف (كبيرة أو صغيرة).

أنشأنا المجلّد Laravel/public وأضفنا إليه الملفّ index.php للتأكد من أن Homestead يعمل من دون مشاكل؛ لكن هدفنا هو استخدام Homestead لعرض مشاريع بـLaravel؛ وهو ما سنعدّه بعد قليل. يمكننا الآن توقيف عمل الآلة الافتراضية بتنفيذ الأمر (من داخل المجلد Homestead): 

$ vagrant destroy --force
==> default: Forcing shutdown of VM...
==> default: Destroying VM and associated drives...

ثم حذف المجلّد Laravel (وبالتالي المجلد public المتفرع منه).

الولوج إلى الآلة الافتراضية عن طريق SSH

نظرا لكون Homestead مبني على توزيعة أوبونتو فيمكن الولوج إليه عن طريق SSH، تماما كما هي الحال بالنسبة لأي خادوم آخر. قد تودّ الدخول إلى الآلة الافتراضية لأسباب منها على سبيل المثال تغيير إعدادات قاعدة البيانات أو خادوم الوِب، إضافة برامج جديدة أو لإجراء تعديلات أخرى. استخدم الأمر التالي، بعد تشغيل الآلة الافتراضية ، للدخول عن طريق SSH: 

 
$ vagrant ssh

تظهر بعد تنفيذ الأمر رسالة ترحيبية ومحثّ Prompt أوامر: 

Welcome to Ubuntu 14.04.4 LTS (GNU/Linux 3.19.0-25-generic x86_64)

* Documentation:  https://help.ubuntu.com/
vagrant@homestead:~$

سيُسجَّل دخولك باسم المستخدم vagrant؛ يمكنك بعدها تنفيذ أوامر لينكس حسب الحاجة. ستجد أنه يوجد مجلّد باسم Code داخل المجلّد الشخصي للمستخدم vagrant.
نفّذ الأمر exit إن أردت الخروج من الآلة الافتراضية.

إنشاء تطبيق Laravel

تأكدنا في الخطوات السابقة من إعداد Homestead وأنه جاهز للعمل. يمكننا الآن إنشاء مشروع Laravel على Homestead. لذا سنستخدم composer لإنشاء مشروع Laravel جديد داخل المجلّد app.homestead. اختر اسما مناسبا للمشروع؛ مثلا demo: 

 
$ composer create-project laravel/laravel demo

لدينا الآن مشروع Laravel على المسار home/zeine77/Documents/projects/app.homestead/demo/؛ ينبغي أن نعدّل ملفّ الإعداد Homestead.yaml ليشير إلى هذا المجلد. نفتح الملفّ لتحريره؛ ونغيّر قيمة الخاصيّة to ضمن الفقرة sites. القيمة القديمة هي التالية (أعددناها في خطوة سابقة): 

sites:
    - map: homestead.app
    to: /home/vagrant/Code/Laravel/public

لتصبح كالتالي: 

sites:
    - map: homestead.app
    to: /home/vagrant/Code/demo/public

احفظ الملفّ ثم أغلقه. نعود لمجلّد Homestead وننفذ الأمر التالي لاعتماد التعديلات (إن كانت الآلة الافتراضية تعمل): 

 
$ vagrant provision

أما إن لم تكن الآلة الافتراضية تعمل فيجب تشغيلها: 

 
$ vagrant up

انتظر اعتماد التعديلات أو تشغيل الآلة الافتراضية؛ ثم توجّه إلى المتصفّح وأدخل العنوان http://homestead.app، وستظهر الصفحة المبدئية لمشروع Laravel.

01_homestead_laravel.png

خاتمة

لست ملزما بمشروع Laravel واحد على آلة Homestead؛ بل يمكنك إنشاء العدد الذي تريد. كل ما يجب عليك فعله هو تحديث قيم map وto في فقرتي folders وsites من ملف الإعداد Homestead.yaml بالمسارات المناسبة.

يمكن مثلا اتخاذ مجلد لمشاريع Laravel تستخدمه لإنشاء المشاريع الجديدة داخله ثم تعدّ الخاصيّة map في folders للإشارة إلى المجلد المشترك؛ وعند إضافة مشروع جديد تضيف نطاقا جديدا له في sites؛ مع تحديث قيمة to لتشير إلى المجلد الموافق له في المجلد المشترك كما في المثال التالي: 

folders:
    - map: /home/zeine77/Documents/projects/app.homestead
    to: /home/vagrant/Code

sites:
    - map: homestead.app
    to: /home/vagrant/Code/demo/public

    - map: anotherhomestead.app
    to: /home/vagrant/Code/anotherdemo/public

لا تنس تحديث ملف المضيفات (hosts) بإضافة اسم النطاق الجديد (anotherhomestead.app) في المثال أعلاه: 

 
192.168.10.10   anotherhomestead.app

ترجمة - بتصرّف - لمقال Installing and Configuring Homestead 2.0 for Laravel 5. حقوق المقال محفوظة لصاحبه W. Jason Gilmore.

]]>361Wed, 28 Sep 2016 11:19:00 +0000دليل مطوّري PHP للبدء في بناء تطبيقات Laravel - الجزء الثانيhttps://academy.hsoub.com/programming/php/laravel/%D8%AF%D9%84%D9%8A%D9%84-%D9%85%D8%B7%D9%88%D9%91%D8%B1%D9%8A-php-%D9%84%D9%84%D8%A8%D8%AF%D8%A1-%D9%81%D9%8A-%D8%A8%D9%86%D8%A7%D8%A1-%D8%AA%D8%B7%D8%A8%D9%8A%D9%82%D8%A7%D8%AA-laravel-%D8%A7%D9%84%D8%AC%D8%B2%D8%A1-%D8%A7%D9%84%D8%AB%D8%A7%D9%86%D9%8A-r364/

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

إضافة المهامّ

التحقّق

لدينا الاآن استمارة في العرض resources/views/tasks/index.blade.php؛ سنحتاج لإضافة شفرة إلى الدالة TaskController@store من أجل التحقّق من المُدخلات القادمة من الاستمارة ثم إنشاء مهمة جديدة. نبدأ بالتحقّق من المدخلات.

سنضع شرطا على حقل الاسم في استمارة إضافة مهمّة جديدة؛ يتمثّل الشرط في وجوب إدخال اسم للمهمة، على ألا يتجاوز طوله 255 محرفا Characters. إن لم يتحقّق الشرط نعيد المستخدم إلى الرابط tasks/ مع إضاءة المُدخلات القديمة وإظهار أخطاء: 

/**
* Create a new task.
*
* @param  Request  $request
* @return Response
*/
public function store(Request $request)
{
    $this->validate($request, [
        'name' => 'required|max:255',
    ]);

    // شفرة إنشاء المهمة 
}

تتضمّن المتحكّمات في Laravel مبدئيا السمة ValidatesRequests التي يمكن عن طريقها التحقّق من موافقة المُدخلات لشروط تُحدَّد في مصفوفة من القواعد. تأخذ دالة التحقّق validate الطّلب request$ الذي نريد التحقّق منه ومصفوفة القواعد التي نريد تطبيقها. تشير الشفرة أعلاه إلى أن الحقل name مطلوب required ويجب ألا يتجاوز طوله 255 (الشّرط max).

لن نحتاج لتحديد ما الذي سيحصُل عند إخفاق التحقّق من الطلب (مثلا عند كتابة اسم يتجاوز طوله 255 محرفا). يُوجَّه المستخدَم تلقائيا عند إخفاق التحقّق إلى المسار الذي أتى منه وستُعرَض رسائل الخطأ تلقائيا.

المتغيّر errors$

تذكّر أننا استخدمنا التعليمة ('include('common.errors@ داخل العرض tasks.index لتقديم أخطاء التحقّق عبر العرض common.errors. يمكّننا العرض common.errors من إظهار أخطاء التحقّق بسهولة وحسب نفس التنسيق في كامل التطبيق. نعرّف في ما يلي العرض resources/views/common/errors.blade.php: 

@if (count($errors) > 0)
    <!-- Form Error List -->
    <div class="alert alert-danger">
        <strong>Whoops! Something went wrong!</strong>

        <br><br>

        <ul>
            @foreach ($errors->all() as $error)
                <li>{{ $error }}</li>
            @endforeach
        </ul>
    </div>
@endif

ملحوظة: يتوفّر المتغيّر errors$ في كلّ عرض في Laravel. يحوي المتغيّر كائنا فارغا من الصّنف ViewErrorBag إن لم توجد أخطاء.

إنشاء المهمّة

ضبطنا في الفقرة السابقة آلية التحقّق؛ يمكننا الآن إكمال الدالة store في المتحكم TaskController من أجل إنشاء مهمّة جديدة. نوجِّه المستخدم بعد إنشاء المهمّة إلى الرابط tasks/. سنلجأ إلى الإمكانيّات التي توفّرها علاقات Eloquent لإنشاء المهمّة.

تتوفّر أغلب علاقات Eloquent على دالة باسم create تأخذ مصفوفة من الخاصيّات وتضبط تلقائيا قيمة المفتاح الخارجي Foreign key بالاعتماد على النماذج التي تربط بينها العلاقة، ثم تنشئ سطرا جديدا في جدول البيانات لتخزين خاصيّات الكائن.

تستخدم الشفرة التالية متغيّرالطلب request$ للحصول على المستخدم الذي طلب إنشاء المهمة ()request->user$ ثم باستخدام الدالة create في العلاقة tasks (عرّفناها سابقا في النموذج User) نعطي القيمة request->name$ (أي الاسم الّذي أدخله المستخدم في الاستمارة) للخاصيّة name في النموذج Task. ستتولّى العلاقة ()tasks تحديد قيمة معرّف المستخدم صاحب المهمة بالاعتماد على المعلومات الواردة في الطلب عن المستخدم. 

/**
* Create a new task.
*
* @param  Request  $request
* @return Response
*/
public function store(Request $request)
{
    $this->validate($request, [
        'name' => 'required|max:255',
    ]);

    $request->user()->tasks()->create([
        'name' => $request->name,
    ]);

    return redirect('/tasks');
}

لاحظ كيف أن تعريف العلاقات أتاح لنا إمكانيّة فعل الكثير من الأمور بسطر برمجي واحد تقريبا.

عرض المهامّ المخزّنة

سنحتاج للتعديل على الدالة index في المتحكّم TaskController من أجل تمرير المهامّ المخزّنة إلى العرض. تقبل الدالة view إضافة إلى اسم العرض، معطى ثانيا يحوي مصفوفة من البيانات المتوفّرة للعرض. يمكن معالجة كلّ عنصر من المصفوفة بعد تمريرها إلى العرض باستخدام متغيّر بنفس الاسم، مثلا: 

/**
* Display a list of all of the user's task.
*
* @param  Request  $request
* @return Response
*/
public function index(Request $request)
{
    $tasks = $request->user()->tasks()->get();

    return view('tasks.index', [
        'tasks' => $tasks,
    ]);
}

لكننا سنختار طريق حقن الاعتمادات التي يوفرها Laravel.

حقن الاعتمادات

يستخدم Laravel ، كما أشرنا لذلك في درس إنشاء مزود خدمة في Laravel حاويةَ خدمة Service container لإدارة الاعتمادات بين الأصناف: ماهي الأصناف التي يعتمد عليها الصّنف الجديد للعمل؟ كيف يمكنه الحصول على كائن من هذه الأصناف؟ أين يوجد الصّنف وهل سبق لإطار العمل تحميلُه إلى الذاكرة؟

إنشاء مستودع في Laravel

تمكّن المستودعات Repositories من تخليص المتحكّم من ضرورة معرفة مصدر البيانات؛ إذ تجرّد المصدر الذي تأتي منه (قاعدة بيانات، ملفّ، واجهة تطبيقات API). تساعد المستودعات - بهذه الحيلة - في زيادة قابليّة التطبيق للصيانة والاختبار.

نودّ أن نعرّف مستودعا باسم TaskRepository للوصول إلى بيانات نموذج المهمة Task. تفيد هذه الطريقة كثيرا عند تزايد حجم المشروع والحاجة لتشارك استعلامات Eloquent عبر التطبيق. سننشئ مجلدا باسم Repositories في المجلّد app. تذكّر أن Laravel يحمّل تلقائيا جميع مجلدات التطبيق؛ لذا يمكنك إنشاء المجلدات حسب الحاجة.ننشئ داخل مجلد المستودعات الصنف TaskRepository: 

<?php

namespace App\Repositories;

use App\User;

class TaskRepository
{
    /**
    * Get all of the tasks for a given user.
    *
    * @param  User  $user
    * @return Collection
    */
    public function forUser(User $user)
    {
        return $user->tasks()
                    ->orderBy('created_at', 'asc')
                    ->get();
    }
}

حقن المستودع

يمكننا الآن تمرير المستودع، بعد استدعائه، إلى مشيّد المتحكم TaskController ثم استخدامه في الدالة index. تصبح شفرة المتحكّم TaskController على النحو التالي: 

<?php

namespace App\Http\Controllers;

use App\Task;
use App\Http\Requests;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;


// استدعاء المستودع
use App\Repositories\TaskRepository;


class TaskController extends Controller
{
    /**
    * The task repository instance.
    *
    * @var TaskRepository
    */
    protected $tasks;

    /**
    * Create a new controller instance.
    *
    * @param  TaskRepository  $tasks
    * @return void
    */
    // التمرير إلى المتحكّم
    public function __construct(TaskRepository $tasks)
    {
        $this->middleware('auth');

        $this->tasks = $tasks;
    }

    /**
    * Display a list of all of the user's task.
    *
    * @param  Request  $request
    * @return Response
    */
    public function index(Request $request)
    {
    // الاستخدام في الدالة
        return view('tasks.index', [
            'tasks' => $this->tasks->forUser($request->user()),
        ]);
    }

        /**
    * Create a new task.
    *
    * @param  Request  $request
    * @return Response
    */
    public function store(Request $request)
    {
        $this->validate($request, [
            'name' => 'required|max:255',
        ]);

        $request->user()->tasks()->create([
            'name' => $request->name,
        ]);

        return redirect('/tasks');
    }
}

إظهار المهامّ

يمكننا، بعد تمرير البيانات إلى العرض tasks/index.blade.php من المتحكّم، إظهار المهامّ في جدول. تُستخدَم التعليمة foreach@ في قوالب Blade لكتابة حلقات تكرارية يُحوّلها Laravel شفرة PHP.

ملحوظة: سبق لنا في الجزأ الأول من الدرس تعريف استمارة إنشاء مهمة جديدة. توضع الشفرة أدناه مكان التعليق الأخير في قالب tasks/index.blade.php الذي أنشأناه سابقا. 

    @if (count($tasks) > 0)
        <div class="panel panel-default">
            <div class="panel-heading">
                Current Tasks
            </div>

            <div class="panel-body">
                <table class="table table-striped task-table">

                    <!-- عناوين الجدول -->
                    <thead>
                        <th>Task</th>
                        <th> </th>
                    </thead>

                    <!-- المهام الموجودة -->
                    <tbody>
                        @foreach ($tasks as $task)
                            <tr>
                                <!-- اسم المهمة -->
                                <td class="table-text">
                                    <div>{{ $task->name }}</div>
                                </td>

                                <td>
                                    <!-- سنضع هنا الشفرة الخاصة بحذف مهمة -->
                                </td>
                            </tr>
                        @endforeach
                    </tbody>
                </table>
            </div>
        </div>
    @endif
    </div>
   </div>

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

حذف المهام

زرّ حذف مهمة

تركنا في العرض tasks/index.blade.php تعليقا للدلالة على المكان المفترض لزرّ حذف مهمة. سنضيف الآن، لكلّ سطر في جدول المهامّ، زرّا يمكّن من حذف المهمة الموجودة في السطر. يُرسَل، عند النقر على زرّ الحذف، طلب بإجراء DELETE إلى المسار task/، يستقبل المسار الطلب ويحيله إلى الدالة destroy في المتحكّم TaskController. نعدّل العرض tasks/index.blade.php بتعديل شفرة أسطُر الجدول لتصبح على النحو التالي: 

<tr>
    <!-- اسم المهمة -->
    <td class="table-text">
        <div>{{ $task->name }}</div>
    </td>

    <!-- زرّ حذف المهمة -->
    <td>
        <form action="{{ url('task/'.$task->id) }}" method="POST">
            {{ csrf_field() }}
            {{ method_field('DELETE') }}

            <button type="submit" id="delete-task-{{ $task->id }}" class="btn btn-danger">
                <i class="fa fa-btn fa-trash"></i>Delete
            </button>
        </form>
    </td>
</tr>

لاحظ أن الاستمارة في خلية الجدول حيث يوجد زرّ الحذف تستخدم الإجراء POST بينما نجيب على الطلب بمسار يستخدم الإجراء DELETE. لا تسمح الاستمارات في HTML باستخدام سوى الإجراءيْن POST وGET، أي أننا يجب أن نجد طريقة لإرسال طلب بإجراء DELETE. يكمُن الحل في تنفيذ الدالة ('method_field('DELETE داخل الاستمارة. تولّد هذه الدالة حقل إدخال input مخفيّا يتعرّف عليه Laravel ويستخدمه في إلغاء الإجراء المستخدَم في طلب HTTP. يبدو الحقل المولَّد كالتالي: 

 
<input type="hidden" name="_method" value="DELETE">

ربط النموذج والمسار

نحن الآن جاهزون لتعريف الدالة destroy في المتحكّم TaskController: 

/**
* Destroy the given task.
*
* @param  Request  $request
* @param  Task  $task
* @return Response
*/
public function destroy(Request $request, Task $task)
{
    //
}

سنلقي، قبل أن نكمل تعريف الدالة destroy، نظرة على المسار الخاصّ بحذف مهمة: 

 
Route::delete('/task/{task}', 'TaskController@destroy');

نظرا لكون المتغيّر {task} في المسار يوافق المتغيّر task$ في دالة المتحكم فإن Laravel سيربط تلقائيا بين الاثنين ويحقن كائنا مناسبا من النموذج Task في المسار؛ أي أن الكائن سيكون متاحا للمتحكّم لتنفيذ العمليات عليه.

التصريح

لدى المتحكّم الآن نسخة من نموذج المهمة Task لاستخدامه في الدالة destroy، إلا أننا لسنا متأكدين من أن المستخدم هو فعلا صاحب المهمة التي طلب حذفها. يمكن، على سبيل المثال، تمرير معرّف عشوائي إلى الرابط {tasks/{task، وستحذف الدالة المهمة ذات المعرّف {task}، إن وُجدت. نستخدم قدرات إدارة التصريحات Authorization في Laravel لحلّ هذه المشكلة، والتأكد من أن المستخدَم المُسجَّل هو فعلا صاحب المهمة التي يطلُب حذفها.

إنشاء سياسة تصريح

يستخدم Laravel سياسات Policies لتنظيم التصريحات في أصناف صغيرة وسهلة. تتعلّق كلّ سياسة - عادة - بنموذج. نستخدم artisan لإنشاء سياسة تصريحات للنموذج Task كالتالي: 

 
php artisan make:policy TaskPolicy

سينشئ الأمر ملفا باسم TaskPolicy.php على المسار /app/Policies.

نضيف دالة باسم destroy إلى سياسة التصريح TaskPolicy. تتلقى هذه الدالة كائنا من صنف User وآخر من صنف Task، ثمّ تتحقّق من أن معرّف المستخدم يطابق الحقل user_id في المهمة. تُرجع الدالة destroy في الصّنف TaskPolicy قيمة منطقية (falseأو true)، كما هي الحال في جميع دوال سياسات التصريح: 

<?php

namespace App\Policies;

use App\User;
use App\Task;
use Illuminate\Auth\Access\HandlesAuthorization;

class TaskPolicy
{
    use HandlesAuthorization;

    /**
    * Determine if the given user can delete the given task.
    *
    * @param  User  $user
    * @param  Task  $task
    * @return bool
    */
    public function destroy(User $user, Task $task)
    {
        return $user->id === $task->user_id;
    }
}

نحتاج الآن لإخبار Laravel بأن سياسة التصريح TaskPolicy تنطبق على النموذج Task. يتمّ هذا الأمر عبر إضافة عنصر جديد إلى خاصيّة policies$ في مزوّد خدمات الاستيثاق app/Providers/AuthServiceProvider.php. سيعرف Laravel بهذه الطريقة سياسة التصريح التي يجب عليه استخدامها للسماح بإجراء مّا (أو رفضه) على النموذج Task: 

/**
* The policy mappings for the application.
*
* @var array
*/
protected $policies = [
'App\Task' => 'App\Policies\TaskPolicy',
];

السماح بحذف المهمة

سياسة التصريح جاهزة، ويمكننا بالتالي استخدامها في المتحكّم TaskController. يمكن لجميع المتحكمات في Laravel استخدام الدالة authorize التي توفّرها السمة AuthorizesRequest: 

/**
* Destroy the given task.
*
* @param  Request  $request
* @param  Task  $task
* @return Response
*/
public function destroy(Request $request, Task $task)
{
    $this->authorize('destroy', $task);

    // حذف المهمة
}

المعطى الأوّل المُمرَّر للدالة authorize هو اسم الدالة التي نريد استدعاءها في سياسة التصريح؛ المعطى الثاني هو الكائن الذي نريد التعامل معه. تذكّر أننا أخبرنا Laravel للتو أن سياسة التصريح TaskPolicy تنطبق على النموذج Task، أي أن إطار العمل يعرف في أي سياسة تصريح سيبحث عن الدالة التي حدّدنا اسمها في المعطى الأول المُمرَّر للدالة authorize. بالنسبة للمستخدم فإن المستخدم الحالي سيُرسَل تلقائيا إلى الدالة destroy في الصّنف TaskPolicy. إن تحقّق الشرط (المستخدم صاحب المهمة هو من طلب حذفها) فسيستمرّ تنفيذ الدالة destroy في المتحكّم TaskController بصورة طبيعية؛ وإلا فسينطلق استثناء Exception برمز الخطأ 403 (غياب التصريح) وتظهر صفحة خطأ.

ملحوظة: ليست هذه هي الطريقة الوحيدة للتخاطب مع خدمات التصريح التي يوفرها Laravel.

حذف المهمة

أخذنا الاحتياطات اللازمة، ويمكننا الآن إضافة الشفرة الخاصة بحذف مهمة من قاعدة البيانات. نستخدم دالة delete التي تتوفّر عليها نماذج Eloquent؛ ثم نوجّه المستخدم بعد حذف المهمة إلى المسار tasks/. تصبح الدالة destroy في المتحكّم TaskController كما يلي: 

/**
* Destroy the given task.
*
* @param  Request  $request
* @param  Task  $task
* @return Response
*/
public function destroy(Request $request, Task $task)
{
    $this->authorize('destroy', $task);

    $task->delete();

    return redirect('/tasks');
}

ترجمة - بتصرّف - للجزء الثاني من مقال Intermediate Task List.

]]>364Tue, 13 Sep 2016 11:16:00 +0000أساسيات التحقق من المدخلات في Laravelhttps://academy.hsoub.com/programming/php/laravel/%D8%A3%D8%B3%D8%A7%D8%B3%D9%8A%D8%A7%D8%AA-%D8%A7%D9%84%D8%AA%D8%AD%D9%82%D9%82-%D9%85%D9%86-%D8%A7%D9%84%D9%85%D8%AF%D8%AE%D9%84%D8%A7%D8%AA-%D9%81%D9%8A-laravel-r352/

كان من الشائع في بدايات التطوير للوب كتابةُ الاستمارات بوسوم HTML ثم إضافة شفرة مخصَّصة للتأكد من مُدخَلات الزائر. وفّرت لغة البرمجة PHP بعد ذلك دوالَّ معيارية للتحقّق من المُدخلات؛ خفّفت هذه الدوّال قليلا من العبء على المطوِّر إلا أنها تركت له مهمّة تعريف طريقة للتحقّق من المُدخلات ومن ثمّ معالجتها أو إشعار الزائر بالبيانات غير الصالحة وعرض الاستمارة من جديد. يزيح Laravel هذه المتاعب بتوفير شيفرة للتحقّق وطريقة للتعامل مع المُدخلات.

يقدّم هذا المقال دليلا لكيفيّة إنشاء استمارات والتحقّق من مدخلات الزائر في Laravel. سنأخذ مثالا لإضافة تصنيف Category ضمن جدول تصنيفات Categories في تطبيق؛ يمكن أن يتعلّق الأمر بتصنيف منشورات مدوّنة، منتجات متجر أو أي شيء مماثل.

laravel-input-validation.png

تهيئة تطبيق Laravel

نفترض أن Laravel مثبَّت وجاهز للعمل مع قاعدة البيانات. نهيّئ التطبيق قبل أن نشرع في إنشاء الاستمارة وأدوات التحقّق المصاحبة لها.

إنشاء نموذج التصنيف والتهجير الموافق له

سيتكون نموذج التصنيف من حقل للاسم إضافة إلى حقل المعرّف id والأختام الزمنية Timestamps. نستخدم artisan لتوليد النموذج والتهجير: 

$ php artisan make:model Category -m
Model created successfully.
Created Migration: 2016_06_13_010501_create_categories_table

ثم نفتح ملفّ التهجير (داخل المجلّد database/migrations) ونحدّث الدالة up على النحو التالي: 

public function up()
{
  Schema::create('categories', function (Blueprint $table) {
      $table->increments('id');
      $table->string('name');
      $table->timestamps();
  });
}

ثم ننفّذ التهجير: 

$ php artisan migrate
Migration table created successfully.
Migrated: 2014_10_12_000000_create_users_table
Migrated: 2014_10_12_100000_create_password_resets_table
Migrated: 2016_06_13_010501_create_categories_table

ننتقل الآن للعمل على المتحكّم Controller الذي سيكون المسؤول عن معالجة محتوى الاستمارة.

إنشاء المتحكم وتعريف المسارات

نستخدم أداة artisan لإنشاء المتحكّم الذي سنستخدمه - من بين أمور أخرى - لعرض النموذج ومعالجة بياناته: 

$ php artisan make:controller CategoriesController.php --resource
Controller created successfully.

ينشئ أمر make:controller عند استخدام المعطى resource--متحكّما بدوال update، edit، store، create، show``index وdestroy. راجع درس أساسيات بناء التطبيقات في إطار العمل Laravel 5 للمزيد عن هذه الدوال.

بقي لنا تعريف المسارات في الملفّ app/Http/routes.php؛ نستخدم Route::resource لهذا الغرض:  

Route::resource('categories', 'CategoriesController');

إنشاء العروض Views

نركّز لأغراض هذا الدّرس على الدالتيْن create وstore المسؤولتيْن على التوالي عن عرض الاستمارة وتخزين بياناتها (في حال تجاوز اختبار التحقّق؛ كما سنرى). تبدو الدالتان لحدّ الساعة فارغتيْن: 

public function create()
{
    //
}

public function store(Request $request)
{
    //
}

...

نحدّث الدالة create كالتالي: 

public function create()
{
    return view('categories.create');
}

أي أننا نطلُب تقديم العرض create.blade.php الموجود في المجلّد resources/views/categories. ننشئ المجلّد categories وننشئ بداخله الملفّ create.blade.php. سنكتفي الآن بإضافة الوسوم التالية إلى ملفّ العرض: 

<h1>Create a Category</h1>

يمكنك بعد حفظ الملفّ زيارة الرابط categories/create/ وسيظهر العنوان أعلاه.

إنشاء استمارة في Laravel

نريد أن نعرض للزائر استمارة لملئها؛ يمكن أن ننشئ هذه الاستمارة بكتابة وسوم HTML المطلوبة في ملفّ العرض create؛ إلا أنه يمكننا الاستفادة من حزمة laravelcollective/html لتولّي هذه المهمّة. نضيف الحزمة إلى مشروع Laravel بتنفيذ الأمر التالي داخل مجلّد المشروع: 

$ composer require laravelcollective/html

ثم نفتح ملفّ الإعداد config/app ونضيف السطر التالي إلى مصفوفة providers: 

Collective\Html\HtmlServiceProvider::class,

لتبدو المصفوفة كالتالي (نزعنا بعض محتويات المصفوفة للاختصار): 

'providers' => [
        ...
    App\Providers\AuthServiceProvider::class,
    App\Providers\EventServiceProvider::class,
    App\Providers\RouteServiceProvider::class,
    Collective\Html\HtmlServiceProvider::class,
]

نكمل مع نفس الملفّ بالانتقال إلى المصفوفة aliases التي نضيف إليها السّطر التالي: 

  'Form' => Collective\Html\FormFacade::class

لتصبح كما يلي: 

'aliases' => [
    ...
    'URL' => Illuminate\Support\Facades\URL::class,
    'Validator' => Illuminate\Support\Facades\Validator::class,
    'View' => Illuminate\Support\Facades\View::class,
    'Form' => Collective\Html\FormFacade::class
]

احفظ الملفّ.

أكملنا تثبيت الحزمة وإعدادها. نعيد فتح ملفّ العرض create ونعدّل محتواه ليصبح على النحو التالي: 

<h1>Create a Category</h1>

{!! Form::open(
array(
    'route' => 'categories.store', 
    'class' => 'form')
) !!}

@if (count($errors) > 0)
<div class="alert alert-danger">
    There were some problems adding the category.<br />
    <ul>
        @foreach ($errors->all() as $error)
            <li></li>
        @endforeach
    </ul>
</div>
@endif

<div class="form-group">
    {!! Form::label('Category') !!}
    {!! Form::text('name', null, 
    array(
        'class'=>'form-control', 
        'placeholder'=>'List Name'
    )) !!}
</div>

<div class="form-group">
    {!! Form::submit('Create Category!', 
    array('class'=>'btn btn-primary'
    )) !!}
</div>
{!! Form::close() !!}
</div>

تضيف حزمة laravelcollective/html تعليمات خاصّة بإنشاء الاستمارات إلى نظام Blade للقوالب.

  • يشير مسار الاستمارة إلى categories/store لأن دالّة store في المتحكّم CategoriesController هي التي ستتولّى معالجة بيانات الاستمارة. تستخدم التعليمة Form::open مبدئيا إجراء POST؛ لذا لا حاجة لتعيينه.
  • يُستخدَم المقطع if..@endif@ لتقديم معلومات إلى المستخدم عن أخطاء التحقق. سنفصّل هذا الأمر بعد قليل.
  • مرّرنا لأغراض جمالية أصنافا وخاصيّات من Bootstrap إلى الاستمارة ؛ هذا ليس ضروريا وستعمل الاستمارة بدونه.

تظهر الآن الاستمارة بالذهاب إلى categories/create/.

01_categories_create.png

يمكنك إدخال اسم تصنيف وإرسال الاستمارة وستُوجَّه إلى categories/store/ لكنّ شيئا لن يحدُث لأننا لم نكتب حتى الآن شيئا في الدالة store من المتحكّم CategoriesController.

معالجة الاستمارة

نعود للدالة store في المتحكم CategoriesController. هذه هي الدالة التي تُرسَل إليها بيانات الاستمارة بعد النقر على زرّ الإرسال. نحدّث المتحكّم كالتالي: 

use App\Category;

...

public function store(Request $request)
{

    $category = new Category;

    $category->name = $request->get('name');

    $category->save();

    return \Redirect::route('categories.show', array($category->id));

}

بدأنا أولا باستيراد النموذج Category في المتحكّم ثم استخدمناه في الدالة store لتخزين تسجيلة Record جديدة في جدول قاعدة البيانات اعتمادا على محتويات الاستمارة؛ ثم بعد التخزين نعيد توجيه المستخدم إلى الدالة show ضمن المتحكّم CategoriesController مع معرّف التصنيف الذي أضفناه للتو. يمكننا تعديل الدالة show كالتالي لعرض رسالة تفيد بنجاح إضافة التصنيف: 

public function show($id)
{
    //
    $category = Category::find($id);
    $message = "$category->name has been added succefully";

    return $message;       
}

من الملاحظ أننا لم نتحقّق في العمليّة السابقة من مُدخلات المستخدم. يعني هذا أنه يمكن - مثلا - ترك الحقل الخاصّ باسم التصنيف فارغا وسيُحفظ تصنيف بدون اسم في قاعدة البيانات؛ طبعا هذا غير مقبول.

التحقق من الاستمارة قبل الإرسال

يوفّر Laravel 5 ميزة تُسمى طلب الاستمارة Form request تسمح بالتحقق من حقول الاستمارة دون تلويث المتحكّم. يدير ملفّ منفصل قواعد التحقّق من الاستمارة؛ نستخدم أمر artisan التالي لإنشاء هذا الملفّ: 

$ php artisan make:request CreateCategoryFormRequest
Request created successfully.

ينشئ الأمر ملفا باسم CreateCategoryFormRequest.php في المجلد app/Http/Requests. يبدو الملفّ كالتالي: 

<?php

namespace App\Http\Requests;

use App\Http\Requests\Request;

class CreateCategoryFormRequest extends Request
{

    public function authorize()
    {
        return false;
    }

    public function rules()
    {
        return [
            //
        ];
    }
}

عدّل الدالة authorize كالتالي: 

public function authorize()
{
    return true;
}

نحتاج لتحديد القيمة true بالنسبة للدالة authorize لأنه في حال كانت القيمة false فلن تُعالج بيانات الاستمارة.

ثم نعدّل الدالة rules: 

public function rules()
{
    return [
    'name' => 'required'
    ];
}

تعرّف الدالة قواعد التحقّق؛ عرّفنا أعلاه الحقل name ضمن الاستمارة بأنه مطلوب required؛ أي أن الاستمارة لن تُرسَل إلا إذا كانت توجد قيمة لهذا الحقل. تمكن إضافة أكثر من شرط على الحقل كالتالي:  

  'name' => 'required|alpha'

نحتاج الآن لدمج طلب الاستمارة في الدالة store ضمن المتحكّم CategoriesController. نبدأ باستيراد الصنف في المتحكّم كالتالي: 

use App\Http\Requests\CreateCategoryFormRequest;

ثم نحدّث الدالة store ليكون الكائن الممرَّر إليها من الصّنف CreateCategoryFormRequest: 

public function store(CreateCategoryFormRequest $request)
{

    ...

}

ابتداءً من الآن سيتحقّق Laravel من بيانات الحقل قبل إرسالها؛ وفي حال الإخفاق في التحقق من الشرط سيعيد الزائر إلى صفحة الاستمارة مع عرض رسالة بوجود خطأ.

ترجمة -وبتصرّف- للمقال Creating and Validating a Laravel 5 Form: The Definitive Guide. حقوق المقال محفوظة لصاحبه W. Jason Gilmore.

]]>352Thu, 08 Sep 2016 08:16:00 +0000دليل مطوّري PHP للبدء في بناء تطبيقات Laravel - الجزء الأوّلhttps://academy.hsoub.com/programming/php/laravel/%D8%AF%D9%84%D9%8A%D9%84-%D9%85%D8%B7%D9%88%D9%91%D8%B1%D9%8A-php-%D9%84%D9%84%D8%A8%D8%AF%D8%A1-%D9%81%D9%8A-%D8%A8%D9%86%D8%A7%D8%A1-%D8%AA%D8%B7%D8%A8%D9%8A%D9%82%D8%A7%D8%AA-laravel-%D8%A7%D9%84%D8%AC%D8%B2%D8%A1-%D8%A7%D9%84%D8%A3%D9%88%D9%91%D9%84-r363/

يقدّم دليل الانطلاق السريع هذا، المكوّن من جزأين، مقدّمة لإطار العمل Laravel. سنغطّي خلال هذه المقدّمة مواضيع تهجير قواعد البيانات Database migrations، ربط كائنات التطبيق بجداول قاعدة البيانات باستخدام Eloquent، التوجيه، الاستيثاق Authentication، التصريح Authorization، حقن الاعتمادات، التحقّق، العروض Views وقوالب Blade. هذه المقدّمة مناسبة إن كنت متعوّدا على أساسيات إطار العمل Laravel أو أطر العمل الأخرى التي تستخدم PHP.

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

التثبيت

نحتاج أولا لإنشاء مشروع Laravel جديد. يمكنك استخدام آلة Homestead افتراضية أو بيئة PHP محليّة على جهازك. استخدم Composer بعد تجهيز بيئة العمل لإنشاء مشروع Laravel جديد على النحو التالي: 

composer create-project laravel/laravel quickstart --prefer-dist "5.2.*"

يمكنك، إن أردت، تنزيل الشفرة المصدريّة النهائية للمشروع لتشغيلها على حاسوبك الشخّصي باستنساخ مستودع Git وتثبيت الاعتمادات الخاصّة بالمشروع على النحو التالي (حدّدنا الفرع 5.2 من المشروع؛ وهو الإصدار المستقرّ من المستودع أثناء كتابة هذا الدرس): 

git clone -b 5.2 --single-branch https://github.com/laravel/quickstart-intermediate/ quickstart-final
cd quickstart-final
composer install
php artisan migrate

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

تهيئة قاعدة البيانات

التهجيرات

سنبدأ بإنشاء تهجيرات لتعريف جدول قاعدة البيانات الذي سيخزّن جميع المهامّ التي سيديرها التطبيق. توفّر التهجيرات في Laravel وسيلة سهلة ومعبّرة لتعريف جداول البيانات باستخدام شفرة PHP. تفيد التهجيرات - مثلا - أثناء العمل في فريق للحصول على نفس البنية في قاعدة البيانات؛ فبدلا من أن ينشئ كل عضو يدويا قاعدة بيانات محليّة لاحتياجات التطوير، فإنه ينفّذ التهجيرات للحصول على قاعدة بيانات بنفس البنية الموجودة لدى بقية الفريق.

جدول المستخدمين

نخطّط لجعل التطبيق يتيح للمستخدمين إنشاء حسابات، أي أنه يتوجّب علينا إنشاء جدول لحفظ بيانات هؤلاء المستخدمين. يأتي Laravel مبدئيا بتهجير لإنشاء جدول للمستخدمين، مما يغنينا عن إنشائه يدويا. يوجد التهجير المبدئي للمستخدمين في المجلّد database/migrations.

جدول المهامّ

العنصر الثاني في تطبيقنا هو المهامّ؛ التي يتوجّب علينا حفظ معلومات عنها. لذا، سننشئ جدولا خاصّا بالمهامّ. تُستخدَم أداة artisan التي تعمل من سطر الأوامر لتوليد أنواع مختلفة من الأصناف Classes وتختصر الكثير من الوقت أثناء تطوير التطبيقات في Laravel. سنستعين بهذه الأداة لإنشاء التهجير الخاصّ بجدول المهامّ، وذلك على النحو التالي: 

 
php artisan make:migration create_tasks_table --create=tasks

يطلُب أمر artisan أعلاه توليد تهجيرٍ باسم create_tasks_table ويحدّد اسم جدول البيانات الذي نريد إنشاءه create=tasks--. يوضَع التهجير المولَّد في المجلّد database/migrations الموجود في مجلّد المشروع. إن فتحت ملفّ التهجير create_tasks_table (اسم الملفّ يبدأ بختم زمني يوافق وقت توليد الملفّ) ستجد أن الأمر أضاف حقلا لمعرّف يزداد تلقائيا Auto-incrementing ID وأختاما زمنيّة Timestamps ضمن حقول الجدول. نحرّر الملفّ المولَّد ونضيف عمودا من نوع سلسلة محارف String لأسماء المهامّ وعمودا آخر باسم user_id لربط المهامّ بالمستخدمين (حتى نعرف صاحب المهمة): 

<?php

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Migrations\Migration;

class CreateTasksTable extends Migration
{
    /**
    * Run the migrations.
    *
    * @return void
    */
    public function up()
    {
        Schema::create('tasks', function (Blueprint $table) {
            $table->increments('id');
            $table->integer('user_id')->index();
            $table->string('name');
            $table->timestamps();
        });
    }

    /**
    * Reverse the migrations.
    *
    * @return void
    */
    public function down()
    {
        Schema::drop('tasks');
    }
}

تأكد من إعداد متطلّبات التهجير لتمكين الاتصال بين التطبيق وقاعدة البيانات وبين أداة artisan وقاعدة البيانات (ليكن اسمُ قاعدة البيانات quickstartdb، مثلا). ثم بعد التأكد نفّذ أمر التهجير على النحو التالي (إن كنت تستخدم Homestead فسيتوجب عليك تنفيذ الأمر من داخل الآلة الافتراضية): 

 
php artisan migrate

سينشئ الأمر السابق الجداول التي عرّفناها في التهجيرات. يمكنك التأكد من الأمر بالنظر في قاعدة البيانات وسرد الجداول الموجودة فيها.

ننتقل الآن لتعريف نماذج Eloquent الخاصّة بالمشروع.

نماذج Eloquent

يستخدم Laravel مبدئيا إطار العمل Eloquent لربط الكائنات في التطبيق بالجداول في قاعدة البيانات Object-relational mapping. يسهّل Eloquent استرجاع البيانات وتخزينها في قاعدة البيانات، وذلك عن طريق نماذج معرَّفة بوضوح. يوافق كلّ نموذج Eloquent عادة جدولًا في قاعدة البيانات.

نموذج المستخدم

نحتاج أولا إلى نموذج Model ليربط الكائنات التي تمثّل المستخدمين في التطبيق بجدول المستخدمين users في قاعدة البيانات. إن نظرت في مجلّد التطبيق app داخل مشروعك فستجد أن Laravel يأتي مبدئيا بنموذج مستخدم User.php؛ أي أننا لن نحتاج لإنشاء واحد.

نموذج المهمة

أنشأنا أثناء إعداد التهجيرات جدولا للمهامّ باسم tasks. حسب نفس مبدأ نموذج المستخدم سنحتاج لنموذج في التطبيق لربط الكائنات من صنف المهام بجدول البيانات tasks. نستخدم أداة artisan لهذا الغرض على النحو التالي: 

 
php artisan make:model Task

ينشئ الأمر نموذجا فارغا باسم Task.php ويضعه في المجلد app. لن تحتاج لإخبار Eloquent بجدول البيانات الذي يتوافق مع النموذج لأن Eloquent يفترض أن اسم الجدول هو جمع لاسم النموذج. بمعنى أن النموذج User يتوافق مع الجدول users والنموذج Task مع الجدول tasks (تبدأ أسماء النماذج بأحرف كبيرة، فيما تبدأ أسماء الجداول بأحرف صغيرة).

نعدّل على ملفّ النموذج Task لإتاحة إمكانية الإسناد الشامل Mass assignment للحقل name: 

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Task extends Model
{
    /**
    * The attributes that are mass assignable.
    *
    * @var array
    */
    protected $fillable = ['name'];
    
   /**
   * The attributes that should be cast to native types.
   *
   * @var array
   */
   protected $casts = [
      'user_id' => 'int',
   ];
}

سنعود لاستخدام النماذج عند الحديث عن تعريف مسارات Routes التطبيق.

ملحوظة:  عند الاستعلام عن بيانات من قاعدة بيانات MySQL في PHP فإن نوع البيانات المتحصَّل عليه هو دائما string (سلسلة محارف). استخدمنا في النموذج أعلاه المصفوفة casts للتأكيد على أن الخاصية user_id في الصنف Task يجب أن تكون من النوع int. سنتمكّن بهذه الطريقة من استخدام المعامل === (المساواة التامة، في القيمة ونوع البيانات).

علاقات Eloquent

عرفنا في الفقرتين السابقتين النموذجيْن User وTask؛ المستخدم والمهمة على التوالي، يجب الآن تعريف العلاقة التي تربط بين الاثنين. يمكن لمستخدم إنشاء أكثر من مهمّة، لكنّ مهمّة محدّدة لا يمكن أن تُسنَد سوى لمستخدم واحد فقط. يمكّن تعريف العلاقات بين النماذج من الحصول بسهولة على البيانات الطلوبة. مثلا؛ يمكن، بعد تعريف العلاقة بين المستخدم والمهام، إيجادُ مهامّ المستخدم ذي المعرّف 1 على النحو التالي: 

$user = App\User::find(1);

foreach ($user->tasks as $task) {
    echo $task->name;
}

علاقة المستخدم بالمهام

نحدّد أولا طبيعة العلاقة بين المستخدم والمهامّ. تعرَّف العلاقات في Eloquent بدوالّ في النموذج. تحدّد الدوال طبيعة العلاقة بين النموذجين. يمكن أن يكون للمستخدم، كما أسلفنا، أكثرُ من مهمة، تُسمّى هذه العلاقة في Eloquent بـhasMany، وتعرَّف بإضافة دالة tasks على النحو التالي إلى النموذج User: 

<?php

namespace App;

use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    /**
    * The attributes that are mass assignable.
    *
    * @var array
    */
    protected $fillable = [
        'name', 'email', 'password',
    ];

    /**
    * The attributes that should be hidden for arrays.
    *
    * @var array
    */
    protected $hidden = [
        'password', 'remember_token',
    ];
    /**
    * Get all of the tasks for the user.
    */
    public function tasks()
    {
        return $this->hasMany(Task::class);
    }
}

علاقة المهمّة بالمستخدم

نعرفّ، في الجانب الآخر، على مستوى النموذج Task، طبيعة العلاقة التي تربط المهمة بالمستخدم. نعرّف، كما فعلنا عند تعريف علاقة المستخدم بالمهامّ، دالةً مع تحديد طبيعة العلاقة التي هي في هذه الحالة belongsTo. بمعنى أن المهمة تتبع للمستخدم؛ أي أنه لا يمكن أن تتبع نفس المهمة لأكثر من مستخدم.

يمكن تقريب الفكرة بالقول إن الناظر للعلاقة من جهة المهمة يرى أنه تسير في اتجاه واحد belongsTo (مستخدم واحد)؛ أما الناظر إليها من جهة المستخدم فيرى أنها يمكن أن تسير في عدّة اتجاهات hasMany (مهامّ متعدّدة): 

<?php

namespace App;

use App\User;
use Illuminate\Database\Eloquent\Model;

class Task extends Model
{
    /**
    * The attributes that are mass assignable.
    *
    * @var array
    */
    protected $fillable = ['name'];

    /**
    * Get the user that owns the task.
    */
    public function user()
    {
        return $this->belongsTo(User::class);
    }
}

التوجيه

تُستخدَم المسارات Routes لتوجيه الروابط URL إلى متحكّم أو دالة تُنفَّذ عند زيارة رابط محدَّد. تُعرَّف المسارات مبدئيا في Laravel ضمن الملفّ app/Http/routes.php. تتيح المتحكمات التعامل مع طلبات Http بتوزيعها بين ملفات مختلفة من أجل تنظيم أفضل وصيانة أسهل.

إظهار عرض

سيكون لدينا مسار / تظهر للزائر عند طلبه صفحة ترحيبية. تنتُج الصفحة الترحيبية عن معالجة قالب HTML. مبدئيا؛ يُخزّن Laravel جميع قوالب HTML في المجلّد resources/views.

ستجد عند فتح الملفّ routes.php أنه يحوي الدالة التالية: 

Route::get('/', function () {
    return view('welcome');
});

تستقبل هذه الدالة الطالبات الواردة على المسار / (مثلا www.example.com) وتقدّم إليها العرض welcome.blade.php باستخدام الدالة المساعدة view. لاحظ أننا لم نحدّد امتداد الملفّ في الدالة، اسم العرض (welcome) يكفي. سنعرّف العرض في ما بعد.

الاستيثاق

ذكرنا في تقديم المشروع الذي نودّ بناءه أننا نريد أن يتمكّن المستخدمون من إنشاء حسابات والولوج بها إلى التطبيق؛ أي أننا سنحتاج لآلية للاستيثاق. قد يتطلّب إنشاء آلية للاستيثاق الكثير من الجهد والوقت؛ إلا أن Laravel يحاول جعل هذه العمليّة أسهل ما يمكن.

أولا؛ تمكن ملاحظة وجود المتحكّم AuthController في المجلد app/Http/Controllers/Auth. يستخدم هذا المتحكّم السمة AuthenticatesAndRegistersUsers التي تحوي الدوال المطلوبة لإنشاء المستخدمين والاستيثاق منهم.

مسارات الاستيثاق وعروضه

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

 
php artisan make:auth

لاحظ مخرجات الأمر والعروض التي أضافها للمشروع. تمكن أيضا ملاحظة أن الأمر أضاف المسارات التالية إلى ملفّ المسارات: 

Route::auth();

Route::get('/home', 'HomeController@index');

تسجّل الدالة auth من الصّنف Route جميع المسارات التي نحتاجها لتسجيل حسابات جديدة للمستخدمين، ولوج مستخدمين مسجَّلين وإعادة تعيين كلمة السّر.

يعرّف الأمر في المسار الثاني الرابط home/ الذي تتعامل معه الدالة index في المتحكم HomeController الذي أنشأه الأمر السابق. إن فتحت ملفّ المتحكم HomeController فستجد أن الدالة index تطلُب إظهار العرض home.

ملحوظة: إن كنت ترغب في الاطّلاع على الشفرة المصدرية الكاملة للعروض فهي متوفّرة ضمن شفرة المشروع على GitHub.

افتح ملفّ المتحكّم AuthController (في المجلّد app/Http/Controllers/Auth) وغيّر قيمة redirectTo$ كالتالي: 

 
protected $redirectTo = '/tasks';

تحدّد هذه الخاصّيّة المسار الذي يُوجَّه الزائر إليه بعد الاستيثاق من بياناته. يجب أيضا التعديل على الملفّ app/Http/Middleware/RedirectIfAuthenticated.php ليرجع نفس المسار بعد ولوج الزائر: 

 
return redirect('/tasks');

المتحكم في المهام

ننشئ متحكّما جديدا خاصّا بالعمليات على المهامّ، مثل العثور على المهامّ المخزّنة وتخزين مهامّ جديدة. سنستخدم - كالعادة - أداة artisan لهذا الغرض: 

 
php artisan make:controller TaskController

ثم نعدّل ملفّ المسارات بإضافة المسارات التالية: 

Route::get('/tasks', 'TaskController@index');
Route::post('/task', 'TaskController@store');
Route::delete('/task/{task}', 'TaskController@destroy');

سنستخدم المسار tasks/ مع الإجراء get للعثور على مهامّ مستخدِم، المسار task/ مع الإجراء post لإضافة مهمة جديدة والمسار {task/{task مع الإجراء delete لحذف مهمّة؛ حيثُ {task} معرّف المهمة.

الاستيثاق من جميع مسارات المهامّ

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

يمكن، بإضافة نداء لصنف الاستيثاق الوسيط auth داخل مشيّد Constructor المتحكّم TaskController، جعلُ جميع الإجراءات في المتحكّم تستدعي الاستيثاق من المستخدم (أن يكون مسجّلَ الدّخول). يعرّف الملف app/Http/Kernel.php جميع الأصناف الوسيطة الممكن تطبيقها على المسارات. يصبح المتحكم TaskController بعد إضافة الوسيط إلى المشيّد كما يلي: 

<?php

namespace App\Http\Controllers;

use App\Http\Requests;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;

class TaskController extends Controller
{
    /**
    * Create a new controller instance.
    *
    * @return void
    */
    public function __construct()
    {
        $this->middleware('auth');
    }
}

إنشاء القوالب والعروض

يتضمّن الجزء الأساسي من التطبيق الذي نعملُ عليه عرضا واحدا توجد به استمارة لإضافة مهامّ جديدة، كما تظهر لائحة بالمهامّ الموجودة سلفا. في ما يلي لقطة من التطبيق المكتمل:

01_application_layout.png

تعريف مخطّط العرض

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

يحتفظ Laravel بجميع العروض ضمن المجلّد resources/views. سنعرّف قالبا جديدا لعروض Blade في الملفّ resources/views/layouts/app.blade.php. يستخدم Laravel نظام القوالب Blade لمعالجة الملفات التي تنتهي بالامتداد blade.php.. يمكن استخدام قوالب PHP تقليدية لتقديم العروض، إلا أن نظام Blade يوفّر قوالب مختصرة ومحكمة.

افتح الملفّ resources/views/layouts/app.blade.php وستجد أن محتواه يشبه التالي: 

<!-- resources/views/layouts/app.blade.php -->

<!DOCTYPE html>
<html lang="en">
    <head>
        <title>Laravel Quickstart - Intermediate</title>

        <!-- شفرات CSS و JavaScript -->
    </head>

    <body>
        <div class="container">
            <nav class="navbar navbar-default">
                <!-- محتوى شريط التصفح Navbar  -->
            </nav>
        </div>

        @yield('content')
    </body>
</html>

تحدّد التعليمة ('yield('content@ مكان الصفحات التي ستمدّد المخطّط الرئيس وتضيف محتوى خاصّا بها. راجع توريث القوالب في Laravel للمزيد من التفصيل. سننتقل الآن لتعريف العرض الإبن الذي سيستخدم المخطّط ويعرّف داخله محتوى خاصّا به.

تعريف العرض المُمدِّد للمخطَّط

سنحتاج لتعريف عرض يحوي استمارة لإنشاء مهمة جديدة وجدولا لعرض المهامّ الموجودة. ننشئ لهذا الغرض عرضا على المسار resources/views/tasks/index.blade.php، الذي ستطلب الدالة index في المتحكّم TaskController عرضه.

سنركّز في ما يلي على التعليمات المتعلّقة بـBlade ونتجاوز شفرة Bootstrap CSS (يمكن الحصول على الشفرة كاملة من مستودع المشروع على GitHub: 

 
<!-- resources/views/tasks/index.blade.php -->

@extends('layouts.app')

@section('content')

    <div class="container">
        <div class="col-sm-offset-2 col-sm-8">
            <div class="panel panel-default">
                <div class="panel-heading">
                    New Task
                </div>

    <div class="panel-body">
        <!-- إظهار أخطاء التحقّق -->
        @include('common.errors')

        <!-- استمارة إنشاء مهمة -->
        <form action="{{ url('task') }}" method="POST" class="form-horizontal">
            {{ csrf_field() }}

            <!-- اسم المهمة -->
            <div class="form-group">
                <label for="task-name" class="col-sm-3 control-label">Task</label>

                <div class="col-sm-6">
                    <input type="text" name="name" id="task-name" class="form-control">
                </div>
            </div>

            <!-- زرّ إضافة مهمة -->
            <div class="form-group">
                <div class="col-sm-offset-3 col-sm-6">
                    <button type="submit" class="btn btn-default">
                        <i class="fa fa-plus"></i> Add Task
                    </button>
                </div>
            </div>
        </form>
    </div>
  </div>

     <!-- سنضع هنا الشفرة الخاصة بعرض المهام التي أنشأها المستخدم -->
@endsection

  • تُخبر التعليمة extends@ نظام القوالب Blade أننا في طور استخدام المخطّط المعرَّف في الملفّ resources/views/layouts/app.blade.php. يضع نظامُ القوالب جميعَ المحتوى الموجود بين التعليمتيْن ('section('content@ وendsection@ مكان التعليمة ('yield('content@ في المخطّط app.blade.php.

  • تحمّل التعليمة ('include('common.errors@ القالب resources/views/common/errors.blade.php. هذا القالب غير معرَّف لحد الساعة، ولكن سنعرّفه بعد قليل.

نعود للمتحكّم TaskController ونضيف الدالة index التي تطلُب تقديم العرض resources/views/tasks/index.blade.php الذي أنشأناه للتو: 

/**
* Display a list of all of the user's task.
*
* @param  Request  $request
* @return Response
*/
public function index(Request $request)
{
    return view('tasks.index');
}

يشير الاسم tasks.index إلى أن المطلوب هو إظهار العرض index.blade.php الموجود في المجلد tasks الذي يوجد بدوره في مجلد العروض (أي resources/view).

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

سنواصل في المقال القادم بناء التّطبيق.

ترجمة - بتصرّف - للجزء الأول من مقال Intermediate Task List.

]]>363Mon, 05 Sep 2016 11:18:00 +0000إنشاء قائمتين منسدلتين (Dropdown lists) باستخدام Laravel و jQueryhttps://academy.hsoub.com/programming/php/laravel/%D8%A5%D9%86%D8%B4%D8%A7%D8%A1-%D9%82%D8%A7%D8%A6%D9%85%D8%AA%D9%8A%D9%86-%D9%85%D9%86%D8%B3%D8%AF%D9%84%D8%AA%D9%8A%D9%86-dropdown-lists-%D8%A8%D8%A7%D8%B3%D8%AA%D8%AE%D8%AF%D8%A7%D9%85-laravel-%D9%88-jquery-r323/

نسعى في هذا الدّرس إلى إنشاء قائمتين منسدلتين Dropdown lists ترتبط إحداهما بالأخرى. تحتوي الأولى مثلا على تصنيف والثانية على تصنيف فرعي من التصنيف الموجود في القائمة الأولى. يعني هذا أنْ تتغيّر التصنيفات الفرعيّة الموجودة في القائمة الثّانيّة عند تغيّر العنصُر المحدّد في القائمة الأولى.

laravel-jquery-dropdown-menu.png

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

01_dependent_dropdown.png

نستخدم Laravel في الجانب الخلفيّ Backend لتولي التعامل مع الطّلبات والتخاطب مع قاعدة البيانات للحصول على التصنيفات والتّصنيفات الفرعيّة منها. يتولّى سكربت jQuery العمل في الواجهة الأماميّة Frontend لتحديث محتويات القائمة الثانيّة عند تعديل محتوى الأولى.

في ما يلي نظرة عامّة على الخطوات التي سنتّبعها:

  • إنشاء النماذج Models والتهجيرات Migrations.
  • تهيئة معمل نماذج Model factory وبذر Seed جداول البيانات.
  • إعداد المسارات Routes والمتحكّمات Controllers.
  • إعداد العروض Views.

الطريقة التي نريد تنفيذها هي كالتالي: عند الدخول إلى المسار categories/ يتلقى ملف المسارات الطّلب ويحوّله إلى الدالّة categories في المتحكّم HomeController. تستقبل الداّلة الطلب وتطلب قائمة بالتّصنيفات من نموذج التّصنيف Category؛ ثم ترسل التّصنيفات إلى العرض categories الذي يعرضها في القائمة المنسدلة الأولى. نستخدم سكربت jQuery في العرض للإنصات لتغييرات القائمة المنسدلة العلويّة، وعند اختيّار أحد عناصرها يأخذ السكربت معرّف العنصر المحدَّد ثم يرسل به طلب Ajax إلى المسار api/category-dropdown/ الذي يجيب بلائحة التصنيفات الفرعيّة للتّصنيف المحدّد في القائمة الأولى. يستقبل السكربت اللائحة ويعرضها في القائمة الثانية.

تمكنك مراجعة المقالات التاليّة لتفصيلات أكثرعن إنشاء النماذج، استخدام معمل النماذج و العروض.

نبدأ بتثبيت Laravel بالأمر التالي:
  

composer create-project --prefer-dist laravel/laravel laradropdown "5.3.*"

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

إنشاء النماذج والتهجيرات

نبدأ بإنشاء نموذجيْن Category و SubCategory. الأوّل للتصنيفات والثاني للتصنيفات الفرعيّة. ننفّذ ما يلي في مجلّد المشروع: 

php artisan make:model Category -m
php artisan make:model SubCategory -m

استخدمنا خيار m- لإنشاء التهجيرات مع إنشاء النماذج.

نفتح ملفّ التهجير الخاصّ بالتصنيف ونعدّله: 

public function up()
{
  Schema::create('categories', function (Blueprint $table) {
    $table->increments('id');
    $table->string('name')->unique();
    $table->timestamps();
  });
}

public function down()
{
  Schema::dropIfExists('categories')
}

يحوي الملفّ كما هو ظاهر أربعة حقول: معرّفا، اسما للتّصنيف وحقليْ الأختام الزمنية.

ننتقل لملفّ التهجير الخاصّ بالتصنيف الفرعي: 

public function up()
{
  Schema::create('sub_categories', function (Blueprint $table) {
    $table->increments('id');
    $table->string('name')->unique();
    $table->integer('category_id')->unsigned();
    $table->timestamps();
  });
  Schema::table('sub_categories', function (Blueprint $table) {
    $table->foreign('category_id')
          ->references('id')
          ->on('categories')
          ->onDelete('cascade');
  });
}

public function down()
{
  Schema::table('sub_categories', function(Blueprint $table) {
    $table->dropForeign('sub_categories_category_id_foreign');
  });
  Schema::dropIfExists('sub_categories');
}

يختلف ملفّ التهجير هذا قليلا عن الملفّ السّابق؛ إذ يحوي إلى جانب حقول المعرّف، الاسم والأختام الزمنيّة معرفَ التصنيف الذي يتفرّع منه. هذا المعرف هو مفتاح خارجي Foreign key يحيل إلى جدول التّصنيفات. نعرّف الحقول أولا ثم نحدّد الحقل category_id على أنه مفتاح خارجي. ينبغي أن يكون الحقل مطابقا تماما من حيث النوع للحقل الذي يحيل إليه. في الدالة down نبدأ بحذف القيد من على الحقل حتى يمكننا حذف الجدول.

أنهينا إعداد التهجيرات. ننتقل لإعداد النماذج.

نغيّر ملف النموذج Category على النحو التالي: 

class Category extends Model
{
protected $fillable = ['id', 'name'];

public function sub_categories()
    {
        return $this->hasMany('SubCategory');
    }
}

نحدّد أولا الحقول التي يمكن إسنادها (خاصيّة fillable) ثم نضيف الدالة sub_categories التي تعرّف العلاقة بين التّصنيف Category والتّصنيف الفرعي SubCategory. هذه العلاقة هي من النوع hasMany بمعنى أنه توجد بالتّصنيف تصنيفات فرعية تابعة له.

يفيدنا تعريف العلاقات بين النماذج في الاستعلامات ويجعلها أسهل بكثير كما سنرى.

نفس الشيء تقريبا بالنسبة للنموذج SubCategory: 

class SubCategory extends Model
{
protected $fillable = ['id', 'name', 'category_id'];

public function category()
    {
        return $this->belongsTo('Category');
    }
}

نعرّف في النموذج SubCategory العلاقة العكسيّة لتلك المعرّفة في النموذج Category؛ وهي belongsTo التي تعني أن هذا الصّنف يتبع للصّنف Category.

النماذج والتهجيرات جاهزة؛ يمكننا الآن تنفيذ التهجيرات:  

php artisan migrate

تهيئة معامل النماذج وبذر جداول البيانات

سنستفيد من الخبرى التي تحصّلنا عليها في درس استخدام معمل النماذج (Model factory) في Laravel لتوليد بيانات الاختبار لتهيئة معملَيْ نماذج نستخدمهما لبذر البيانات في الجدوليْن categories و sub_categories.

ننشئ ملفيْن في المجلّد /database/factories؛ واحدا باسم CategoryFactory.php والآخر SubCategoryFactory.php. ثم نضيف المحتوى التالي إلى CategoryFactory.php : 

<?php
    $factory->define(App\Category::class, function (Faker\Generator $faker){
        return [
        'name' => $faker->unique()->word
        ];
});

نفس المبدأ المستخدَم في الدرس المُشار إليه أعلاه. نعرّف النموذج الذي نريد توليد بيانات له ثم نستخدم مكتبة Faker لملْء الحقل المحدَّد (name). طلبنا توليد كلمات فريدة Unique حتى نوافق الشّرط المعرَّف في تهجير قاعدة البيانات الخاصّ بالجدول categories.

الأمر مختلف قليلا مع الملف SubCategoryFactory.php الذي نعدّله كالتالي: 

<?php

    $factory->define(App\SubCategory::class, function (Faker\Generator $faker){
        $categories = App\Category::get()->pluck('id')->all();
        return [
        'name' => $faker->unique()->word,
        'category_id' =>  $faker->randomElement($categories),
        ];
});

بما أن الحقل category_id مفتاح خارجي على معرّف التّصنيف فلن تقبل قاعدة البيانات إضافة معرّف لتصنيف غير موجود في جدول التصنيفات. لتجاوز هذا القيد نبدأ بطلب معرّفات التصنيفات:  

$categories = App\Category::get()->pluck('id')->all();

ثم عند توليد بيانات للحقل category_id نطلب منه أن يختار واحدا عشوائيا من المعرّفات التي تحصّلنا عليها سابقا: 

'category_id' =>  $faker->randomElement($categories),

هذا كلّ شيء بالنسبة لمعمل النماذج. ننتقل للبذر. ننشئ صنفا سنستخدمه لبذر النموذجيْن Category و SubCategory: 

php artisan make:seeder SubCategoryTableSeeder

نفتح الملف ونعدّله كما يلي: 

public function run()
{
  App\SubCategory::truncate();
  factory(App\Category::class, 10)->create();
  factory(App\SubCategory::class, 50)->create();
}

نطلُب في الملفّ توليد 10 تصنيفات و50 تصنيفا فرعيا.

نعدّل ملف البذر DatabaseSeeder كما يلي: 

public function run()
{
    Model::unguard();
    $this->call(SubCategoryTableSeeder::class);
    Model::reguard();
}

لا ننسى استدعاء النموذج Model في الملف DatabaseSeeder: 

use Illuminate\Database\Eloquent\Model;

نستدعي ملفّ البذر SubCategoryTableSeeder الذي يستخدم معمليْ النماذج لتوليد البيانات. يمكننا الآن تنفيذ البذر: 

php artisan db:seed

إعداد المسارات والمتحكمات

نريد أن نصل إلى صفحة القائمتين المنسدلتين عبر الرابط categories/؛ لذا سنعرّف مسارا له في ملف مسارات الوِب  routes/web.php: 

Route::get('/categories', 'HomeController@categories');

لا خصوصيةَ هنا؛ المسار والمتحكّم والدالة اللذان يعالجان الطّلب.

إن لم يكن المتحكّم HomeController معرّفا لديك فاستخدم الأمر php artisan make:controller HomeController وأضف إليه دالة باسم categories: 

public function categories() {
  $categories = Category::orderBy('name', 'asc')->get();
  return view('layouts.categories', compact('categories'));
}

لا تنس استيراد النموذج Category: 

use App\Category;

نستخدم النموذج Category في الدالة للحصول على لائحة التصنيفات مرتبة تصاعديا حسب الاسم؛ ثم نرسل النتيجة إلى العرض categories الموجود في المجلّد layouts ضمن مجلّد العروض resources/views. هذا العرض غير موجود لحدّ الساعة لذا يجب أن ننشئه. لكن قبل ذلك يجب أن ننهي إعداد المتحكّمات.

سنضع في العرض سكربت jQuery -كما أشرنا سابقا- للحصول على لائحة بالتصنيفات الفرعيّة للتّصنيف المحدّد في القائمة المنسدلة العلوية. يرسل السكربت طلب Ajax إلى المسار api/category-dropdown/. ننشئ هذا المسار في ملفّ المسارات الخاصّ بواجهة التطبيقات البرمجيّة routes/api.php على النحو التالي: 

Route::get('/category-dropdown', 'ApiController@categoryDropDownData');

يمكن أن نستخدم نفس المتحكّم السابق (HomeController) ونعرّف دالة فيه كما يمكن أن ننشئ متحكّما جديدا. اخترنا الحلّ الأخير حتى نفصل بين التحكّم في المسارات العادية والمسارات المعدّة لتكون واجهة برمجية Application programming interface, API.

نستخدم الأمر التالي لإنشاء متحكّم باسم ApiController:  

php artisan make:controller ApiController

ثم نعدّل عليه: 

public function categoryDropDownData() {

    $category_id = Input::get('category_id');
    $subcategories = App\Category::find($category_id)->sub_categories;

    return Response::json($subcategories);
}

يتلقى المسار api/category-dropdown/ معرّف التّصنيف المحدّد في القائمة ضمن متغيّر category_id. نستقبل المتغيّر المُرسَل من المستخدم بالدّالة get من الصّنف Input.

بما أننا عرّفنا علاقات بين التصنيف والتصنيف الفرعي في النموذجين المقابليْن فيمكننا بسهولة العثور على التّصنيفات الفرعيّة لتصنيف؛ كلّ ما علينا فعله هو استخدام الدّالة sub_categories التي عرّفناها في الصّنف Category.

تعثُر التعليمة التالية على جميع التّصنيفات الفرعيّة للتّصنيف ذي المعرّف category_id.  

$subcategories = Category::find($category_id)->sub_categories;

في الأخير نرمّز التصنيفات الفرعيّة بصيغة Json ثم نرسلها في الإجابة.

لا تنس استدعاء الأصناف التي استخدمناها وإضافتها إلى بداية الملف: 

use Illuminate\Support\Facades\Response;
use Illuminate\Support\Facades\Input;
use App\Category;

المحصّلة: 

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Response;
use Illuminate\Support\Facades\Input;
use App\Category;

class ApiController extends Controller
{
    public function categoryDropDownData() {

      $category_id = Input::get('category_id');
      $subcategories = Category::find($category_id)->sub_categories;

      return Response::json($subcategories);
    }
}

إعداد العروض

أكملنا الإعدادات من جهة النهاية الخلفيّة؛ تبقى فقط إعداد العرض لاستقبال البيانات وتقديمها للزائر.

ننشئ لهذا الغرض عرضا باسم categories.blade.php في المجلّد layouts. يمدّد هذا العرض عرضا رئيسا Master view اسمُه app.blade.php، يوجد في نفس المجلّد. ينفّذ categories.blade.php مقطعًا باسم content معرّفًا في العرض الرّئيس ويوجد به محتوى الصفحة. 

@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">Dashboard</div>
                <div class="panel-body">
                <div class="form-group">
                    <label>Category:</label><br>
                    <select class="form-control input-lg" name="category_id" id="category_id">
                    <option value="">Select Category</option>
                    @foreach($categories as $category)
                        <option value="{{ $category->id }}"> {{$category->name}}</option>
                    @endforeach
                    </select>
                </div>
                <div class="form-group">
                    <label>Subcategory:</label><br>
                    <select class="form-control input-lg" name="subcategory_id" id="subcategory_id">
                    <option value="">First Select Category</option>
                    </select>
                </div>

                </div>
            </div>
        </div>
    </div>
</div>

<script>
$('#category_id').on('change', function(e){
var cat_id = e.target.value;
//ajax
$.get('/api/category-dropdown?category_id=' + cat_id, function(data){
    //success data
    $('#subcategory_id').empty();
    $('#subcategory_id').append('<option value=""> Please choose one</option>');
    $.each(data, function(index, subcatObj){
    $('#subcategory_id').append('<option value="' + subcatObj.id+'">'
    + subcatObj.name + '</option>');
    });
});
});
</script>
@endsection

يستقبل المقطع content التصنيفات في المتغيّر categories ثم يستخدم دالة foreach التكراريّة لعرضها في القائمة المنسدلة: 

        @foreach($categories as $category)
            <option value="{{ $category->id }}"> {{$category->name}}</option>
        @endforeach

نضيف في المقطع script سكربت jQuery الذي سيتولى مزامنة محتوى القائمتيْن.

يأخذ الجزء الأول من السكربت العنصر category_id الذي يمثّل القائمة الأولى ويستخدم الحدث on change لمراقبة التغيّرات عليه. نحتفظ بمعرّف التصنيف في المتغيّر cat_id: 

$('#category_id').on('change', function(e){
var cat_id = e.target.value;

ثم يأتي دور نداء Ajax الذي يرسل المتغيّر cat_id إلى المسار api/category-dropdown/ ضمن المعطى category_id: 

$.get('/api/category-dropdown?category_id=' + cat_id, function(data)

يخزّن النداء النتيجة في المتغيّر data. عند تلقّي الطلب ننفّذ ثلاثة أمور:

  • حذف محتوى القائمة المنسدلة الثّانية لمحو المحتوى الموجود فيها (المحتوى الأصلي أو المحتوى المرتبط بعنصُر محدد سابقا في القائمة الأولى):  

    $('#subcategory_id').empty();

    ثم نضيف تعليمة جديدة تطلب من الزائر الاختيّار: 

    $('#subcategory_id').append(' Please choose one');

    ثم في الأخير نستخدم دالة each التكرارية في jQuery للمرور على البيانات (التصنيفات الفرعيّة) الواحدة تلو الأخرى وإضافتها إلى القائمة المنسدلة الثانيّة: 

    $.each(data, function(index, subcatObj){
    $('#subcategory_id').append(''
    + subcatObj.subcategory_name + '</option');
});

     

بالنسبة للعرض الرّئيس app.blade.php فقد استخدمنا هذا الملف.

لم يتبق سوى زيارة الرابط categories/ لمعاينة النتيجة.

ترجمة -وبتصرّف- للمقال Dependent Dropdown List with jquery in Laravel 5.1 لصاحبه  Bill Keck.

]]>323Sun, 19 Jun 2016 08:17:00 +0000استخدام inject@ لحقن مزود خدمة Service provider في قالب Blade في Laravelhttps://academy.hsoub.com/programming/php/laravel/%D8%A7%D8%B3%D8%AA%D8%AE%D8%AF%D8%A7%D9%85-inject-%D9%84%D8%AD%D9%82%D9%86-%D9%85%D8%B2%D9%88%D8%AF-%D8%AE%D8%AF%D9%85%D8%A9-service-provider-%D9%81%D9%8A-%D9%82%D8%A7%D9%84%D8%A8-blade-%D9%81%D9%8A-laravel-r331/

رأينا في درس كيف تنشئ مزود خدمة Service provider في Laravel طريقة عمل مزوّدات الخدمة والآليّة التي تتيح بها مرونة أكبر في التعامل مع الأصناف في Laravel.

سنرى في هذا الدّرس كيفيّة الاستفادة من تعليمة inject@ لإعادة استخدام مزوّد خدمة في قالب Blade.

laravel-inject-service-provider-blade.png

استخدمنا في الدرس السابق مزوّد خدمة داخل متحكّم على النحو التالي: 

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.

]]>331Fri, 10 Jun 2016 14:01:40 +0000كيف تنشئ مزود خدمة (Service provider) في Laravelhttps://academy.hsoub.com/programming/php/laravel/%D9%83%D9%8A%D9%81-%D8%AA%D9%86%D8%B4%D8%A6-%D9%85%D8%B2%D9%88%D8%AF-%D8%AE%D8%AF%D9%85%D8%A9-service-provider-%D9%81%D9%8A-laravel-r326/

تعتمد بنية Laravel كثيرا على مزوّدي الخدمة Service providers لتحميل الأصناف Classes إلى الذاكرة مع بدء عمل التطبيق أو عند الحاجة إليها. يستخدم Laravel حاويةَ خدمة Service container لإدارة الاعتمادات بين الأصناف: ماهي الأصناف التي يعتمد عليها الصّنف الجديد للعمل؟ كيف يمكنه الحصول على كائن من هذه الأصناف؟ أين يوجد الصّنف وهل سبق لإطار العمل تحميلُه إلى الذاكرة؟ تمكننا بإعداد مزوّد خدمة وتعريفه إضافةُ صنف إلى حاويّة الخدمة ممّا يسهّل بالتالي استخدامه؛ إذ سيتعرّف إطار العمل على ما يحتاجه هذا الصّنف (أي الاعتمادات) وينشئه إن لم يكن موجودا سلفا.

سنشرح في هذا الدرس أساسيّات إنشاء مزود خدمة في Laravel.

laravel-service-provider.png

نبدأ بإنشاء مسار سنستخدمه للتوضيح:  

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.

]]>326Thu, 26 May 2016 09:22:00 +0000الأحداث (Events) واستخدامها في Laravelhttps://academy.hsoub.com/programming/php/laravel/%D8%A7%D9%84%D8%A3%D8%AD%D8%AF%D8%A7%D8%AB-events-%D9%88%D8%A7%D8%B3%D8%AA%D8%AE%D8%AF%D8%A7%D9%85%D9%87%D8%A7-%D9%81%D9%8A-laravel-r305/

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

laravel-events.png

كانت الطريقة القديمة تقضي بكتابة شفرة برمجية مباشرةً في المتحكّم 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 للدلالة على نجاح الإرسال.

01_eventing_laravel.png

الملف المرفق: الأحداث في Laravel.zip

ترجمة -وبتصرّف- للمقال Eventing in Laravel 5.1 لصاحبه Bill Keck.

]]>305Sun, 22 May 2016 08:13:00 +0000استخدام مكتبة Morris.js لإنشاء مخططات بيانية في Laravelhttps://academy.hsoub.com/programming/php/laravel/%D8%A7%D8%B3%D8%AA%D8%AE%D8%AF%D8%A7%D9%85-%D9%85%D9%83%D8%AA%D8%A8%D8%A9-morrisjs-%D9%84%D8%A5%D9%86%D8%B4%D8%A7%D8%A1-%D9%85%D8%AE%D8%B7%D8%B7%D8%A7%D8%AA-%D8%A8%D9%8A%D8%A7%D9%86%D9%8A%D8%A9-%D9%81%D9%8A-laravel-r304/

يكثُر استخدام المخططات البيانيّة في مواقع الويب لتقريب المعلومة للزّائر. سنرى في هذا الدرس كيفية إنشاء مخطّطات بيانية في تطبيق Laravel باستخدام مكتبة Morris.js.

morris-charts-laravel.png

سنفترض أن لديك مشروع 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 لنجد النتيجة التالية (قد يختلف المخطّط البياني عن الموجود في الصورة بسسب أن البيانات مولَّدة عشوائيا).

01_chart.png

الملف المرفق: laravelchart.zip

ترجمة -وبتصرّف- للمقال Charts in Laravel 5.1 with Morris.js لصاحبه Bill Keck.

]]>304Tue, 10 May 2016 08:19:59 +0000استخدام الصور الرمزية العالمية Gravatar في Laravelhttps://academy.hsoub.com/programming/php/laravel/%D8%A7%D8%B3%D8%AA%D8%AE%D8%AF%D8%A7%D9%85-%D8%A7%D9%84%D8%B5%D9%88%D8%B1-%D8%A7%D9%84%D8%B1%D9%85%D8%B2%D9%8A%D8%A9-%D8%A7%D9%84%D8%B9%D8%A7%D9%84%D9%85%D9%8A%D8%A9-gravatar-%D9%81%D9%8A-laravel-r321/

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

gravatar-laravel.png

إنّ إضافة صورة 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.

]]>321Mon, 02 May 2016 11:29:00 +0000استخدام الاستثناءات Exceptions المخصصة في Laravelhttps://academy.hsoub.com/programming/php/laravel/%D8%A7%D8%B3%D8%AA%D8%AE%D8%AF%D8%A7%D9%85-%D8%A7%D9%84%D8%A7%D8%B3%D8%AA%D8%AB%D9%86%D8%A7%D8%A1%D8%A7%D8%AA-exceptions-%D8%A7%D9%84%D9%85%D8%AE%D8%B5%D8%B5%D8%A9-%D9%81%D9%8A-laravel-r299/

يستخدم Laravel الصنف Handler الموجود على المسار app/Exceptions للتعامل مع جميع الاستثناءات. يحوي هذا الصّنف دالتين: report وrender. تُستخدَم دالة report لتسجيل الاستثناءات أو إرسالها إلى خدمة خارجية؛ أما الدالة render فتُستخدَم لاعتراض الاستثناءات وإرسال إجابة مناسبة إلى المتصفّح ليعرضها للزّائر.

laravel-custom-exceptions.png

ملحوظة: اعتمدنا العروض، المسارات والمتحكّم الذي أنشأناه في درس كيف تستخدم PHPUnit لاختبار تطبيقات Laravel وبنينا عليها لتطبيق الخطوات الواردة هنا. يمكنك تجربة الدّرس على مشروعك الخاص أو استخدام الملفّ المرفَق الذي يمثّل الحصيلة النهائية لهذا الدرس. إن استخدمت الملفّ المرفق فستحتاج لتسجيل مستخدم أولا عبر رابط register والدخول إلى الموقع حتى يظهر بقية المحتوى (سنترك لك اكتشاف الآلية المستخدمة في ذلك. كلمة السّر: المسارات المحميّة).

تخصيص رسائل الاستثناءات

يُعدّ ErrorException أحد أكثر الاستثناءات انتشارا ويظهر مثلا عند إضافة معرف كائن غير موجود إلى مسار URL، أو عند طلب خاصيّة غير موجودة في الكائن. عند محاولة دخول المسار التالي دون أن تكون التسجيلة ذات المعرّف 56 موجودة في جدول البيانات widgets: 

laravel.dev/widget/56

فستظهر في المتصفّح صفحة خطأ كالتالي:

01_ErrorException.png

صفحة الخطأ هذه مفيدة للمطوّرين إلا أننا لا نرغب في أن يراها زوار الموقع؛ لذا يجب علينا التعامل مع هذا الاستثناء وقت حدوثه وعرض رسالة مغايرة للزائر.

نعدّل دالة 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

إن لم يكن الكائن ذو المعرّف موجودا فستظهر رسالة الخطأ التالية:

02_ErrorException.png

تخصيص الاستثناءات

استخدمنا في الفقرة السابقة استثناءً موجودا وخصّصنا النتيجة التي يعرضها للزائر. نريد في هذه الفقرة إنشاء استثناء مخصَّص لتلبية حاجة خاصّة بمشروعنا. سنفرض مثلا أننا نريد إظهار رسالة خطأ للزائر عند تصفّح الرابط /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

لاحظ النتيجة:

03_WidgetCreationException.png

قدّمنا في هذا المقال أساسيات تخصيص الاستثناءات في Laravel؛ ما زال يوجد الكثير لتعلمّه في هذا الإطار انطلاقا من هذه الأساسيات.

حمل الملف المرفق لهذا الدرس.

ترجمة -وبتصرّف- للمقال Handling Exceptions and Custom Exceptions in Laravel 5.1 لصاحبه Bill Keck.

]]>299Tue, 19 Apr 2016 11:43:38 +0000