كيفية دمج Supabase مع Laravel لقاعدة البيانات والتخزين

إنفورماتيك ديجيتال » الموارد » كيفية دمج Supabase مع Laravel لقواعد البيانات والتخزين

إذا كنت تعمل باستخدام Laravel وتُكرّس وقتك لبرمجة الواجهة الخلفية ، وتتطلع إلى الانتقال إلى قاعدة بيانات PostgreSQL حديثة مُدارة مثل Supabase ، فربما تكون قد أدركت أن مجرد تغيير بعض المتغيرات في ملف .env لا يكفي. فهناك تفاصيل الاتصال، والمخططات، والمصادقة، وتخزين الملفات التي قد يؤدي إهمالها إلى ظهور أخطاء غامضة.

علاوة على ذلك، عندما ترغب في المضي قدمًا واستخدام Supabase كوحدة تخزين ملفات متكاملة مع نظام القرص الخاص بـ Laravel (Storage)، تصبح الأمور أكثر تعقيدًا بعض الشيء: مفاتيح الخدمة، والمجلدات، ونقاط النهاية، وبرامج تشغيل Flysystem المخصصة، وما إلى ذلك. والخبر السار هو أنه يمكن دمج كل شيء بشكل مثالي - قاعدة البيانات والتخزين ومعالجة UUID - بطريقة سلسة إلى حد ما.

ربط Laravel بقاعدة بيانات Supabase

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

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

للحصول على تفاصيل الاتصال، سجّل الدخول إلى لوحة تحكم Supabase الخاصة بك وأنشئ مشروع قاعدة بيانات جديدًا (يمكنك القيام بذلك مباشرةً من خلال `database.new` ، الذي يُعيد توجيهك إلى المعالج). إذا لم يكن لديك حساب بعد، فسترى أولًا شاشة التسجيل؛ أما إذا كان لديك حساب بالفعل، فستنتقل مباشرةً إلى إعدادات المشروع والقسم الذي يمكنك فيه العثور على سلسلة الاتصال.

في صفحة المشروع، ضمن قسم الاتصال، ستجد زر "اتصال" أو ما شابه. بالنقر عليه، ستظهر لك عدة صيغ لسلسلة الاتصال (URI، معلمات فردية، إلخ). انسخ عنوان URI بالكامل، ولكن تذكر استبدال كلمة المرور بكلمة المرور التي تستخدمها فعليًا لقاعدة البيانات، حيث غالبًا ما يتم عرض كلمة مرور افتراضية أو عنصر نائب.

باستخدام هذه المعلومات، عليك الانتقال إلى ملف ‎.env الخاص بمشروع Laravel الخاص بك وتحديث المتغيرات DB_HOST وDB_PORT وDB_DATABASE وDB_USERNAME وDB_PASSWORD، أو ضبط متغير DATABASE_URL إذا كنت تفضل استخدام تنسيق السلسلة الكامل. الهدف هو ضمان أن جميع البيانات تشير إلى مجموعة خوادم Supabase Postgres وليس إلى جهازك المحلي.

تكوين برنامج تشغيل Postgres ومخطط Supabase في Laravel

في Laravel، يُعدّ ملف config/database.php الملف الرئيسي لتكوين قاعدة البيانات . على الرغم من إمكانية استخدام برنامج تشغيل pgsql المرفق مع الإطار مباشرةً، إلا أنه عند العمل مع Supabase، من الشائع تطبيق بعض الإعدادات الإضافية، خاصةً فيما يتعلق بالمخططات وخيارات Postgres الخاصة.

قد يبدو تكوين Postgres النموذجي في Laravel على النحو التالي، ضمن مصفوفة الاتصالات، تحت المفتاح 'pgsql' :

'pgsql' => ,

يكمن المفتاح هنا في مُعامل `search_path` . يستخدم Supabase، افتراضيًا، مخطط `public`، وهو المخطط المُتاح عبر واجهات برمجة التطبيقات الخاصة به. إذا كنت ترغب في إبقاء تطبيق Laravel الخاص بك منفصلاً عن هذا المخطط وتجنب تعارضات الجداول أو السياسات، يُنصح بشدة بتغيير `search_path` إلى مخططك الخاص، على سبيل المثال، `laravel` ، كما هو موضح في المثال السابق.

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

بعد تعديل ملف الإعدادات، يمكنك تشغيل عمليات الترحيل باستخدام أوامر Laravel القياسية. سيؤدي ذلك إلى إنشاء جداول المصادقة وأي جداول أخرى قمت بتعريفها. إذا تم تكوين كل شيء بشكل صحيح، فسيتم تشغيل الأوامر تلقائيًا على خادم Supabase Postgres.

