تقويم العطل القابل للتعديل

ما هو

تحدد إيران عطلها الدينية برؤية الهلال، والجدول لا يستطيع إلا تقديرها، وقد يخطئ التقدير بيوم أو يومين. يعالج RtlyKit\Holiday\HolidayCalendar ذلك بطريقتين: فهو يضم التواريخ الرسمية المنشورة لعدد من السنوات الجلالية، ويتيح لك تصحيح ما سواها بإعدادات صغيرة.

الصنف HolidayCalendar لا يتغير بعد إنشائه ولا يحمل حالة عامة؛ كل دالة with*() تُرجع تقويمًا جديدًا. وله دوال البحث نفسها التي في الصنف الساكن IranHolidays (isHoliday() وgetTitles() وall() وisBusinessDay() وغيرها). أما IranHolidays فيستعمل التقويم الافتراضي، وهو HolidayCalendar::default().

من أين تأتي التواريخ

لكل سنة جلالية أحد ثلاثة مصادر. اسأل التقويم بـ sourceOf($year)، وهي تُرجع قيمة من HolidaySource.

العطل الثابتة، مثل النوروز و22 بهمن، تقع في التاريخ الجلالي نفسه كل سنة. هي دقيقة ولا تدخل في هذا السؤال.

<?php
require 'vendor/autoload.php';

use RtlyKit\Holiday\HolidayCalendar;
use RtlyKit\Holiday\IranHolidays;

$cal = HolidayCalendar::default();    // IranHolidays::calendar() هو التقويم نفسه

echo $cal->sourceOf(1405)->value;     // official
echo $cal->sourceOf(1395)->value;     // reported
echo $cal->sourceOf(1406)->value;     // estimated

echo implode(', ', IranHolidays::getTitles(1405, 1, 1));   // جشن نوروز, عید فطر

في سنة 1405 يقع عيد الفطر 1447 هـ في 1405/01/01، أي مع النوروز، وهذا هو التاريخ الرسمي. أما تقدير الجدول فيضعه في 1404/12/29.

شرح عملي: تصحيح سنة خطوة بخطوة

ليست للسنة 1406 بيانات رسمية بعد، فهي تقديرية. سنصححها في أربع خطوات.

1. إزاحة كل التواريخ التقديرية

إذا لاحظت أن التقدير أبكر بيوم طوال السنة، فأزح كل العطل الإسلامية التقديرية بـ withIslamicOffset(). تقبل من -3 إلى +3 أيام، وتؤثر في السنوات التقديرية فقط؛ فالسنوات الرسمية والعطل الثابتة لا تتحرك.

$later = $cal->withIslamicOffset(1);

echo implode(', ', $cal->getTitles(1406, 3, 25));     // عاشورای حسینی
echo implode(', ', $later->getTitles(1406, 3, 26));   // عاشورای حسینی

2. تحديد البداية الفعلية لشهر هجري

الإزاحة الواحدة لا تتبع القمر شهرًا بعد شهر. فإذا عرفت اليوم الأول الفعلي للشهر، فأعطِه لـ withHijriMonthStart($hijriYear, $hijriMonth, $firstDay). والتاريخ ميلادي: نص مثل '2027-06-08' (الأرقام الفارسية والعربية مقبولة) أو أي DateTimeInterface. تُشتق من هذا اليوم كل العطل الإسلامية لذلك الشهر. وهذا يعمل في السنوات الرسمية أيضًا، ويغلب البيانات الرسمية.

// يُحسب أن محرم 1449 يبدأ في 2027-06-06. ورُئي الهلال بعد يومين:
$moved = $cal->withHijriMonthStart(1449, 1, '2027-06-08');

echo implode(', ', $moved->getTitles(1406, 3, 25));   // (لا شيء)
echo implode(', ', $moved->getTitles(1406, 3, 26));   // تاسوعای حسینی
echo implode(', ', $moved->getTitles(1406, 3, 27));   // عاشورای حسینی

يجب أن يكون التاريخ ضمن 3 أيام من البداية المحسوبة. وإذا أعطيت أيضًا بداية شهر مجاور، فيجب أن يفصل بين البدايتين 29 أو 30 يومًا. وإلا أثارت الدالة InvalidDateException.

3. إضافة يوم أو حذفه

تضيف withHoliday($date, $title) عنوانًا إلى يوم. وتحذف withoutHoliday($date) اليوم كله، وتحذف withoutHoliday($date, $title) عنوانًا واحدًا. والتاريخ كائن Jalali أو نص مثل '1406/02/03'.

$mine = $moved
    ->withHoliday('1406/02/03', 'Company day')
    ->withoutHoliday('1406/01/13');            // حذف يوم الطبيعة

