RTLY-KitUser guide
فارسیEnglishالعربية

API stability

What you can rely on, what is internal, how versions are numbered before and after 1.0, and which PHP, Laravel and Carbon versions are supported.

On this page
  1. Public API
  2. Internal (no promise)
  3. Versioning policy
  4. Supported platforms

Public API#

Everything in this table is covered by the compatibility promise.

AreaPublic symbols
CalendarsRtlyKit\Calendar\Jalali, Hijri, Hebrew, HijriVariant; the MIN_YEAR and MAX_YEAR constants; RtlyKit\Contracts\CalendarDate
ValidationRtlyKit\Contracts\Validator; RtlyKit\Validation\NationalCode, Sheba, BankCard, Mobile, PostalCode, VehiclePlate, Result, and the error-code strings they return
Numbers and textRtlyKit\Number\Digits, Format, NumberToWords, ArabicOptions; RtlyKit\Text\Normalizer, Detector, Slugify
HolidaysRtlyKit\Holiday\IranHolidays, HolidayCalendar, HolidaySource, HolidayOrigin, HolidayEntry
Prayer timesRtlyKit\Prayer\PrayerTimes (its METHOD_* and ASR_* constants and public methods) and HighLatitudeRule
ErrorsRtlyKit\Exceptions\RtlyKitThrowable, RtlyKitException, InvalidDateException, InvalidNumberException, InvalidPrayerConfigException, UnsupportedLocaleException, and ErrorCode (case names and values)
Helpersthe 27 namespaced functions in RtlyKit\ (RtlyKit\jdate() and so on) and RtlyKit\Globals::register() with Globals::NAMES
LaravelRtlyKit\Laravel\RtlyKitServiceProvider, Facades\Jalali, JalaliFactory, Casts\JalaliCast, the validation rule names (national_code, sheba, bank_card, iran_mobile, mobile, postal_code, vehicle_plate), the translation keys under the rtly-kit namespace, and the keys of the rtly-kit config file (publish tag rtly-kit-config)
Carbonthe macro names toJalali, jformat, toHijri, toHebrew, createFromJalali, createFromHijri, createFromHebrew

The documented behaviour of these symbols is part of the contract. That means accepted inputs, the exception class and ErrorCode thrown, return types, the year ranges and the input caps. The wording of exception and validation messages is not part of it. Match on getErrorCode() or Result::errors() instead (see Error handling).

Internal (no promise)#

These carry an @internal docblock or are implementation details. They can change or disappear in any release, including a patch release. Do not call, extend or depend on them.

  • RtlyKit\Calendar\CalendarLimits
  • RtlyKit\Calendar\Jdn
  • RtlyKit\Calendar\CalendarDateTrait
  • RtlyKit\Calendar\UmmAlQuraTable
  • RtlyKit\Holiday\HolidayData and HolidayTitles
  • RtlyKit\Validation\Input
  • RtlyKit\Validation\DataTables
  • RtlyKit\Text\Utf8
  • RtlyKit\Support\CarbonMacros and RtlyKit\Support\AutoLoader (setup code; use the macros, not these classes)
  • the files in resources/data/ (read the data through the public classes only)
  • src/functions-global.php (reach it through Globals::register())
  • private and protected members of every class, and the constructors of final classes unless documented
Good to know. Reading resources/data/*.php directly, or calling a class from the list above, is not supported. Earlier pre-release builds kept the reference tables in classes of their own. Those were never API, and the data now lives in resources/data/ (see Upgrade).

Also outside the promise: the exact contents of the embedded reference tables (bank BINs, Sheba bank codes, operator prefixes, national-code prefixes, Umm al-Qura months, official holiday dates). They are corrected when better sources appear, and a correction is not a breaking change. See Accuracy and data.

Versioning policy#

RTLY-Kit follows Semantic Versioning.

  • From 1.0.0: breaking changes to the public API come only in a major release. Minor releases add features and may add enum cases, methods and error codes. Patch releases fix bugs only.
  • Before 1.0.0 (now): a minor release (0.x) may contain breaking changes. Each one is listed under "Changed" in the changelog, with migration steps on the Upgrade page. Patch releases (0.x.y) do not break the public API. Pin a minor range in composer.json (for example ~0.2.0) and read the upgrade notes before you move to the next one.
  • A bug fix that makes a function return the correct answer is a fix, not a breaking change, even if the output changes. Example: Isha in the Makkah method during Ramadan moved 30 minutes later when it was corrected. Using official holiday dates for the years 1380 to 1405 is a data correction of the same kind.
  • Adding a case to ErrorCode, or a key to a Result::details() array, is not breaking. Write match over ErrorCode with a default arm.
  • The interfaces (CalendarDate, Validator, RtlyKitThrowable) are for using, not implementing. The library may add methods to them in a minor release before 1.0.0 and in a major release afterwards.
  • Deprecations are announced in the changelog and in @deprecated tags. After 1.0.0 they are kept for at least one minor release.

Supported platforms#

Supported
PHP8.2, 8.3, 8.4 and 8.5 (CI runs all four). No PHP extension is required
Laravel (illuminate/*)11, 12 and 13 (Laravel 13 needs PHP 8.3 or newer)
Carbon3 (nesbot/carbon ^3.0)

The only required dependency is PHP itself. Carbon and Laravel are optional. Dropping support for a PHP, Laravel or Carbon version is announced in the changelog. It happens in a minor release before 1.0.0 and in a major release afterwards.