بعد اكتمال عمليات الترحيل، شغّل خادم التطوير باستخدام الأمر `artisan serve`، ثم حاول تسجيل المستخدمين وتسجيل دخولهم. إذا لم تظهر أي أخطاء في الاتصال أو الترحيل، فهذا يعني أن Laravel يتواصل بشكل صحيح مع Supabase ، ويمكنك متابعة بناء منطق عملك كالمعتاد.

استخدام برنامج تشغيل Supabase محدد في Laravel

على الرغم من أن برنامج تشغيل pgsql القياسي يعمل، إلا أن هناك حزمة تضيف برنامج تشغيل قاعدة بيانات supabase لـ Laravel ، مما يوسع سلوك PostgreSQL بتحسينات مفيدة للغاية، خاصة فيما يتعلق بمعالجة أعمدة UUID وطريقة إنشاء الاستعلامات.

يتم تثبيت هذه الحزمة، الموزعة باسم prahsys/laravel-supabase، عبر Composer، وتُسجّل مُشغّلًا إضافيًا يُسمى supabase، والذي يُمكنك استخدامه في ملف config/database.php. يعتمد هذا المُشغّل داخليًا على مُشغّل Postgres الخاص بـ Laravel، ولكنه يتضمن إعدادات وقواعد استعلام مُحسّنة لبيئة Supabase المُحددة.

بعد التثبيت، يمكنك تعريف شيء مثل التالي ضمن قسم الاتصالات :

'connections' => ,
    // otras conexiones...
],

تكمن ميزة استخدام هذا المُشغّل في أنه يمنحك كامل إمكانيات محرك Postgres، ولكنه في الوقت نفسه يُعالج تلقائيًا بعض التفاصيل الدقيقة في Supabase، خاصةً عند التعامل مع مُعرّفات UUID كمفاتيح أساسية أو حقول علاقات . وهذا يُغنيك عن كتابة عمليات التحويل يدويًا في كل استعلام مُعقّد.

تم تصميم الحزمة أيضًا لتتناسب بشكل جيد مع الإصدارات الحديثة من الإطار و PHP، مما يوفر توافقًا رسميًا مع Laravel 10.x و 11.x و 12.x ومع PHP من الإصدار 8.1 فصاعدًا، بالإضافة إلى أي قاعدة بيانات PostgreSQL قياسية، بما في ذلك Supabase بالطبع.

لضمان عمل كل شيء بشكل صحيح، تتضمن الحزمة مجموعة من الاختبارات الآلية. يمكنك تشغيل الاختبارات باستخدام الأمر `composer test`، الذي سيستخدم قاعدة بيانات SQLite في الذاكرة لتحسين السرعة، أو يمكنك إعداد ملف `.env.testing` يشير إلى قاعدة بيانات Supabase الخاصة بك وتشغيل الأمر `composer test-supabase` للتحقق من السلوك في بيئة حقيقية مع قاعدة بيانات Postgres عن بُعد.

إدارة UUID في Supabase وLaravel

يُعاني Supabase من مشكلة خاصة في التعامل مع أعمدة UUID: إذا حاولتَ مقارنة UUID مباشرةً بسلسلة نصية دون تحويل نوع البيانات، فقد يفشل الاستعلام أو يُعيد نتائج غير متوقعة . في بيئة Postgres الأساسية، يُمكنك حل هذه المشكلة باستخدام تحويلات عامة أو عوامل تشغيل مُخصصة، لكن Supabase لا يسمح بمثل هذه التخصيصات العامة.

وهذا يعني أن الاستعلام المباشر عن النمط:

SELECT *
FROM users
WHERE id = '123e4567-e89b-12d3-a456-426614174000';

لن ينجح الأمر كما تتوقع. ولكن، إذا قمت بالتحويل الصريح:

SELECT *
FROM users
WHERE CAST(id AS TEXT) = '123e4567-e89b-12d3-a456-426614174000';

تم تنفيذ الاستعلام بنجاح. تكمن المشكلة في أنه في Laravel، عند كتابة الاستعلامات باستخدام Eloquent أو أداة إنشاء الاستعلامات، لا يُنصح بإضافة عمليات تحويل (CAST) إلى كل شرط WHERE . هنا يأتي دور برنامج تشغيل supabase من الحزمة المذكورة سابقًا، والذي يُضيف عمليات التحويل هذه تلقائيًا.

مع تفعيل هذا البرنامج التشغيلي، يمكنك إجراء استعلامات شائعة مثل:

$user = User::find($uuidString);
$user = User::where('id', $uuidString)->first();
$users = User::whereIn('id', )->get();

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

