تعطیلات رسمی ایران

این کلاس چه می‌کند

کلاس RtlyKit\Holiday\IranHolidays چهار سؤال دربارهٔ یک تاریخ جلالی را جواب می‌دهد: تعطیل رسمی است یا نه، اسم تعطیلی چیست، آخر هفته است یا نه، و روز کاری بعدی کدام است. همهٔ متدها static هستند و کلاس final است. عنوان‌ها فارسی‌اند و همان‌طور که در تقویم رسمی آمده‌اند.

دو نوع تعطیلی در کار است:

• تعطیلات ثابت شمسی هر سال در یک تاریخ جلالی هستند (نوروز، ۲۲ بهمن و مانند آن) و دقیق‌اند.
• تعطیلات مذهبی (قمری) با رؤیت هلال تعیین می‌شوند و هر سال حدود ۱۱ روز در تقویم شمسی جلو می‌آیند. برای سال‌های جلالی ۱۳۸۰ تا ۱۴۰۵ کتابخانه تاریخ‌های منتشرشده را برمی‌گرداند (رسمی برای ۱۳۹۴ و ۱۳۹۶ تا ۱۴۰۵). در بقیهٔ سال‌ها آن‌ها را از تقویم هجری حساب می‌کند. جزئیات در دقت و محدودیت‌ها است.

متدهای این صفحه همیشه از تنظیمات پیش‌فرض استفاده می‌کنند. اگر می‌خواهید تاریخ رؤیت هلال را خودتان وارد کنید یا تعطیلی اضافه و حذف کنید، تقویم تعطیلات را ببینید.

بررسی یک روز

isHoliday() و getTitle() و getTitles() یا یک شیء 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(1405, 1, 1)));
// Array ( [0] => جشن نوروز [1] => عید فطر )

روز اول فروردین ۱۴۰۵ با اول شوال ۱۴۴۷ یکی است. این تاریخ از جدول رسمی آمده است.

فهرست کل سال

سه متد یک سال کامل را می‌دهند. کلیدها رشتهٔ 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/01/11 عید فطر، 1404/01/12 تعطیل عید فطر، 1404/03/16 عید قربان، 1404/03/24 عید غدیر خم، 1404/04/14 تاسوعای حسینی و 1404/04/15 عاشورای حسینی. وقتی تعطیلی ثابت و مذهبی در یک روز باشند، all() آن‌ها را به هم وصل می‌کند، مثلاً 1404/01/12 روز جمهوری اسلامی / تعطیل عید فطر.

آخر هفته و روز کاری

سه متد کمکی یک شیء Jalali می‌گیرند:

• isWeekend($date) فقط روز جمعه true است.
• isBusinessDay($date) وقتی true است که روز نه آخر هفته باشد و نه تعطیل رسمی.
• nextBusinessDay($date) اولین روز کاری بعد از تاریخ داده‌شده را می‌دهد (خود آن روز حساب نمی‌شود). در آخرین روز بازهٔ پشتیبانی‌شده (جلالی 9377/12/30) روز بعدی وجود ندارد و InvalidDateException پرتاب می‌شود.

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

نکته. فقط جمعه آخر هفته حساب می‌شود. پنجشنبه اینجا روز کاری است. نیم‌روز پنجشنبه، تقویم استان‌ها و تعطیلی‌های موردی (مثل آلودگی هوا یا اعلام دولت) در نظر گرفته نمی‌شوند. اگر سازمان شما پنجشنبه‌ها تعطیل است، بعد از isBusinessDay() خودتان آن را فیلتر کنید.

ورودی نامعتبر

ورودی نادرست یکی از زیرکلاس‌های 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 با کد date_out_of_range (سال بیرون از ‎-620..9377)

دقت و محدودیت‌ها

برای اینکه بفهمید هر سال از کدام دسته است، IranHolidays::sourceOf($year) را بزنید. مقدارش یکی از HolidaySource::Official و Reported و Estimated است.

خوب است بدانید. در سال‌های گزارش‌شده، یعنی ۱۳۸۰ تا ۱۳۹۳ و ۱۳۹۵، فهرست روزها ممکن است کامل نباشد: روز امام رضا یا روز امام حسن عسکری می‌تواند نباشد. تعطیلات ثابت شمسی دقیق‌اند. تاریخ مناسبت‌های مذهبی در ایران با رؤیت هلال تعیین می‌شود، پس برای سال‌هایی که تخمینی‌اند ممکن است ۱ تا ۲ روز با اعلام رسمی فرق داشته باشد. اگر برای حقوق، مهلت قانونی یا تاریخ حقوقی به این تاریخ‌ها تکیه می‌کنید، با اعلام رسمی مقایسه کنید. در تقویم تعطیلات می‌توانید تاریخ رؤیت هلال را خودتان بدهید.

• بازهٔ تخمین. تعطیلات مذهبیِ تخمینی فقط داخل جدول ام‌القری گزارش می‌شوند (سال‌های هجری ۱۳۰۰ تا ۱۵۰۰، یعنی از 1882-11-12 تا 2077-11-16). بیرون از آن، isHoliday() ، getTitles() ، all() و allTitles() فقط تعطیلات ثابت شمسی را می‌دهند، چون حدس جدولی برای تعطیلات قابل اتکا نیست. مثلاً IranHolidays::getTitles(Jalali::create(1500, 1, 1)) فقط ["جشن نوروز"] را می‌دهد.
• بازهٔ سال جلالی. all() و allTitles() و allFixed() سال‌های جلالی ‎-۶۲۰ تا ۹۳۷۷ را قبول می‌کنند. برای سال بیرون از این بازه InvalidDateException با کد date_out_of_range و زمینهٔ year و min و max می‌گیرید. هر سال داخل بازه، از جمله اولین و آخرین سال، جواب می‌دهد. جایی که تعطیلات اسلامی را نشود حساب کرد (قبل از مبدأ هجری یا بیرون از جدول ۱۳۰۰ تا ۱۵۰۰) فقط تعطیلات ثابت می‌آید و خطایی پرتاب نمی‌شود.
• پوشش داده‌نشده. تعطیلی‌های موردی که دولت اعلام می‌کند، و مناسبت‌هایی که تعطیل نیستند.
• منبع داده در دقت و داده آمده است.

ببینید: تقویم تعطیلات، تقویم جلالی و تقویم هجری.