العطل الرسمية الإيرانية

ماذا تفعل#

تجيب RtlyKit\Holiday\IranHolidays عن أربعة أسئلة بشأن تاريخ جلالي: هل هو عطلة رسمية، وما اسم العطلة، وهل هو يوم عطلة أسبوعية، وما يوم العمل التالي. جميع الدوال ساكنة (static) والفئة final. وتُرجع عناوين العطل بالفارسية كما تظهر في التقويم الرسمي.

تجمع الفئة نوعين من العطل:

• العطل الشمسية الثابتة تقع في التاريخ الجلالي نفسه كل سنة (النوروز، و22 بهمن، وغيرهما). وهي دقيقة.
• العطل الإسلامية (القمرية) تتحرك عبر السنة الجلالية بنحو 11 يومًا كل عام. للسنوات 1380 إلى 1405 تستعمل الفئة التواريخ الرسمية أو المنقولة، وللسنوات الأخرى تحسبها من تقويم أم القرى. التفاصيل في الدقة والحدود.

الدوال الساكنة هنا تعمل على التقويم الافتراضي. وإذا أردت إزاحة أو تصحيحًا أو يومًا خاصًا بك، فاستعمل تقويم العطل القابل للتعديل.

فحص يوم واحد#

يقبل كل بحث إما كائن Jalali أو ثلاثة أعداد صحيحة (السنة والشهر واليوم).

use RtlyKit\Calendar\Jalali;
use RtlyKit\Holiday\IranHolidays;
use function RtlyKit\is_iran_holiday;

var_dump(IranHolidays::isHoliday(1404, 11, 22));              // bool(true)
var_dump(IranHolidays::getTitle(1404, 11, 22));               // string(38) "پیروزی انقلاب اسلامی"
var_dump(IranHolidays::isHoliday(Jalali::create(1404, 1, 5))); // bool(false)
var_dump(is_iran_holiday(1404, 1, 1));                        // bool(true)  (دالة مساعدة ذات نطاق)

تُرجع getTitle() أول عنوان أو null. وعندما تتزامن عطلتان في يوم واحد، استعمل getTitles() التي تُرجع قائمة تأتي فيها العطلة الثابتة أولًا والإسلامية ثانيًا:

print_r(IranHolidays::getTitles(Jalali::create(1404, 1, 2)));
// Array ( [0] => عید نوروز [1] => شهادت امام علی )

في 1404 يوافق ثاني أيام النوروز ذكرى شهادة الإمام علي بحسب التقويم الرسمي، فيظهر العنوانان معًا.

عرض سنة كاملة#

تُرجع ثلاث دوال سنةً كاملة، مفهرسةً بسلاسل Y/m/d بترتيب تصاعدي:

• تُرجع allFixed(int $year) العطل الشمسية الثابتة فقط، بعنوان واحد لكل تاريخ.
• تُرجع all(int $year) العطل الثابتة والإسلامية؛ وتُضم العناوين الواقعة في اليوم نفسه بالفاصل / .
• allTitles(int $year) هي الصيغة المنظّمة: كل قيمة فيها من النوع list<string>.

foreach (IranHolidays::allFixed(1404) as $date => $title) {
    echo $date, '  ', $title, "\n";
}
// 1404/01/01  جشن نوروز
// 1404/01/02  عید نوروز
// 1404/01/03  عید نوروز
// 1404/01/04  عید نوروز
// 1404/01/12  روز جمهوری اسلامی
// 1404/01/13  روز طبیعت
// 1404/03/14  رحلت امام خمینی
// 1404/03/15  قیام ۱۵ خرداد
// 1404/11/22  پیروزی انقلاب اسلامی
// 1404/12/29  ملی شدن صنعت نفت

echo count(IranHolidays::all(1404));    // 26 (عطل ثابتة وإسلامية، مدخل واحد لكل يوم)

ومن الجزء الإسلامي في 1404 مثلًا: 1404/01/11 عید فطر و1404/03/16 عید قربان و1404/03/24 عید غدیر خم و1404/04/14 تاسوعای حسینی و1404/04/15 عاشورای حسینی. وفي بعض الأيام يجتمع عنوانان، مثل 1404/01/12 الذي تطبع فيه all() العنوان روز جمهوری اسلامی / تعطیل عید فطر.

