عرض مصدر Laravel/horizon

<noinclude>{{DISPLAYTITLE:Laravel Horizon}}</noinclude>
== مقدمة ==
يوفّر Horizon لوحة تحكم جميلة و إعدادات برمجيّة لطوابير ‏‎(Queues) Laravel المبنيّة على [[Redis]]، فهو يوفّر لك مراقبة سهلة للمقاييس الأساسية لنظام الطوابير مثل إنتاجيّة العمل ووقت التشغيل، وفشل المهام.

ستبقى جميع عمليّات الضبط في ملف ضبط واحد وبسيط ممّا يضمن التعاون الكامل بين أعضاء فريقك.

== التثبيت ==
'''تنبيه''': يتطلّب ‎،Horizon نظرًا لاستخدامه لإشارات العمليّة غير متزامنة، إلى نسخة PHP‏ 7.1‏ فما فوق. ويجب عليك التأكّد من تعيين محرك الطابور إلى Redis في ملف ضبط الطابور.

يمكنك استخدام <code>Composer</code> لتثبيت Horizon في مشروع [[Laravel]] الخاص بك:<syntaxhighlight lang="bash">
composer require laravel/horizon
</syntaxhighlight>

بعد تثبيت Horizon، يمكننا استخدام أداة Artisan لنشر الأصول (Assets) باستخدام <code>vendor:publish</code>:<syntaxhighlight lang="bash">
php artisan vendor:publish --provider="Laravel\Horizon\HorizonServiceProvider"
</syntaxhighlight>

=== الضبط ===
سيتكوّن ملف الضبط الأساسي في <code>config/horizon.php</code> بعد نشر أصول Horizon، ويسمح لك هذا الملف بضبط خيارات العامل ويحتوي كل خيار ضبط على وصف لعمله، لذا تأكّد من الاطلاع على هذا الملف بشكل جيّد.

==== خيارات التوازن ====
يسمح لك Horizon بالاختيار بين ثلاثة استراتيجيات توازن: <code>simple</code> و <code>auto</code> و <code>false</code>. تُقسّم الاستراتيجية simple (والتي هي الافتراضيّة) الوظائف الواردة بالتساوي بين العمليات:<syntaxhighlight lang="php">
'balance' => 'simple',
</syntaxhighlight>

تضبط الاستراتيجيّة <code>auto</code> عدد عمليات العامل لكل طابور بالاعتماد على حجم العمل الحالي في قائمة الانتظار. فعلى سبيل المثال، إذا كان طابور notifications يحتوي على 1000 مهمة قيد الانتظار في حين أن طابور render فارغ، فسيخصص Horizon أكثر عمال لطابور notifications إلى أن ينتهي.

في حالة كان خيار التوازن <code>false</code>، فسيُستخدم سلوك [[Laravel]] الافتراضي، والذي يعالج الطوابير بالترتيب الموجود في ملف الضبط.

=== استيثاق لوحة التحكم ===
يعرض Horizon لوحة التحكم في <code>‎/horizon</code>، ويمكنك الوصول إلى لوحة التحكم بشكل افتراضي من خلال البيئة المحليّة (local) فقط، ولتحديد سياسة وصول محددة أكثر للوحة التحكم، يمكنك استخدام التابع  <code>Horizon::auth</code>.

يقبل التابع auth رد نداء (callback) والذي يُرجع القيمة <code>true</code> أو القيمة <code>false</code> للإشارة ما إذا كان المستخدم يمكنه الوصول إلى لوحة تحكم Horizon، وعادةً، يجب عليك استدعاء التابع <code>Horizon::auth</code> في التابع boot من <code>AppServiceProvider</code>:<syntaxhighlight lang="php">
Horizon::auth(function ($request) {
   // return true / false;
});
</syntaxhighlight>

== تشغيل Horizon ==
بمجرّد ضبط العاملين في ملف الضبط <code>config/horizon.php</code>، يمكنك بدء تشغيل Horizon باستخدام الأمر Artisan، وهذا الأمر المنفرد سيشغّل جميع العاملين المكوّنين:<syntaxhighlight lang="bash">
php artisan horizon
</syntaxhighlight>

يمكنك إيقاف عمل Horizon بشكل مؤقت واستئناف عمل المهام باستخدام أوامر <code>Artisan</code> وهي <code>horizon:pause</code> و <code>horizon:continue</code>:<syntaxhighlight lang="bash">
php artisan horizon:pause

php artisan horizon:continue
</syntaxhighlight>

يمكنك إنهاء عمل Horizon الرئيسي بأمان على جهازك باستخدام أمر  <code>horizon:terminate</code> Artisan، وستكتمل أي مهام يعالجها Horizon ومن ثم سيتوقف:<syntaxhighlight lang="bash">
php artisan horizon:terminate

</syntaxhighlight>

=== نشر Horizon على الخادم الإنتاجي ===
إذا كنت ترغب في نشر Horizon على الخادم الإنتاجي، فيجب عليك ضبط مراقب العمليّة (process monitor) لمراقبة أمر <code>php artisan horizon</code> وإعادة تشغيله إذا انتهى بشكل غير متوقع.

عند نشر شيفرات برمجيّة جديدة على خادمك، ستحتاج إلى إنهاء Horizon حتى تتمكن من إعادة تشغيله عن طريق مراقب العمليّة Supervisor وتلقي التغييرات الجديدة في الشيفرات البرمجيّة.