var_dump($mine->isHoliday(1406, 2, 3));        // bool(true)
var_dump($mine->isHoliday(1406, 1, 13));       // bool(false)

4. معرفة سبب كون اليوم عطلة

تُرجع statusOf() كل عنوان في اليوم مع أصله. والأصل قيمة من HolidayOrigin: Fixed أو Official أو Reported أو Estimated أو User.

foreach ($mine->statusOf(1406, 2, 3) as $entry) {
    echo $entry->title, ' ', $entry->origin->value, "\n";   // Company day user
}
foreach ($mine->statusOf(1406, 3, 27) as $entry) {
    echo $entry->title, ' ', $entry->origin->value, "\n";   // عاشورای حسینی user
}
foreach ($cal->statusOf(1405, 1, 1) as $entry) {
    echo $entry->title, ' ', $entry->origin->value, "\n";
}
// جشن نوروز fixed
// عید فطر official

يمكنك بهذا أن تعرض ملاحظة صغيرة بجانب التواريخ التي هي تقدير فقط.

كل الخيارات

أي قاعدة تغلب

لكل يوم ولكل عنوان الترتيب نفسه:

1. تعديلاتك: withHoliday() و withoutHoliday() و withHijriMonthStart() .
2. الجدول الرسمي، للسنوات التي يغطيها، ما دامت withOfficialData(true) مفعّلة.
3. تقدير أم القرى، مع إزاحة withIslamicOffset() .

العطل الجلالية الثابتة لا تحركها إزاحة ولا بداية شهر. ويمكنك مع ذلك حذف واحدة منها بـ withoutHoliday().

إعدادات Laravel

انشر ملف الإعدادات:

php artisan vendor:publish --tag=rtly-kit-config

ينشئ هذا الأمر الملف config/rtly-kit.php، وفي قسم holidays منه هذه المفاتيح:

'holidays' => [
    'islamic_offset' => 0,           // من -3 إلى 3، للسنوات التقديرية فقط
    'hijri_month_starts' => [],      // '1447-10' => '2026-03-21'
    'extra' => [],                   // '1405/02/03' => 'Title' أو ['Title 1', 'Title 2']
    'removed' => [],                 // '1405/02/03' أو '1405/02/03' => 'Title'
    'use_official_data' => true,
],

يبني مزوّد الخدمة HolidayCalendar واحدًا من هذا القسم ويربطه في الحاوية. احصل عليه بـ app(HolidayCalendar::class). يُنشأ عند أول طلب، فالقيمة الخاطئة تفشل عندئذ. والمفاتيح الناقصة تأخذ قيمها الافتراضية.

use RtlyKit\Holiday\HolidayCalendar;

$calendar = app(HolidayCalendar::class);
$calendar->isHoliday(1406, 3, 27);

من المفيد أن تعرف. الصنف الساكن IranHolidays والدالة المساعدة is_iran_holiday() يستعملان دائمًا التقويم الافتراضي، لا تقويم إعداداتك. استعمل app(HolidayCalendar::class) حين تريد تطبيق إعداداتك.

ما الذي تغيّر في 0.2.0

في السنوات الجلالية من 1380 إلى 1405 صارت الدوال الساكنة تُرجع التواريخ الرسمية أو المنقولة، بعد أن كانت تُرجع تقدير الجدول. أما السنوات خارج 1380 إلى 1405 والتقاويم المبنية بـ withOfficialData(false) فتُرجع ما كانت تُرجعه الإصدارات السابقة. بعض الأمثلة:

• 1405/01/01 هو عيد الفطر 1447 هـ، ولم يعد 1404/12/29 يومًا له.
• عيد الفطر 1446 هـ في 1404/01/11 وليس في 1404/01/10.
• في السنوات الرسمية لا تظهر إلا العناوين الواردة في الجدول الرسمي. فيوم 8 ربيع الأول (الإمام الحسن العسكري) مثلًا غير موجود في بيانات 1394 و1395.

القائمة المقارنة في الترقية.

من المفيد أن تعرف

من المفيد أن تعرف. لا توجد بيانات رسمية للسنة 1406 بعد. وعند نشرها ستضاف إلى ملف البيانات دون أن يتغير شيء آخر. وفي السنوات التقديرية تعالج الإزاحة الواحدة تأخرًا ثابتًا، ولا تعالج رؤية الهلال شهرًا بشهر؛ فاستعمل withHijriMonthStart() للأشهر الدقيقة. ومصدر البيانات موصوف في الدقة والبيانات.

ذو صلة: العطل الرسمية الإيرانية والتقويم الهجري وإعداد Laravel.