=== Quran Player for WordPress ===
Contributors: quran-player
Tags: quran, audio, recitation, gutenberg, shortcode
Requires at least: 6.2
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPL-2.0-or-later

مشغل قرآن كريم لووردبريس يستدعي أسماء القرّاء والسور وروابط تلاوة السورة من Quran.Foundation Content API، ويستخدم مشغل MediaElement المدمج في ووردبريس.

== الميزات ==

* واجهة عربية متوافقة مع اتجاه RTL.
* إضافة المشغل باستخدام [quran_player] أو كتلة Gutenberg باسم «مشغل القرآن الكريم».
* جلب القرّاء والسور من Quran.Foundation API.
* البحث عن اسم القارئ أو السورة.
* تذكر اختيار القارئ والسورة في المتصفح نفسه.
* محاولة الانتقال والتشغيل التلقائي للسورة التالية.
* تخزين مؤقت للرمز والبيانات لتقليل طلبات API.
* لا تُرسل بيانات Client Secret إلى المتصفح.
* لا تحتاج إلى مكتبات JavaScript خارجية؛ تستخدم واجهة WordPress REST وMediaElement المدمجتين.

== التثبيت والإعداد ==

1. من لوحة تحكم ووردبريس افتح الإضافات ← أضف إضافة جديدة ← رفع إضافة، ثم ارفع ملف ZIP وفعّله.
2. افتح الإعدادات ← مشغل القرآن الكريم.
3. أنشئ تطبيق Backend/Server من Quran.Foundation Developer Console، واطلب صلاحية Content API. احصل على Client ID وClient Secret الخاصين بالبيئة المختارة.
4. ابدأ ببيئة Pre-live للاختبار، ثم استخدم Production بعد اعتماد الصلاحية. بيانات Pre-live تحتوي على الفاتحة والبقرة فقط.
5. أدخل Client ID وClient Secret، واحفظ الإعدادات، ثم اضغط «اختبار الاتصال الآن».
6. أضف [quran_player] إلى صفحة أو مقالة، أو أضف كتلة «مشغل القرآن الكريم» في Gutenberg.

وثائق البدء: https://api-docs.quran.foundation/docs/quickstart/

== تخزين بيانات السر ==

يمكن إدخال بيانات الوصول من لوحة التحكم، وستُحفظ ضمن إعدادات ووردبريس على الخادم. للحماية الأعلى، عرّف الثوابت التالية في wp-config.php قبل سطر «That's all, stop editing!»:

define('QFP_CLIENT_ID', 'ضع-client-id-هنا');
define('QFP_CLIENT_SECRET', 'ضع-client-secret-هنا');
define('QFP_ENV', 'prelive');

استخدم 'production' بدل 'prelive' فقط بعد اعتماد حساب الإنتاج. عندما تكون الثوابت مضبوطة، تكون لها الأولوية على حقول لوحة التحكم. لا تضع بيانات السر في الصفحة أو الشورت كود أو ملفات JavaScript، ولا تشاركها علنًا.

== ملاحظات ==

* يتطلب الاتصال بالخدمة أن يسمح خادم الموقع باتصالات HTTPS الصادرة إلى Quran.Foundation.
* إذا لم ينجح الاختبار، تحقق من صحة بيانات البيئة، ونوع التطبيق Backend/Server، وصلاحية Content API ونطاق content.
* قد يمنع المتصفح التشغيل التلقائي بعد الانتقال للسورة التالية؛ في هذه الحالة استخدم زر التشغيل الموجود في مشغل الصوت.
* يخزّن اختيار القارئ والسورة في Local Storage للمتصفح الحالي فقط، ولا تتم مزامنته بين الأجهزة.