العطلة الأسبوعية وأيام العمل#

تأخذ ثلاث دوال مساعدة كائن Jalali:

• تكون isWeekend($date) مساوية لـ true يوم الجمعة فقط.
• تكون isBusinessDay($date) مساوية لـ true عندما لا يكون اليوم عطلة أسبوعية ولا عطلة رسمية.
• تُرجع nextBusinessDay($date) أول يوم عمل يأتي بعد التاريخ المعطى بشكل صارم.

foreach ([Jalali::create(1404, 11, 20), Jalali::create(1404, 11, 21), Jalali::create(1404, 11, 22)] as $d) {
    echo $d->toDateString(),
        ' weekend=', var_export(IranHolidays::isWeekend($d), true),
        ' business=', var_export(IranHolidays::isBusinessDay($d), true),
        ' next=', IranHolidays::nextBusinessDay($d)->toDateString(), "\n";
}
// 1404/11/20 weekend=false business=true next=1404/11/21
// 1404/11/21 weekend=false business=true next=1404/11/23
// 1404/11/22 weekend=false business=false next=1404/11/23

الإدخال غير الصالح#

يُثير الإدخال الخاطئ استثناءً من فئة فرعية من RtlyKitException، ولا يظهر خطأ PHP خام. راجع معالجة الأخطاء.

IranHolidays::isHoliday(1404, 13, 1);  // InvalidDateException: Invalid Jalali date: 1404/13/1
IranHolidays::isHoliday(1404);         // InvalidDateException: Month and day are required when the year is given as int.
IranHolidays::all(99999);              // InvalidDateException: Jalali year 99999 is outside the supported range -620..9377. [date_out_of_range]

الدقة والحدود#

تحدد إيران عطلها الدينية برؤية الهلال، ولذلك فإن حسابها من جدول أم القرى قد يخالف المعلن بيوم أو يومين. لهذا السبب تضم المكتبة التواريخ المنشورة، وهذه هي حال السنوات:

• 1394 و1396 إلى 1405: تواريخ رسمية، من مصدرين لكل سنة. لا تظهر في هذه السنوات إلا العناوين الواردة في الجدول الرسمي.
• 1380 إلى 1393 و1395: تواريخ منقولة عن مصدر واحد، دون مراجعة مجموعة العطل نفسها.
• ما سوى ذلك: تقدير محسوب من جدول أم القرى.

لمعرفة حال سنة معينة استعمل IranHolidays::sourceOf($year)؛ وهي تُرجع Official أو Reported أو Estimated. تفاصيل الجدول وطريقة التصحيح في تقويم العطل القابل للتعديل.

echo IranHolidays::sourceOf(1405)->name, "\n";   // Official
echo IranHolidays::sourceOf(1385)->name, "\n";   // Reported
echo IranHolidays::sourceOf(1406)->name, "\n";   // Estimated

• النطاق. لا تُعرض العطل الإسلامية التقديرية إلا داخل جدول أم القرى المضمَّن (السنوات الهجرية من 1300 إلى 1500، أي من 1882-11-12 إلى 2077-11-16). وخارجه تُرجع isHoliday() وgetTitles() وall() وallTitles() العطل الشمسية الثابتة فقط، لأن الاستقراء الجدولي لا يصلح للعطل. مثال: IranHolidays::getTitles(Jalali::create(1500, 1, 1)) تُرجع ["جشن نوروز"] فقط.
• نطاق السنة الجلالية. تقبل all() وallTitles() وallFixed() السنوات الجلالية من -620 إلى 9377. وإذا كانت السنة خارج هذا النطاق أثارت InvalidDateException برمز الخطأ date_out_of_range وسياق فيه year وmin وmax. وحيث لا يمكن اشتقاق العطل الإسلامية (قبل بداية التقويم الهجري، أو خارج جدول 1300 إلى 1500 هـ) تُرجع الدوال العطل الجلالية الثابتة فقط دون أي استثناء.
• غير مشمول. العطل الإضافية الاستثنائية التي تعلنها الحكومة، وقائمة المناسبات التي ليست أيام عطلة. وتستطيع إضافتها بنفسك بـ withHoliday().
• مصدر البيانات موصوف في صفحة الدقة والبيانات.

ذو صلة: التقويم الجلالي والتقويم الهجري.