استقرار واجهة API

واجهة API العامة

كل ما في هذا الجدول مشمول بوعد التوافق.

المجال	الرموز العامة
التقاويم	RtlyKit\Calendar\Jalali وHijri وHebrew وHijriVariant؛ والثابتان MIN_YEAR / MAX_YEAR؛ وRtlyKit\Contracts\CalendarDate
التحقق من الصحة	RtlyKit\Contracts\Validator؛ وRtlyKit\Validation\NationalCode وSheba وBankCard وMobile وPostalCode وVehiclePlate وResult، وسلاسل رموز الأخطاء التي تُرجعها
الأرقام والنصوص	RtlyKit\Number\Digits وFormat وNumberToWords وArabicOptions؛ وRtlyKit\Text\Normalizer وDetector وSlugify
العطل وأوقات الصلاة	RtlyKit\Holiday\IranHolidays وHolidayCalendar وHolidaySource وHolidayOrigin وHolidayEntry؛ وRtlyKit\Prayer\PrayerTimes (ثوابتها METHOD_* / ASR_* ودوالها العامة) وHighLatitudeRule
الأخطاء	RtlyKit\Exceptions\RtlyKitThrowable وRtlyKitException وInvalidDateException وInvalidNumberException وInvalidPrayerConfigException وUnsupportedLocaleException، وErrorCode (أسماء الحالات وقيمها)
الدوال المساعدة	الدوال الـ 27 ذات النطاق في RtlyKit\ (RtlyKit\jdate() وغيرها) وRtlyKit\Globals::register() / Globals::NAMES
Laravel	RtlyKit\Laravel\RtlyKitServiceProvider وFacades\Jalali وJalaliFactory وCasts\JalaliCast، وأسماء قواعد التحقق (national_code وsheba وbank_card وiran_mobile وmobile وpostal_code وvehicle_plate) ومفاتيح الترجمة ضمن النطاق rtly-kit، وملف الإعدادات rtly-kit.php (وسم النشر rtly-kit-config)
Carbon	أسماء الماكروات toJalali وjformat وtoHijri وtoHebrew وcreateFromJalali وcreateFromHijri وcreateFromHebrew

السلوك الموثَّق لهذه الرموز جزء من العقد: المدخلات المقبولة، وفئة الاستثناء وErrorCode المُلقيان، وأنواع القيم المُرجعة، ونطاقات السنوات، وحدود المدخلات. أما صياغة رسائل الاستثناءات والتحقق فليست جزءًا منه؛ فاعتمد بدلًا من ذلك على getErrorCode() أو Result::errors() (راجع معالجة الأخطاء).

داخلي (بلا وعد)

تحمل هذه العناصر وسم @internal في التوثيق، أو هي من تفاصيل التنفيذ. قد تتغير أو تختفي في أي إصدار، بما في ذلك إصدار الإصلاحات (patch). لا تستدعها ولا ترثها ولا تعتمد عليها.

• RtlyKit\Calendar\CalendarLimits
• RtlyKit\Calendar\Jdn
• RtlyKit\Calendar\CalendarDateTrait
• RtlyKit\Calendar\UmmAlQuraTable
• RtlyKit\Validation\Input
• RtlyKit\Validation\DataTables
• RtlyKit\Text\Utf8
• RtlyKit\Holiday\HolidayData و HolidayTitles
• RtlyKit\Number\Arabic\ArabicCardinal و ArabicOrdinal و ArabicToken (استخدم NumberToWords )
• RtlyKit\Support\CarbonMacros و RtlyKit\Support\AutoLoader (بنية التسجيل التحتية؛ استخدم الماكروات لا هاتين الفئتين)
• الملفات في resources/data/ (اقرأ البيانات عبر الفئات العامة فقط)
• src/functions-global.php (توصَّل إليه عبر Globals::register() )
• الأعضاء الخاصة (private) والمحمية (protected) في كل فئة، ومنشئات الفئات final ما لم تكن موثَّقة

من المفيد أن تعرف. قراءة resources/data/*.php مباشرة، أو استدعاء فئة من القائمة أعلاه، غير مدعومة. كانت الإصدارات التجريبية السابقة تحتفظ بجداول المراجع في فئات مستقلة؛ ولم تكن تلك الفئات جزءًا من واجهة API، وأصبحت البيانات الآن في resources/data/ (راجع الترقية).

وغير مشمول كذلك: المحتوى الدقيق لجداول المراجع المضمَّنة (أرقام BIN للبطاقات المصرفية، ورموز مصارف شبا، وبادئات المشغّلين، وبادئات الرقم الوطني، وأشهر أم القرى، وتواريخ العطل الرسمية). تُصحَّح هذه الجداول عند ظهور مصادر أفضل، والتصحيح ليس تغييرًا غير متوافق مع السابق. راجع الدقة والبيانات.

سياسة الإصدارات

يتبع RTLY-Kit الترقيم الدلالي للإصدارات (Semantic Versioning) (opens in a new tab).

• ابتداءً من 1.0.0: لا تُجرى تغييرات غير متوافقة على واجهة API العامة إلا في إصدار رئيسي (major). وتضيف الإصدارات الفرعية (minor) ميزات وقد تضيف حالات إلى التعدادات (enum) ودوال ورموز أخطاء. أما إصدارات الإصلاحات (patch) فتصلح الأخطاء فقط.
• قبل 1.0.0 (الآن): قد يتضمن الإصدار الفرعي ( 0.x ) تغييرات غير متوافقة مع السابق. وكل تغيير منها مدرج تحت «Changed» في سجل التغييرات، مع خطوات الانتقال في صفحة الترقية . ولا تكسر إصدارات الإصلاحات ( 0.x.y ) واجهة API العامة. ثبّت نطاقًا فرعيًا في composer.json (مثل ~0.1.0 ) واقرأ ملاحظات الترقية قبل الانتقال إلى النطاق التالي.
• إصلاح الخطأ الذي يجعل الدالة تُرجع الإجابة الصحيحة يُعدّ إصلاحًا لا تغييرًا غير متوافق مع السابق، حتى لو تغيّر الناتج. مثال: تأخّر وقت العشاء بطريقة مكة المكرمة في رمضان 30 دقيقة عند تصحيحه.
• إضافة حالة إلى ErrorCode ، أو مفتاح إلى مصفوفة Result::details() ، ليست تغييرًا غير متوافق مع السابق. اكتب match على ErrorCode مع فرع default .
• الواجهات ( CalendarDate و Validator و RtlyKitThrowable ) مخصصة للاستهلاك. قد تضيف المكتبة إليها دوال في إصدار فرعي قبل 1.0.0 وفي إصدار رئيسي بعده، فلا تطبّقها بنفسك.
• يُعلَن عن الإيقاف (deprecation) في سجل التغييرات وفي وسوم @deprecated ، ويُحتفظ بالعنصر الموقوف إصدارًا فرعيًا واحدًا على الأقل بعد 1.0.0.

المنصات المدعومة

Item	المدعوم
PHP	8.2 و8.3 و8.4 و8.5 (يشغّل CI الأربعة)؛ ولا يلزم أي امتداد PHP
Laravel (illuminate/*)	11 و12 و13 (يتطلب Laravel 13 PHP 8.3 أو أحدث)
Carbon	3 (nesbot/carbon ^3.0)

الاعتماد الإلزامي الوحيد هو PHP نفسه. أما Carbon وLaravel فتكاملان اختياريان. يُعلَن عن إسقاط دعم إصدار من PHP أو Laravel أو Carbon في سجل التغييرات، ويحدث في إصدار فرعي قبل 1.0.0 وفي إصدار رئيسي بعده.