RTLY-Kitراهنمای کاربر
فارسیEnglishالعربية

پایداری API

به چه چیزهایی می‌توانید تکیه کنید، چه چیزهایی داخلی است، نسخه‌گذاری قبل و بعد از ۱٫۰ و نسخه‌های پشتیبانی‌شدهٔ PHP، Laravel و Carbon.

در این صفحه
  1. API عمومی
  2. داخلی (بدون تعهد)
  3. نسخه‌گذاری
  4. پلتفرم‌های پشتیبانی‌شده

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
LaravelRtlyKit\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) پیروی می‌کند.

  • از ۱٫۰٫۰ به بعد: تغییر ناسازگار در 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 می‌مانند.

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

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

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