$posts = Post::join('users', 'posts.user_id', '=', 'users.id')
    ->where('users.email', '[email protected]')
    ->get();

يتولى برنامج التشغيل تطبيق تحويلات النصوص اللازمة على أعمدة UUID ذات الصلة تلقائيًا. وبهذه الطريقة، يظل كودك متوافقًا مع لغة Laravel، ولن تحتاج إلى كتابة استعلامات SQL مباشرة أو استخدام حيل معقدة في كل استعلام.

إذا كنت ترغب في تحكم أدق في الأعمدة التي تُعتبر مُعرّفات فريدة عالمية (UUIDs)، فإن الحزمة توفر سمة CastsUuidColumns لنماذج Eloquent الخاصة بك. ما عليك سوى استخدامها في فئة النموذج الخاصة بك وتحديد مصفوفة محمية من الأعمدة الإضافية.

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

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

في الحالات الأكثر تعقيدًا ، يمكنك تسجيل كاشف أعمدة UUID مخصص. باستخدام PostgresGrammar من الحزمة، يمكنك تحديد دالة رد نداء، بناءً على اسم العمود أو سياق الاستعلام، لتحديد ما إذا كان ينبغي التعامل معه كـ UUID. على سبيل المثال:

use Prahsys\Supabase\Database\Query\Grammars\PostgresGrammar;

PostgresGrammar::detectUuidColumnsWith(function ($columnName, $query) {
    return str_contains($columnName, 'uuid_')
        || in_array($columnName, );
});

مع إعداد هذه الوظيفة، يمكن للنظام اعتبار جميع الأعمدة التي تحتوي أسماؤها على نمط معين أو تقع ضمن قائمة محددة بمثابة UUID، مما يسمح له بالتكيف مع اصطلاحات التسمية الخاصة بمشروعك.

دمج Supabase Storage كنظام ملفات في Laravel

بالإضافة إلى قاعدة البيانات، تحتاج العديد من المشاريع إلى تخزين الصور والمستندات والملفات الأخرى التي يرفعها المستخدمون. يتضمن Supabase خدمة تخزين قائمة على الحاويات، يمكنك استخدامها كقرص تخزين لـ Laravel عبر Flysystem . يتوفر محول خاص للتعامل مع تخزين Supabase كبرنامج تشغيل إضافي ضمن ملف config/filesystems.php.

توفر هذه الحزمة مُهايئ Flysystem الذي يتكامل بسلاسة مع نظام التخزين الخاص بإطار العمل. وهي تُلبي الحد الأدنى من متطلبات PHP 8.1 والإصدارات الأحدث، وLaravel 10.x و11.x ، بالإضافة إلى إضافة PHP fileinfo (ext-fileinfo) التي يُوصي بها Laravel عادةً لإدارة الملفات. يتم التثبيت باستخدام Composer، وبعد تضمين الحزمة، ما عليك سوى تحديد قرص supabase في ملف الإعدادات.

في ملف config/filesystems.php ، ضمن مصفوفة الأقراص، ستضيف شيئًا مشابهًا لما يلي:

'supabase' => ,
    ],
    'signedUrlExpires' => 60 * 60 * 24,
],

عادةً ما يكون مُعامل `bucket` هو اسم حاوية التخزين التي أنشأتها في لوحة تحكم Supabase (على سبيل المثال، `myapp-file-uploads`). أما `endpoint` فهو عنوان URL الأساسي لخدمة تخزين المشروع، والذي يظهر أيضًا في القسم المُناسب من لوحة التحكم، ويُشتق عادةً من عنوان URL للمشروع والمنطقة.

يُشير خيار `public` إلى ما إذا كان سيتم التعامل مع محتويات الحاوية على أنها عامة افتراضيًا. إذا كانت قيمته `true`، فسيقوم المُهايئ بإنشاء عناوين URL قابلة للوصول دون توقيع خاص؛ أما إذا كانت قيمته `false`، فسيتم تفعيل خيار `defaultUrlGeneration`، الذي يُمكنه فرض إنشاء عناوين URL مُوقّعة مع تحديد وقت انتهاء الصلاحية بواسطة `signedUrlExpires`. يُتيح لك هذا الإعداد تحقيق التوازن بين الأمان وسهولة الاستخدام بناءً على نوع الملفات التي تتعامل معها.

يُترك عنوان URL العام للقرص عادةً فارغًا ليقوم المحول باستخلاصه تلقائيًا من نقطة النهاية. لا تُعدّله إلا إذا كنت تستخدم خادم وكيل وسيط أو شبكة توصيل محتوى (CDN) وتريد أن تشير المسارات المُنشأة إلى ذلك النطاق بدلاً من نطاق Supabase الأصلي.

