دليل: دمج فيديوهاتي في مشروع Laravel 11

ثبّت حزمة videohati/laravel، واضبط مفتاحك، وارفع فيديو، وأنشئ جلسة تشغيل، ثم ضمّن المشغّل في عرض Blade.

يربط هذا الدليل حزمة Laravel الرسمية بتطبيق Laravel 11. سترفع فيديو من الخادم، وتنشئ جلسة تشغيل، وترسم المشغّل عبر موجِّه Blade المرفق.

قبل أن تبدأ

تحتاج إلى:

تطبيق Laravel 11 يعمل على PHP 8.2 أو أحدث.
مفتاح واجهة برمجية للمشروع في الوضع التجريبي (vh_test_...).
مُعرّف مشروعك (يستخدمه تضمين المشغّل).

1. ثبّت الحزمة

composer require videohati/laravel

تكتشف الحزمة مزوّد خدمتها وواجهة Videohati تلقائيًا — فلا حاجة إلى تسجيل يدوي.

2. اضبط البيئة

أضف بيانات الاعتماد إلى .env:

VIDEOHATI_API_KEY=vh_test_xxxxxxxxxxxxxxxxxxxxx
VIDEOHATI_PROJECT_ID=01JZ9WV3N8GQ5T2M7K4C6XBARP

ويمكنك اختياريًا نشر ملف الإعداد لضبط الرابط الأساسي أو رابط المشغّل أو المهلة:

php artisan vendor:publish --tag=videohati-config

أبقِ VIDEOHATI_API_KEY خارج نظام التحكّم بالإصدارات. فالمفتاح مرتبط بالمشروع ويمنح صلاحية الكتابة.

3. ارفع فيديو

ينفّذ videos()->upload() تدفّق الرفع المُجزّأ كاملًا: إنشاء الفيديو، وفتح جلسة الرفع، وإرسال كل جزء عبر PUT إلى نقطة الرفع، ثم إكمال الرفع. ويعيد حمولة الإكمال متضمّنةً videoId.

use Videohati\Laravel\Facades\Videohati;

$result = Videohati::videos()->upload(
    storage_path('app/lectures/lecture-01.mp4'),
    onProgress: function (int $uploaded, int $total) {
        logger()->info("Uploaded {$uploaded} / {$total} bytes");
    },
);

$videoId = $result['videoId'];

تفضّل التحكّم اليدوي؟ يتوفّر التدفّق نفسه عبر videos()->create() و videos()->startUpload() ثم طلبات PUT لكل جزء و videos()->completeUpload().

4. انتظر حتى يصبح الفيديو جاهزًا

يجري الترميز بعد اكتمال الرفع. استعلم عبر videos()->get() وافحص قيمة state في الكائن حتى تصبح ready:

use Videohati\Laravel\Facades\Videohati;

do {
    sleep(3);
    $video = Videohati::videos()->get($videoId);
} while (!in_array($video->state, ['ready', 'failed'], true));

abort_if($video->state === 'failed', 422, 'Encoding failed');

5. أنشئ جلسة تشغيل

أنشئ الجلسة على الخادم، ثم مرّر sessionToken وحده إلى العرض — لا مفتاح الواجهة البرمجية.

use Videohati\Laravel\Facades\Videohati;

$session = Videohati::playback()->createSession(
    videoId: $videoId,
    viewerDisplayText: auth()->user()->email, // يظهر في العلامة المائية
);

return view('watch', [
    'videoId' => $videoId,
    'sessionToken' => $session->sessionToken,
]);

يكشف الكائن المُعاد PlaybackSessionDto الحقول sessionId وmanifestUrl و sessionToken وwatermarkToken وexpiresAt وheartbeatIntervalSeconds.

6. ضمّن المشغّل في عرض Blade

تأتي الحزمة بموجِّه Blade باسم @videohatiPlayer يُخرج وسم <script> للمشغّل مع عنصر <div> الذي يُركّب عليه. وتأخذ قيمة projectId افتراضيًا من VIDEOHATI_PROJECT_ID.

{{-- resources/views/watch.blade.php --}}
<!doctype html>
<html lang="en" dir="ltr">
  <body>
    @videohatiPlayer([
        'videoId' => $videoId,
        'sessionToken' => $sessionToken,
        'lang' => 'en',
        'autoplay' => 'muted',
    ])
  </body>
</html>

وللعربية، اضبط 'lang' => 'ar' وdir="rtl" على <html>:

<html lang="ar" dir="rtl">
  <body>
    @videohatiPlayer([
        'videoId' => $videoId,
        'sessionToken' => $sessionToken,
        'lang' => 'ar',
    ])
  </body>
</html>

هذا هو المسار الكامل: الرفع على الخادم، وإنشاء جلسة، وتضمين المشغّل — كل ذلك دون كشف مفتاح الواجهة البرمجية للمتصفح.