پایداری 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 (نام caseها و مقدارها)
توابع کمکی	۲۷ تابع فضای‌نام‌دار در 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. کلیدهای holidays در فایل تنظیمات rtly-kit.php
Carbon	نام ماکروهای toJalali، jformat، toHijri، toHebrew، createFromJalali، createFromHijri، createFromHebrew

رفتار مستندشدهٔ این‌ها هم جزو تعهد است: ورودی‌های قابل قبول، کلاس خطا و ErrorCode پرتاب‌شده، نوع خروجی، بازهٔ سال‌ها و سقف ورودی‌ها. متن پیام خطاها و پیام‌های اعتبارسنجی جزو تعهد نیست. به‌جای آن روی getErrorCode() یا Result::errors() تصمیم بگیرید (مدیریت خطا).

داخلی (بدون تعهد)

این‌ها در docblock علامت @internal دارند یا جزئیات پیاده‌سازی‌اند. ممکن است در هر نسخه، حتی نسخهٔ patch، عوض یا حذف شوند. آن‌ها را صدا نزنید، از آن‌ها ارث نبرید و به آن‌ها وابسته نشوید.

• RtlyKit\Calendar\CalendarLimits
• RtlyKit\Calendar\Jdn
• RtlyKit\Calendar\CalendarDateTrait
• RtlyKit\Calendar\UmmAlQuraTable
• RtlyKit\Holiday\HolidayData و HolidayTitles
• RtlyKit\Number\Arabic\* ( ArabicCardinal ، ArabicOrdinal ، ArabicToken )
• RtlyKit\Validation\Input
• RtlyKit\Validation\DataTables
• RtlyKit\Text\Utf8
• 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 از نسخه‌گذاری معنایی (SemVer) (opens in a new tab) پیروی می‌کند.

• از ۱٫۰٫۰ به بعد: تغییر ناسازگار در API عمومی فقط در نسخهٔ major می‌آید. نسخهٔ minor قابلیت، case در enum، متد و کد خطای تازه اضافه می‌کند. نسخهٔ patch فقط باگ را درست می‌کند.
• قبل از ۱٫۰٫۰ (الان): نسخهٔ minor ( 0.x ) ممکن است تغییر ناسازگار داشته باشد. هر مورد در بخش «Changed» تغییرنامه، با راه مهاجرت در ارتقا نوشته می‌شود. نسخهٔ patch ( 0.x.y ) API عمومی را نمی‌شکند. در composer.json یک بازهٔ minor ثابت کنید (مثلاً ~0.2.0 ) و پیش از رفتن به نسخهٔ بعد، یادداشت‌های ارتقا را بخوانید.
• درست کردن باگی که تابع را به جواب درست می‌رساند «رفع باگ» است و «تغییر ناسازگار» نیست، حتی اگر خروجی عوض شود. مثلاً وقتی عشای روش مکه در رمضان درست شد، ۳۰ دقیقه دیرتر شد.
• اضافه شدن case به ErrorCode یا کلید به آرایهٔ Result::details() ناسازگار نیست. برای match روی ErrorCode شاخهٔ default بگذارید.
• اینترفیس‌ها ( CalendarDate ، Validator ، RtlyKitThrowable ) برای استفاده‌اند. کتابخانه ممکن است قبل از ۱٫۰٫۰ در نسخهٔ minor و بعد از آن در نسخهٔ major به آن‌ها متد اضافه کند. پس خودتان پیاده‌سازی‌شان نکنید.
• منسوخ‌شدن‌ها در تغییرنامه و با برچسب @deprecated اعلام می‌شوند و بعد از ۱٫۰٫۰ دست‌کم یک نسخهٔ minor می‌مانند.

پلتفرم‌های پشتیبانی‌شده

Item	پشتیبانی‌شده
PHP	۸٫۲، ۸٫۳، ۸٫۴ و ۸٫۵ (CI هر چهار را اجرا می‌کند). افزونهٔ PHP لازم نیست
Laravel (illuminate/*)	نسخه‌های ۱۱، ۱۲ و ۱۳ (Laravel 13 به PHP 8.3 یا بالاتر نیاز دارد)
Carbon	نسخهٔ ۳ (nesbot/carbon ^3.0)

تنها وابستگی اجباری خود PHP است. Carbon و Laravel بخش‌های اختیاری‌اند. کنار گذاشتن یک نسخهٔ PHP یا Laravel یا Carbon در تغییرنامه اعلام می‌شود و قبل از ۱٫۰٫۰ در نسخهٔ minor و بعد از آن در نسخهٔ major انجام می‌شود.