مفاهیم اصلی

CivilDateTime و JDN

CivilDateTime یک مقدار تغییرناپذیر با سه پراپرتی عمومی و readonly است: عدد صحیح jdn برای شماره روز ژولیوسی، عدد صحیح secondsOfDay از 0 تا 86399 و رشته tzLabel که می‌تواند null باشد. JDN در اینجا شناسه یک روز تقویمی است، نه timestamp نجومی با بخش اعشاری. دقت زمان تا ثانیه است؛ ثانیه کبیسه و میکروثانیه ذخیره نمی‌شوند.

متدهای ساخت تاریخ، محدوده سال‌های تقویم را بررسی می‌کنند. سازنده سطح پایین new CivilDateTime($jdn, $secondsOfDay, $tzLabel) فقط ثانیه روز را بررسی می‌کند؛ نه قابل استفاده بودن JDN در همه تقویم‌ها را و نه نام منطقه زمانی را. نزدیک مرزهای تقویم، پیش از نمایش نتیجه از isInSupportedRange() روی view استفاده کنید.

View تقویم

متدهای gregorian()، jalali()، hijri() و hijriCivil() مشخص می‌کنند روز ذخیره‌شده با کدام تقویم خوانده شود. ساعت و برچسب منطقه زمانی حفظ می‌شوند. هر view جدید به‌صورت پیش‌فرض زبان انگلیسی و ارقام لاتین دارد. ساخت view به‌تنهایی تضمین نمی‌کند که اجزای تاریخ قابل خواندن باشند؛ مثلا تبدیل ام‌القری ممکن است هنگام فراخوانی year() یا format() خطا بدهد.

dateTime() مقدار اصلی و calendar() الگوریتم تقویم را برمی‌گرداند. toArray() روی view آرایه‌ای از اجزای تاریخ و ساعت با کلیدهای نام‌دار می‌دهد که با نمایش JSON مقدار اصلی فرق دارد.

تغییرناپذیری و نوع خروجی

withLocale() و withDigits() یک view جدید از همان نوع برمی‌گردانند. محاسبات تاریخ، with() و متدهای ابتدا و انتهای بازه روی view، خروجی CivilDateTime دارند. برای ادامه محاسبه یا نمایش، دوباره view مورد نظر را انتخاب کنید و در صورت نیاز زبان و ارقام را تنظیم کنید. اشیای قبلی تغییر نمی‌کنند.

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

use Eram\Daynum\CivilDateTime;

$d = CivilDateTime::fromJalali(1405, 1, 19, 14, 30);
$view = $d->jalali()->withLocale('fa')->withDigits('persian');
$next = $view->addMonths(1);
echo get_class($next), "\n";
echo $view->format('Y/m/d'), "\n";
echo $next->jalali()->format('Y/m/d H:i'), "\n";
echo $next->jalali()->withLocale('fa')->withDigits('persian')->format('Y/m/d'), "\n";

Eram\Daynum\CivilDateTime
۱۴۰۵/۰۱/۱۹
1405/02/19 14:30
۱۴۰۵/۰۲/۱۹

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

امکانات فعلی و محدودیت‌ها

نسخه آزمایشی فعلی چهار تقویم مستندشده و هفت locale داخلی دارد. ذخیره زمان با دقت کمتر از ثانیه، خواندن عبارت نسبی تاریخ، تقویم تعطیلات و اتصال آماده ORM ارائه نمی‌کند. محدودیت‌ها و پوشش تست را ببینید؛ تقویم‌های احتمالی آینده، وعده API فعلی نیستند.