استكشاف أخطاء التحميل وإصلاحها وفهم مفتاح تخزين Supabase

من المشاكل الشائعة عند محاولة تحميل الملفات إلى وحدة تخزين Supabase من Laravel ظهور رسائل مثل "تعذر كتابة الملف في الموقع: uploads/..." . يشير هذا عادةً إلى أنه على الرغم من تهيئة برنامج التشغيل، إلا أن Supabase يرفض عملية الكتابة بسبب عدم كفاية الصلاحيات أو إعداد مفتاح غير صحيح.

في ملف تهيئة قرص Supabase، `config/filesystems.php`، يُحدد الإعداد استخدام "مفتاح مميز" في حقل `key`، مع التأكيد صراحةً على أن المفتاح للقراءة فقط لن يعمل. هذا يعني أنه يجب عليك استخدام مفتاح خدمة بصلاحيات كتابة إلى الحاوية، وليس مجرد مفتاح API عام من جانب العميل أو مفتاح توافق S3 بدون صلاحيات تعديل.

في لوحة Supabase، ضمن قسم إعدادات واجهة برمجة التطبيقات والتخزين، ستجد مفاتيح مجهولة ومفاتيح دور الخدمة (أو ما يعادلها) ، والتي تتمتع بصلاحيات موسعة. يجب عليك وضع مفتاح الخدمة هذا، وليس المفتاح العام، في متغير SUPABASE_SECRET_ACCESS_KEY، والذي سيقرأه برنامج التشغيل باستخدام env('SUPABASE_SECRET_ACCESS_KEY').

إذا كنت تختبر باستخدام مفتاح S3 من إعدادات التخزين أو باستخدام مفاتيح API العامة للمشروع، فمن المرجح جدًا أن هذه البيانات لا تملك صلاحيات الكتابة إلى الحاوية المحددة، مما يؤدي إلى خطأ الكتابة. عادةً ما يؤدي تغيير قيمة المفتاح إلى مفتاح خدمة صالح بصلاحيات الكتابة والتأكد من وجود الحاوية واسمها الصحيح إلى حل المشكلة.

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

سير العمل مع Laravel Breeze وBlade وSupabase Storage

بعد إعداد قاعدة البيانات ومساحة التخزين، تتمثل الخطوة المنطقية التالية في دمج كل شيء مع واجهة Laravel Breeze وقوالب Blade . بهذه الطريقة، يمكن للمستخدمين التسجيل والتحقق من الهوية وتحميل الملفات إلى Supabase دون مغادرة بيئة Laravel.

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

if ($request->hasFile('file')) {
    $path = $request->file('file')
        ->store('uploads', 'supabase');
}

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

تتمثل ميزة هذا الأسلوب في أن تطبيقك يحتفظ بواجهة تخزين واحدة، بغض النظر عما إذا كان يستخدم القرص المحلي، أو Amazon S3، أو Supabase، أو أي خدمة أخرى مدعومة. ويقتصر تغيير مزود الخدمة على تعديل ملف config/filesystems.php ومتغيرات البيئة، دون التأثير على منطق العمل.

بدمج هذه الميزة مع Blade وBreeze، يمكنك توفير نماذج تحميل الملفات، وقوائم الملفات، وروابط التنزيل بشكل متكامل تمامًا مع تجربة مستخدم تطبيقك. علاوة على ذلك، يتيح لك نهج Supabase Storage القائم على الحاويات والسياسات الاستفادة من ضوابط الوصول وقواعد الأمان لتحديد ما يمكن لكل مستخدم عرضه أو تنزيله.

تتيح هذه المنظومة المتكاملة من الحزم وبرامج التشغيل والإعدادات لـ Laravel العمل بسلاسة مع Supabase، سواءً فيما يتعلق بالبيانات العلائقية مع Postgres أو تخزين الملفات وإدارة UUID . من خلال ضبط المفاتيح والمخططات وبرامج التشغيل بشكل صحيح، يمكنك تحقيق تكامل قوي للغاية يتجنب العديد من الأخطاء الشائعة التي تُصادف عند محاولة ربط المنصتين يدويًا دون هذه الطبقات الداعمة.

يتيح لك ربط Laravel بـ Supabase لقاعدة البيانات والتخزين، والاستفادة من برنامج تشغيل Supabase المخصص لإدارة UUIDs بدون متاعب، واستخدام محول Flysystem للتخزين، بناء تطبيقات حديثة حيث يتم تغليف جميع البنية التحتية المعقدة خلف واجهة برمجة تطبيقات Laravel النظيفة، بدءًا من عمليات الترحيل والمصادقة وحتى تحميل الملفات إلى حاويات آمنة.