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

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

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

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

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

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

بررسی یک روز#

هر جست‌وجو یا یک شیء 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 عاشورای حسینی. در سال ۱۴۰۴ عید فطر دو بار نمی‌آید: عید فطر ۱۴۴۷ روی اول فروردین ۱۴۰۵ است و در فهرست ۱۴۰۵ می‌آید.

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

سه متد کمکی یک شیء 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 با کد 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 می‌گیرید. هر سال داخل بازه، از جمله اولین و آخرین سال، جواب می‌دهد. جایی که تعطیلات اسلامی را نشود حساب کرد (قبل از مبدأ هجری یا بیرون از جدول ۱۳۰۰ تا ۱۵۰۰) فقط تعطیلات ثابت می‌آید و خطایی پرتاب نمی‌شود.
• پوشش داده‌نشده. تعطیلی‌های موردی که دولت اعلام می‌کند، و مناسبت‌هایی که تعطیل نیستند.
• منبع داده در دقت و داده آمده است.

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