ما هو PrizeX
PrizeX منصة جوائز وألعاب وسوق مبنية على PHP: مزادات ويانصيب وصناديق مفاجآت ومجموعة ألعاب أركيد ومتجر تجارة إلكترونية متعدد البائعين واقتصاد محفظة وعملات — كل ذلك في تطبيق واحد ذاتي الاستضافة. وتُشحن ببنية قائمة على الإضافات والقوالب، مع لوحة تحكم و38 إضافة بوابة دفع تغطي البطاقات والمحافظ والعملات الرقمية والمعالجات الإقليمية، إضافةً إلى 3 وسائل دفع يدوية مضمّنة في النواة.
لا ارتباط بأي خدمة SaaS: تثبّتها على استضافتك أنت، وتملك قاعدة البيانات، وتحصل على تحديثات مدى الحياة ضمن الترخيص. ويمكن تشغيل كل وحدة (المزادات واليانصيب وصناديق المفاجآت والألعاب والمتجر) أو تعطيلها بشكل مستقل من لوحة التحكم — فالتثبيت الجديد يمكن أن يعمل كمنتج بوحدة واحدة أو كحزمة كاملة.
الكود الأساسي لا يعتمد أبدًا اعتمادًا إلزاميًا على أي إضافة. فكل وحدة وكل بوابة دفع وكل تسجيل دخول اجتماعي هي إضافة تحت plugins/ يمكن تفعيلها أو تعطيلها أو حذفها دون أن يتعطل باقي الموقع.
بادئة الجداول tbl_، دون أي ORM، ومع استخدام العبارات المُعدّة في الغالب. وكل إضافة تملك جداولها الخاصة وتُرحّلها عبر مثبّت db_delta() يمكن تشغيله مرارًا بأمان.
البيئة التي تعمل عليها
يعمل PrizeX على الاستضافة المشتركة العادية أو على خادم افتراضي خاص — دون أي إعداد خاص للخادم سوى خادم ويب يدعم إعادة كتابة الروابط.
* عدة ملفات ضمن database/migrations/ تستخدم امتداد ADD COLUMN IF NOT EXISTS الخاص بـ MariaDB وحدها، وMySQL 8.0/8.4 العادي يرفضه — لذا استخدم MariaDB لقاعدة البيانات، في التطوير والإنتاج معًا.
تشغيل تثبيت جديد
لا يوجد معالج تثبيت للإعداد الجديد — أنت تستورد المخطط مباشرةً وتضبط ملف البيئة.
- ثبّت اعتماديات PHP:
composer install - انسخ قالب ملف البيئة واملأ بيانات اعتماد قاعدة البيانات:
cp .env.example .env - استورد
database/production.sqlإلى قاعدة البيانات المذكورة في ملف.env— وهذا ينشئ المخطط كاملًا. - استبدل حساب المشرف المضمَّن مسبقًا (انظر التنبيه أدناه)، ثم سجّل الدخول من
/admin/.
database/production.sql صفًا في tbl_admin (admin@wowcodes.in) تكون قيمة تجزئة كلمة مروره متطابقة في كل تثبيت. احذفه وأدرج حسابك أنت قبل الإطلاق:
php -r "echo password_hash('your-password', PASSWORD_BCRYPT), \"\n\";"DELETE FROM tbl_admin;
INSERT INTO tbl_admin (username, email, password, image, status, permission_settings)
VALUES ('yourname', 'you@example.com', '<hash from the command above>', '', 1, 1);للتطوير المحلي، يعمل خادم PHP المدمج دون الحاجة إلى Apache: php -S localhost:8000 router.php — ولاحظ أن هذا الخادم يتجاهل .htaccess تمامًا، لذا يعيد router.php تطبيق قواعد التوجيه نفسها يدويًا (انظر إعداد خادم الويب).
متغيرات البيئة
جميع الإعدادات الخاصة بالبيئة موجودة في .env، ويُحمَّل عبر vlucas/phpdotenv. انسخ .env.example إلى .env (المستثنى من git) واضبط القيم الحقيقية لكل بيئة — بيانات اعتماد قاعدة البيانات على الأقل، قبل استيراد المخطط.
أما الإعدادات العامة للموقع التي لا تتعلق بالبيئة (اسم التطبيق والعملة والإضافات المفعّلة والقالب المفعّل ومفاتيح تشغيل كل وحدة) فتوجد في قاعدة البيانات ضمن tbl_settings، وتُدار من لوحة التحكم لا من الملفات.
إعداد خادم الويب
قواعد التوجيه والأمان — الروابط النظيفة، ومنع الوصول المباشر إلى .env/connection.php/ملفات السجل، ومنع تنفيذ المحتوى المرفوع ككود PHP — معرَّفة في ملفات .htaccess الموزَّعة في أنحاء المشروع. ويقرأها Apache وLiteSpeed/OpenLiteSpeed أصلًا دون إعداد إضافي.
على nginx، استخدم nginx.conf.example الذي يعكس كل قاعدة من تلك القواعد داخل كتلة server{} في nginx — عدّل server_name وroot ومقبس PHP-FPM بما يناسب بيئتك.
.htaccess (الإنتاج) وrouter.php (خادم التطوير المحلي php -S) وnginx.conf.example (nginx) يعيد تطبيق قواعد التوجيه نفسها بشكل مستقل. وإضافة مسار جديد برابط نظيف تعني تحديث الثلاثة جميعًا.
بنية الطلبات
كل صفحة في واجهة المتجر (index.php وitem.php و…) تُقلِع عبر includes/header.php، بهذا الترتيب:
يبدأ connection.php الجلسة، ويتصل عبر mysqli ببيانات الاعتماد المأخوذة من .env، ويحمّل tbl_settings إلى ثوابت مثل APP_NAME وCURRENCY، ويسجّل دخول المستخدم الحالي مع صف لبصمة الجهاز. ثم تُقلِع plugins_load() كل إضافة مفعّلة وتطلق خطاف plugins_loaded — وهذه هي اللحظة التي تُعرف عندها المجموعة الحقيقية والحالية من الوحدات المفعّلة، ولهذا يعيد header.php بعدها مطابقة مفاتيح الإعدادات القديمة (المتجر، تعدد البائعين، المزادات، اليانصيب) مع حالة التفعيل الفعلية للإضافات.
لا تكرّر لوحة التحكم عملية الإقلاع هذه — إذ يضبط admin/includes/connection.php إعدادات الجلسة والأخطاء الخاصة بلوحة التحكم ثم يُضمّن ملف includes/connection.php الجذري نفسه.
نظام الإضافات
الإضافة هي plugins/<slug>/plugin.php — بيانات وصفية في تعليق الترويسة تُقرأ دون تنفيذ الملف — إضافةً إلى ملف plugin.json اختياري لمعلومات كتالوج أوفى. وتُخزَّن الإضافات المفعّلة كمصفوفة JSON في tbl_settings.active_plugins.
- ملكية الجداول — كل إضافة تعرّف ملف
includes/schema.phpالخاص بها، ويُستدعى عند التفعيل، مستخدمًا المساعدdb_delta()الذي يمكن تشغيله مرارًا بأمان (CREATE TABLE IF NOT EXISTS+ALTER TABLE ADD COLUMNللإضافة فقط). ولا تمسّ أي إضافة جداول إضافة أخرى أبدًا. - السجلات تُحمَّل أولًا —
add_admin_pageوadd_routeوadd_cron_jobوadd_api_routeوregister_moduleكلها معرَّفة قبل تحميل أي إضافة، فلا تتسبب استدعاءات الإضافة في مستواها الأعلى بخطأ قاتل حتى لو انتهى بها الأمر معطّلة. - حذف نظيف — حذف الإضافة يشغّل ملف
uninstall.phpالخاص بها ويزيل مجلدها؛ ولا ينبغي لأي شيء خارجplugins/<slug>/أن يستدعي ملفاتها استدعاءً إلزاميًا، فيواصل باقي الموقع عمله بعد اختفاء الإضافة.
نظام القوالب
يوجد القالب في assets/themes/<slug>/ — ملف manifest.php وtheme.css وfunctions.php لخطافات القالب، ومجلد components/ اختياري. ويُخزَّن القالب المفعّل في tbl_settings.active_theme، مع editorial كقالب بديل إن لم يُضبط أي قالب.
يجري تحديد المكوّن بهذا الترتيب: مجلد components/ الخاص بالقالب المفعّل، ثم مجلد المكوّنات الذي تعلنه إضافة عبر register_module()، ثم مجلد components/ الجذري المشترك. وعمليًا يعني هذا أن النسخة الافتراضية المشتركة توجد مرة واحدة في components/، ويمكن لأي قالب — أو لأي إضافة وحدة مفعّلة — أن يتجاوز مسار مكوّن بعينه بنسخته الخاصة.
قاعدة البيانات
بادئة الجداول tbl_، وmysqli خام، والعبارات المُعدّة في الغالب. وملفات SQL مرتبة حسب الأولوية:
database/core-schema.sql— جداول النواة وحدها، وتُصان يدويًا؛ أما جداول الوحدات والإضافات فمستثناة عمدًا.database/production.sql— مولَّد آليًا (مخطط النواة + روتين التثبيت الخاص بكل إضافة، مُصدَّرًا من قاعدة بيانات مؤقتة). وهذا هو الملف الذي تستورده لتثبيت جديد.database/sandbox.sql— بيانات تجريبية أولية للتطوير المحلي.database/migration.sql— سكربت ترقية موحّد يمكن تشغيله مرارًا بأمان للتثبيتات القائمة.database/migrations/<slug>/up.sql(معdown.sqlحيث يكون التراجع ممكنًا) — ملف لكل ترحيل على حدة.
الوحدات
كل وحدة تُشحن ضمن التنصيب نفسه، وتُفعَّل أو تُعطَّل بشكل مستقل من لوحة التحكم.
المزادات
مزايدة مباشرة مع بوابة بائعين متعددين ومحرك عمولات. الإضافة الأساسية: plugins/auction.
اليانصيب
سحوبات بتذاكر مع مواعيد وجوائز وإشعارات فائزين قابلة للتهيئة. الإضافة الأساسية: plugins/lottery.
صندوق المفاجآت
مجموعات جوائز قابلة للتهيئة مع مؤثرات كشف متحركة — يشتري المستخدمون صندوقًا ويرون فورًا ما ربحوه. الإضافة: plugins/mystery-box.
الألعاب والمكافآت
مجموعة ألعاب أركيد تحت games/ إضافةً إلى إضافات التفاعل والكسب:
المتجر والسوق
طبقة تجارة إلكترونية متعددة البائعين مع أدوات للعروض الترويجية وعرض المنتجات. الإضافات الأساسية: plugins/shop وplugins/multivendor.
المحفظة والعملات والاستثمار
محفظة على مستوى المنصة كلها، مشتركة بين جميع الوحدات.
الإحالات والمكافآت
المصادقة والثقة والامتثال
أدوات مساعدة
لوحة التحكم
توجد لوحة التحكم تحت admin/ ولا تكرّر إقلاع واجهة المتجر — فهي تضبط إعدادات الجلسة والأخطاء الخاصة بها، ثم تُضمّن ملف includes/connection.php الجذري نفسه. وتُسجَّل الصفحات عبر add_admin_page() الذي يتولى إدخال القائمة الجانبية وضبط الصلاحيات وحماية CSRF وواجهة المصادقة؛ أما إجراءات JSON الخاصة بلوحة التحكم فتُسجَّل عبر add_admin_ajax() وتُوجَّه من خلال admin/ajax.php?action=<slug>.
العناصر واللافتات والصفحات والقوائم والمدونة.
إدارة البوابات الآلية واليدوية، ومراجعة المدفوعات اليدوية، وتصدير التحويلات.
مجموعات المستخدمين والأدوار وبيانات البائعين وانتحال هوية المستخدم.
تصدير المعاملات والطلبات والمستخدمين، وسجلات المهام المجدولة، وتتبع الأخطاء، وسجلات نشاط المشرفين.
الحملات البريدية والقوالب والنشرات والإشعارات الفورية وسجل الإشعارات.
تفعيل الإضافات والقوالب وتعطيلها، وإعدادات SEO لكل صفحة، وإعدادات الموقع العامة.
قوالب واجهة المتجر
تُشحن خمسة قوالب تحت assets/themes/، ويمكن التبديل بينها في كل تثبيت من لوحة التحكم. ويحتفظ كل قالب بنسخته الخاصة من المكوّنات المشتركة داخل مجلد components/ التابع له.
مظهر بسيط وعصري ببطاقات بيضاء وظلال ناعمة — خيار آمن ومتعدد الاستخدامات يناسب أي نوع من المتاجر تقريبًا.
مظهر أنيق بطابع المجلات، بألوان ورقية دافئة وطباعة واضحة، لواجهة متجر مصقولة تبعث على الثقة.
القالب الافتراضي البديلقالب داكن جريء وفاخر بلمسات ذهبية — مصمم ليمنح إحساسًا بالإثارة والرقي.
مظهر دافئ غني بالزخارف مستوحى من الأسواق التقليدية، مع دعم للغات التي تُكتب من اليمين إلى اليسار.
مظهر موسمي احتفالي مخيف — خلفيات أرجوانية داكنة مع لمسات برتقالية متوهجة بلون اليقطين.
بوابات الدفع
البوابات الآلية الـ38 مملوكة للإضافات — كل واحدة تعيش في مجلدها plugins/gateway-<slug>/ وتسجّل نفسها لدى النواة عبر add_payment_gateway(). ويكفي تفعيل البوابة لتعمل؛ فلا شيء في موزّع الدفع (payment_processor.php) مربوط ببوابة بعينها.
أما الوسائل اليدوية الثلاث فهي صفوف مضمّنة في النواة بقيمة gateway_type = 'manual' دون أي كود تهيئة أو تحقق يُضبط — فهي تعرض تعليمات الدفع أو رمز QR ليس إلا. وتتيح إضافة manual-gateway-builder للمشرف إضافة وسائل دفع يدوية مخصصة أخرى دون المساس بالكود.
بعض البوابات (Stripe وRazorpay وMidtrans وVenmo) تسجّل أيضًا خطاف render لمسارات دفع تحتاج إلى جافاسكربت في المتصفح — كتهيئة Stripe Checkout، أو حزمة تطوير Razorpay/Midtrans/Braintree التي تحتاج إلى معرّف طلب أو رمز يُنشأ على الخادم أولًا. أما كل بوابة أخرى فتعمل دون أي ربط إضافي في النواة على الإطلاق.
طبقتا API وAJAX
api/v1/— واجهة REST API بمصادقة JWT لتطبيق الجوال والمستهلكين الخارجيين. ويتحققapi/v1/middleware/*.phpمن ترويسةAuthorization: Bearer <token>. وتضيف الإضافات نقاط النهاية الخاصة بها عبرadd_api_route().ajax/— طبقة AJAX داخلية بمصادقة عبر كوكي الجلسة، تخدم جافاسكربت واجهة المتجر نفسها (السلة والكوبونات والإشعارات). لا طبقة رموز فيها — فهي تعتمد على جلسة PHP التي ينشئهاconnection.php.- مجلد
api/العلوي المتفرق — نقاط نهاية متنوعة بلا إصدار، مثلgeo_location.phpوexchange-rate.phpوofferwall_postback.php.
تطبيق الجوال
mobile/ مشروع Capacitor + Ionic منفصل — غلاف WebView حول الموقع المباشر، لا تطبيق SPA مستقلًا ولا مجرد مستهلك لـ api/v1. ويوجّه ملف capacitor.config.ts الخاص به قيمة server.url إلى نطاقك. وله ملف package.json خاص به ولا يُبنى من جذر المشروع:
cd mobile
npm run sync
npm run open:ios
npm run open:androidالتحديث والترحيلات
خذ نسخة احتياطية قبل تشغيل database/migration.sql أو أي database/migrations/<slug>/up.sql على قاعدة بيانات مباشرة:
mysqldump --single-transaction -u<user> -p<pass> <db> > pre-deploy-$(date +%Y%m%d-%H%M%S).sqlتُشحن معظم الترحيلات بملف down.sql مقابل يتراجع عن ذلك التغيير وحده. أما القليل منها الذي يحوّل بيانات قائمة بدل أن يضيف بنية فحسب فيُشحن بملف down.sql يوثّق سبب كونه بلا أثر بدلًا من ذلك — ولإرجاع تلك الحالات استعِد من النسخة المأخوذة قبل النشر.
ملاحظات الأمان
- غيّر بيانات اعتماد المشرف المضمّنة فور الاستيراد (انظر التثبيت).
- الملفات
.envوconnection.phpوملفات السجل محجوبة عن الوصول المباشر عبر HTTP بواسطة قواعد.htaccess/ nginx المشحونة معها — فلا تحذف تلك القواعد. - يُقدَّم المحتوى المرفوع بطريقة تمنع تنفيذه ككود PHP، وهذا مفروض على مستوى إعداد خادم الويب لا على مستوى التطبيق.
- تُضبط بيانات اعتماد بوابات الدفع لكل بوابة على حدة من لوحة التحكم وتُخزَّن على الخادم — ولا تُكشف أبدًا لواجهة المتجر.
الاختبارات
لا توجد مجموعة اختبارات PHPUnit. فالأمر composer test يشغّل bin/run-probes.php الذي يجمع كل ملف probe_*.php تحت includes/_probes/ وتحت مجلد _probes/ الخاص بكل إضافة، ثم يشغّل كلًا منها كعملية فرعية في سطر الأوامر ويتحقق من رمز الخروج.
composer test # run every probe
php plugins/<slug>/_probes/probe_*.php # run a single probe directly
php bin/run-probes.php --all # also run destructive probes (skipped by default)الأسئلة الشائعة
الدعم والموارد
ما زلت متعثرًا، أو تحتاج شيئًا لا تغطيه هذه الصفحة؟