==== ضبط المشرف ====
إذا كنتَ تستخدم برمجية Supervisor لمراقبة العمليات لكي تدير عملية Horizon. الخاصة بك، فهذا الملف سيكون كافيًا:<syntaxhighlight lang="php">
[program:horizon]
process_name=%(program_name)s
command=php /home/forge/app.com/artisan horizon
autostart=true
autorestart=true
user=forge
redirect_stderr=true
stdout_logfile=/home/forge/app.com/horizon.log
</syntaxhighlight>

ملاحظة: فكر في استخدام Laravel Forge إذا كنت لا ترغب في إدارة خوادمك الخاصة، فهو يوفّر لك خوادم PHP 7+‎ مع كل ما تحتاجه لتشغيل تطبيقات Laravel حديثة وقويّة مع Horizon.

== الوسوم ==
يوفر لك Horizon إمكانيّة تعيين وسوم على الوظائف (jobs)، بما في ذلك البريد، وبث الأحداث والإشعارات ومستمعي الأحداث في الطابور. في الواقع، سيضع Horizon بشكل تلقائي وذكي الوسوم لمعظم الوظائف بالاعتماد على نماذج [[Laravel/eloquent|Eloquent]] المرتبطة بالوظيفة. فعلى سبيل المثال، ألقِ نظرة على المهمة التالية:<syntaxhighlight lang="php">
<?php

namespace App\Jobs;

use App\Video;
use Illuminate\Bus\Queueable;
use Illuminate\Queue\SerializesModels;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;

class RenderVideo implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    /**
     * هذا مثيل الفيديو.
     *
     * @var \App\Video
     */
    public $video;

    /**
     * إنشاء مثيل مهمة جديد.
     *
     * @param  \App\Video  $video
     * @return void
     */
    public function __construct(Video $video)
    {
        $this->video = $video;
    }

    /**
     * تنفيذ المهمة.
     *
     * @return void
     */
    public function handle()
    {
       //
    }
}
</syntaxhighlight>

إذا وُضعت وظيفة في الطابور مع نسخة <code>App\Video</code> التي تملك معرّف يساوي 1، فستحصل بشكل تلقائي على الوسم <code>App\Video:1</code>. وهذا لأن Horizon سيدرس خصائص الوظيفة لأي نموذج <code>Eloquent</code>، فإذا وُجد نموذج <code>Eloquent</code>، سيضع Horizon الوسم بذكاء في الوظيفة باستخدام اسم صنف النموذج والمفتاح الرئيسي.<syntaxhighlight lang="php">
$video = App\Video::find(1);

App\Jobs\RenderVideo::dispatch($video);
</syntaxhighlight>

=== وضع الوسوم يدويًا ===
إذا كنت ترغب في تحديد الوسوم لأحد الكائنات التي يمكن أن تضعها على الطابور، فيمكنك تحديد التابع <code>tags</code> في الصنف:<syntaxhighlight lang="php">
class RenderVideo implements ShouldQueue
{
    /**
     * للحصول على الوسوم المستندة إلى المهمة
     *
     * @return array
     */
    public function tags()
    {
        return ['render', 'video:'.$this->video->id];
    }
}
</syntaxhighlight>

== الإشعارات ==
ملاحظة: قبل استخدام الإشعارات، يجب عليك إضافة حزمة guzzlehttp/guzzle Composer إلى مشروعك، وعند تهيئة Horizon لإرسال إشعارات SMS، يجب عليك في هذه الحالة مراجعة المتطلبات الأساسيّة لبرنامج تشغيل الإشعارات Nexmo.

إذا كنت ترغب في أن تُعلم عندما يكون وقت انتظار إحدى الطوابير طويل، فيمكنك استخدام توابع <code>Horizon::routeMailNotificationsTo</code> و <code>Horizon::routeSlackNotificationsTo</code> و<code>Horizon::routeSmsNotificationsTo</code>، ويمكنك استدعاء هذه التوابع من مقدّم الخدمة <code>AppServiceProvider</code> الخاص بك:<syntaxhighlight lang="php">
Horizon::routeMailNotificationsTo('example@example.com');
Horizon::routeSlackNotificationsTo('slack-webhook-url', '#channel');
Horizon::routeSmsNotificationsTo('15556667777');
</syntaxhighlight>

ضبط الإشعارات للحدود القصوى لوقت الانتظار

يمكنك وضع عدد الثواني التي تُعتبر "وقت انتظار طويل" من خلال ملف الضبط <code>config/horizon.php</code>، ويتيح لك خيار الضبط <code>waits</code> داخل هذا الملف بالتحكم بأقصى حد للانتظار لكل تجميعة اتصال/طابور:<syntaxhighlight lang="php">
'waits' => [
    'redis:default' => 60,
],

</syntaxhighlight>

== المقاييس Metrics ==
يحتوي Horizon على لوحة تحكم بالمقاييس التي توفر المعلومات عن وظيفتك ووقت انتظار الطابور والإنتاجيّة (throughput). ولتعبئة لوحة التحكم، يجب ضبط أمر <code>Artisan snapshot</code> للعمل كل خمسة دقائق عبر مجدول التطبيق الخاص بك:<syntaxhighlight lang="php">
/**
 * تعريف أمر التطبيق schedule.
 *
 * @param  \Illuminate\Console\Scheduling\Schedule  $schedule
 * @return void
 */
protected function schedule(Schedule $schedule)
{
    $schedule->command('horizon:snapshot')->everyFiveMinutes();
}
</syntaxhighlight>

== مصادر ==
* [https://laravel.com/docs/5.6/horizon صفحة Horizon في توثيق Laravel الرسمي].
[[تصنيف:Laravel|{{SUBPAGENAME}}]]
[[تصنيف:Laravel Official Packages|{{SUBPAGENAME}}]]