دليل الترقية

قبل الإصدار 1.0.0 قد يتضمن أي إصدار فرعي (minor) تغييرات جذرية. كل تغيير منها مذكور هنا مع خطوات الانتقال. والسياسة موضحة في استقرار واجهة البرمجة. وتبدأ هذه الصفحة بأحدث إصدار. ويغطي القسم الأخير النسخ التجريبية الأولى، أي ما قبل 0.1.0.

من 0.1.x إلى 0.2.0

لا تحتاج معظم التطبيقات إلى أي تغيير. راجع البنود التالية؛ فالبنود 8 و9 و10 تغيّر ما تُرجعه المكتبة لبعض المُدخلات.

1. لم يعد ext-mbstring مطلوبًا. كان composer.json يشترط الامتداد؛ والآن يكفي PHP. لا يلزم فعل شيء. وإذا أضفت ext-mbstring إلى composer.json الخاص بك من أجل هذه الحزمة وحدها فيمكنك حذفه.
2. تنسيق الأعداد العشرية. تطبع Format::withSeparator() و format_number() الآن العدد العشري (float) بأقصر نص عشري يعيد القراءة إلى العدد نفسه وبحد أقصى 15 رقمًا معنوياً، فيختفي ضجيج التمثيل الثنائي. النصوص لم تتغير وتبقى دقيقة: مرّر نصًا عندما تحتاج أرقامًا أكثر.

إذا كنت تنسّق ناتج حساب عشري فقرّبه أولًا (round($x, 2)) أو مرّر نصًا.

1. صارت NumberToWords::fromWords() صارمة. كانت تجمع الكلمات بأي ترتيب.

ضع و بين الأجزاء والتزم الترتيب: المئات ثم العشرات ثم الآحاد. وكل ما تُرجعه convert() ما زال يُقرأ.

1. Slugify::make() ترمي RtlyKitException ( invalid_argument ، argument = text ) إذا لم يكن النص UTF-8 صالحًا. كان الفاصل وحده يُفحص من قبل. التقط RtlyKitThrowable أو نظّف المُدخل أولًا.
2. Hijri::format() وHebrew::format() ترفضان نمطًا أطول من 256 بايتًا برمي InvalidDateException ( input_too_long ، argument = format ، limit = 256). وكانت Jalali::format() تفعل ذلك أصلًا. والحد في Hijri::MAX_FORMAT_LENGTH و Hebrew::MAX_FORMAT_LENGTH .
3. الشرطة المائلة العكسية في آخر نمط التنسيق تُحذف في التقاويم الثلاثة: format('Y\') تُرجع السنة فقط.
4. IranHolidays::all() وallTitles() وallFixed() تعمل لكل سنة جلالية من -620 إلى 9377. كانت السنوات قبل بداية التقويم الهجري وآخر يوم من 9377 تُثير invalid_date . وحيث لا يمكن اشتقاق العطل الإسلامية تُرجع الدوال العطل الثابتة فقط. أما السنة خارج هذا النطاق فتُثير InvalidDateException ( date_out_of_range ، والسياق year و min و max ).
5. رسائل الخطأ التي تكرر مُدخلك تقتطعه إلى 40 حرفًا وتبقى UTF-8 صالحة دائمًا. وإذا كنت تطابق نص الرسالة فطابق getErrorCode() بدلًا منه.
6. التواريخ الرسمية للعطل في 1380 إلى 1405. في هذه السنوات الجلالية صارت الدوال الساكنة ( IranHolidays و is_iran_holiday() ) تُرجع التواريخ المنشورة بدل تقدير أم القرى. والسنوات الأخرى لم تتغير.

في السنوات الرسمية لا تظهر إلا العناوين الواردة في الجدول الرسمي. والسنوات 1380 إلى 1393 و1395 منقولة: تواريخها من مصدر واحد، وقد تكون قائمة الأيام ناقصة. وللحصول على السلوك القديم في كل السنوات استعمل HolidayCalendar::default()->withOfficialData(false). ولمعرفة مصدر سنة استعمل IranHolidays::sourceOf($year). المزيد في تقويم العطل القابل للتعديل.

1. أوقات الصلاة في خطوط العرض العالية. صار لـ PrayerTimes قاعدة جديدة HighLatitudeRule والافتراضي AngleBased . تعمل حيث يكون وقت الفجر أو العشاء مفقودًا، أو أبعد عن الشروق أو الغروب مما تسمح به القاعدة. جنوب نحو 44 درجة شمالًا لا يتغير شيء. وشمال نحو 44 إلى 46 درجة، قرب انقلاب يونيو، تختلف بعض القيم. والوقت الذي كان null صار له قيمة.

للحصول على الناتج القديم استدعِ $prayer->withHighLatitudeRule(HighLatitudeRule::None). وصارت nextPrayer() تجد أيضًا الصلاة التي تقع بعد منتصف الليل. انظر خطوط العرض العالية.

1. التحقق من أرقام الجوال. فحص الشكل هو نفسه، فلا يتغير صلاح أي مُدخل. وهناك أمران جديدان: لكل نتيجة مفتاح تفاصيل allocated وتُرجعه Mobile::isAllocated() قيمةً bool ؛ وجدول المشغّلين يتبع خطة الترقيم أدق: ضُيّق مفتاح شاتل موبايل 998 إلى 09981 و 09982 ، وتوسّع مفتاح آپتل من 99910 إلى 9991 ، وأُضيفت 0923 و 0931 و 0932 و 0934 .

إذا كنت تقارن مصفوفة details() كلها، فتوقع المفتاح الإضافي allocated.

1. الأعداد العربية بالحروف. تعطي convert($n, 'ar') بلا خيارات النص نفسه كما قبل لكل عدد دون 10 9 . وتقبل الآن أعدادًا حتى 10 27 ، بعد أن كانت تُثير number_too_large . الخيارات الجديدة والأعداد الترتيبية في صفحة الأعداد بالحروف العربية .
2. المنصات. يُدعم PHP من 8.2 إلى 8.5 وLaravel 11 و12 و13 وCarbon 3. انظر استقرار واجهة البرمجة .

من النسخ التجريبية الأولى (قبل 0.1.0): الدوال المساعدة ضمن فضاء الأسماء

1. لم تعد الدوال المساعدة العامة معرَّفة افتراضيًا

تغيير جذري. كانت النسخ التجريبية السابقة تعرّف jdate() وto_persian() وis_national_code() وسائر الدوال المساعدة كدوال عامة بمجرد أن يحمّل Composer الحزمة. وكان هذا قد يتعارض مع شيفرتك أو مع حزمة أخرى، فأُزيل. الدوال المساعدة الآن في فضاء الأسماء RtlyKit ولا يُعرَّف شيء على المستوى العام.

الدوال المساعدة السبع والعشرون: jdate، hdate، hebrew_date، to_persian_digits، to_english_digits، to_persian، to_english، is_national_code، is_sheba، is_bank_card، is_mobile، is_postal_code، is_vehicle_plate، validate_national_code، validate_sheba، validate_bank_card، validate_mobile، validate_postal_code، validate_vehicle_plate، number_to_words، normalize_text، contains_rtl، text_direction، is_iran_holiday، prayer_times، format_number، وordinal.

الخيار أ: استورِد ما تستخدمه (موصى به).

use function RtlyKit\jdate;
use function RtlyKit\is_national_code;

echo jdate('2026-03-21')->format('Y/m/d');   // 1405/01/01

أو استدعِ الاسم المؤهَّل بالكامل: \RtlyKit\jdate('2026-03-21').

الخيار ب: استعد الأسماء العامة القصيرة القديمة. استدعِ Globals::register() مرة واحدة، مثلًا في ملف التهيئة (bootstrap):

\RtlyKit\Globals::register();

echo jdate('2026-03-21')->format('Y/m/d');   // 1405/01/01، يعمل كما كان

لا تعرّف register() إلا الأسماء الحرة بعد. ولا تستبدل أي دالة موجودة، ولا تُطلق استثناءً. وتُرجع قائمة الأسماء التي تخطّتها لأن شيئًا آخر يستخدمها، ويمكن استدعاؤها أكثر من مرة بأمان:

$skipped = \RtlyKit\Globals::register();
if ($skipped !== []) {
    error_log('RTLY-Kit globals skipped: '.implode(', ', $skipped));   // استخدم \RtlyKit\name() لهذه الأسماء
}

ولا يسجّل مزوّد خدمة Laravel (Service Provider) الأسماء العامة أيضًا. في Blade اكتب {{ \RtlyKit\jdate($post->created_at)->format('j F Y') }}، أو استدعِ Globals::register() من AppServiceProvider::register(). المزيد في الدوال المساعدة والأسماء العامة.

2. تغييرات أخرى يجدر الانتباه إليها

فحص للسلوك الجديد لطريقة مكة (2026-03-01 في رمضان، و2026-03-21 ليس كذلك):

use RtlyKit\Prayer\PrayerTimes;

$mecca = PrayerTimes::forCity('mecca', PrayerTimes::METHOD_MAKKAH);
foreach (['2026-03-01', '2026-03-21'] as $d) {
    $t = $mecca->getTimes(new DateTimeImmutable($d));
    echo $d, ' maghrib ', $t['maghrib'], ' isha ', $t['isha'], "\n";
}
// 2026-03-01 maghrib 18:25 isha 20:25
// 2026-03-21 maghrib 18:32 isha 20:02

أبرز ما في سجل التغييرات للسلسلة 0.x

هذه هي النقاط التي تهم المستخدم من سجل التغييرات، مجمّعة؛ والقائمة الكاملة في CHANGELOG.md بالمستودع.

سلوك تغيّر

• مدخلات التقويم خارج النطاق تُطلق استثناءً. السنوات والطوابع الزمنية (timestamps) وقيم add*() / sub*() الضخمة خارج النطاقات المدعومة تُطلق InvalidDateException بدل TypeError أو تاريخ ملتفّ. النطاقات: الجلالي من -620 إلى 9377، والهجري من 1 إلى 9665، والعبري من 3762 إلى 13759 ( الحدود ).
• قواعد السلاسل في make() أصبحت محددة. السنة الأقل من 1700 (العبري: 3000 فأكثر) تُقرأ بتقويم الصنف نفسه، وكل ما عداها يُقرأ ميلادياً؛ والسلاسل الفارغة تُطلق استثناءً؛ و null تعني الآن. لذلك تُقرأ سلسلة ISO ميلادية سنتها أقل من 1700 على أنها جلالية أو هجرية: مرّر DateTimeImmutable لمثل هذه التواريخ ( الأسئلة الشائعة ).
• العطلات. تواريخ رسمية للسنوات الجلالية 1380 إلى 1405 (انظر أعلاه). وفي السنوات الأخرى لا تُبلَّغ العطل الإسلامية إلا للسنوات 1300 إلى 1500 هـ، والسنة خارج النطاق الجلالي تُثير InvalidDateException .
• مدخلات الأعداد. تقبل NumberToWords::convert() و Format::ordinal() الأعداد العشرية الصحيحة ( 3.0 ) وتُطلقان InvalidNumberException للأعداد العشرية الكسرية و NaN و INF .
• حدود المدخلات (تشديد أمني): السلاسل الأطول من 4096 بايت ترفضها NumberToWords و Format ، وترفض Format::withSeparator() الأعداد الأطول من 1000 نويسة. وتُطلق InvalidNumberException ( input_too_long ).
• قُلّصت جداول البيانات إلى المدخلات المؤكَّدة. تغطي NationalCode::getLocation() 547 بادئة وتُرجع null لما عداها؛ وتحتفظ جداول BIN المصرفية (39) ورموز شبا (38) والمشغّلين بالمدخلات التي أكدها مصدران فقط. وقد يصبح اسم كان يُرجَع سابقًا null الآن. وترفض BankCard الأرقام المكوّنة من رقم واحد مكرر.
• أُعيدت كتابة نواة أوقات الصلاة وفق المعادلات الفلكية القياسية؛ وكان الفرق عن التنفيذ السابق في أحداث المساء دقيقتين على الأكثر (متوسطه نصف دقيقة أو أقل) عبر شبكة المقارنة. ويُطبَّق التوقيت الصيفي (DST) لكل حدث على حدة، ووسيط المُنشئ $elevation جديد.
• العطل الإسلامية في السنوات التقديرية تُشتق من التقويم الهجري وقد تختلف عن الإعلان الرسمي بيوم إلى يومين.

ما أُضيف

• تقويم عبري بـ PHP خالصة ( Hebrew ) دون حاجة إلى ext-calendar ؛ وإعادة كتابة التقويم الهجري حول جدول أم القرى للسنوات 1300 إلى 1500 هـ، مع بديل احتياطي HijriVariant::Tabular .
• تحقق منظّم: Result ( isValid() و errors() و details() ) ودوال validate_*() المساعدة برموز أخطاء ثابتة.
• NumberToWords::fromWords() ، وأعداد حتى 21 رقماً، والأعداد السالبة، والأعداد العربية بالحروف ( number_to_words($n, 'ar') ).
• Normalizer::fixHalfSpace() / clean() ، و Detector::isRtlLocale() / isHebrew() ، و IranHolidays::getTitles() / isBusinessDay() / nextBusinessDay() ، و PrayerTimes::nextPrayer() .
• Laravel: الواجهة (Facade) Jalali والمصنع الذي تحلّه الحاوية، والاكتشاف التلقائي، وقواعد التحقق الست برسائل fa / en / ar، و JalaliCast .
• ماكروات Carbon: toJalali و jformat و createFromJalali و toHijri و toHebrew و createFromHijri و createFromHebrew .
• تسلسل الاستثناءات تحت RtlyKitThrowable ، وتعداد ErrorCode ، و Globals::register() ، وعقدا CalendarDate و Validator .

ما أُصلح

• العشاء بطريقة مكة في رمضان (موصوف أعلاه).
• Format::ordinal() للعددين 30 و23؛ و Format::withSeparator() تقبل الأرقام الفارسية والعربية دون تقريب؛ و Mobile تطبّع الصيغ 0098 و 98 و 9xxxxxxxxx المجردة؛ و Sheba تقبل الصيغة المجردة من 24 رقمًا.
• معالجة المنطقة الزمنية لأوقات الصلاة حول التوقيت الصيفي، ومعالجة الخطأ عند طريقة أو معامل عصر غير معروف.
• التصريح المكرر للدالة المساعدة hdate() .

ملاحظة. ثبّت نطاقًا فرعيًا (مثل ~0.1.0) ما دامت المكتبة دون 1.0.0، واقرأ هذه الصفحة قبل كل ترقية فرعية، وشغّل اختباراتك الخاصة على مخرجات التواريخ وأوقات الصلاة التي تخزّنها.