محاسبات تاریخ

خروجی محاسبات CivilDateTime است

برای محاسبه ماه و سال از view تقویم استفاده کنید؛ مثلا $d->jalali()->addMonths(1) یک ماه شمسی اضافه می‌کند. هر متد view که تاریخ را تغییر می‌دهد، CivilDateTime برمی‌گرداند، برچسب منطقه زمانی را حفظ می‌کند و شیء قبلی را تغییر نمی‌دهد. پیش از ادامه محاسبه تقویمی یا format() دوباره view را انتخاب کنید.

محدود شدن روز به انتهای ماه

متدهای addMonths()، subMonths()، addYears() و subYears() اگر روز مورد نظر در ماه مقصد وجود نداشته باشد، آخرین روز آن ماه را انتخاب می‌کنند. بنابراین جمع و تفریق در انتهای ماه همیشه معکوس هم نیستند. انتقال روز کبیسه به سال دیگر هم همین رفتار را دارد.

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

use Eram\Daynum\CivilDateTime;

$d = CivilDateTime::fromGregorian(2026, 1, 31, 14, 30);
$next = $d->gregorian()->addMonths(1);
echo $next->gregorian()->format('Y-m-d H:i'), "\n";
echo $next->gregorian()->subMonths(1)->gregorian()->format('Y-m-d'), "\n";
echo $next->gregorian()->diffInMonths($d), "\n";
echo $d->gregorian()->endOfMonth()->endOfDay()->gregorian()->format('Y-m-d H:i:s'), "\n";

2026-02-28 14:30
2026-01-28
0
2026-01-31 23:59:59

تغییر یک جزء با with

متد with(year:, month:, day:, hour:, minute:, second:) روی view، اجزای حذف‌شده یا null را حفظ و نتیجه را بررسی می‌کند. روز را به انتهای ماه محدود نمی‌کند: تغییر ۳۱ ژانویه با month: 2 خطا می‌دهد، مگر اینکه روز معتبری هم بدهید. روی مقدار اصلی، withTime() هر سه جزء ساعت را عوض می‌کند و withJdn() روز را مستقیم تغییر می‌دهد.

محاسبه ساعت روز

مقدار اصلی متدهای add/subSeconds، add/subMinutes، add/subHours، add/subDays و add/subWeeks را دارد. همه یک مقدار صحیح می‌گیرند و عدد منفی جهت عمل را برعکس می‌کند. این متدها ساعت محلی را جابه‌جا می‌کنند و DST را در نظر نمی‌گیرند. هر روز همیشه 86400 ثانیه محلی و هر هفته هفت روز است. viewها هم addDays() و subDays() دارند که معادل متدهای مقدار اصلی‌اند. برای ساعت واقعی سپری‌شده از timestamp استفاده کنید.

هفته‌ها

startOfWeek() و endOfWeek() از شروع هفته در locale یا یک WeekDay یا عدد ISO از 1 تا 7 استفاده می‌کنند. آرگومان endOfWeek() روز شروع هفته است، نه آخر آن. هر دو ساعت روز را حفظ می‌کنند. weekDay() مقدار enum می‌دهد، dayOfWeek() یکشنبه را صفر و dayOfWeekIso() دوشنبه را یک در نظر می‌گیرد. تشخیص آخر هفته از تنظیمات زبان پیروی می‌کند.

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

use Eram\Daynum\CivilDateTime;
use Eram\Daynum\WeekDay;

$v = CivilDateTime::fromGregorian(2026, 4, 8, 14, 30)->jalali()->withLocale('fa');
echo $v->startOfWeek()->gregorian()->format('Y-m-d H:i'), "\n";
echo $v->startOfWeek(WeekDay::Monday)->gregorian()->format('Y-m-d'), "\n";
echo CivilDateTime::fromGregorian(2024, 12, 30)->gregorian()->format('o-\\WW'), "\n";

2026-04-04 14:30
2026-04-06
2025-W01

متدهای weekOfYear() و weekBasedYear() و توکن‌های W و o مستقل از locale، قوانین هفته با شروع دوشنبه و تعیین سال بر اساس پنجشنبه را در تقویم view اعمال می‌کنند. برای شناسه هفته ISO میلادی از view میلادی استفاده کنید. نزدیک مرز محدوده، اگر پنجشنبه یا سال هفته خارج از محدوده باشد، ممکن است WeekAtBoundaryException رخ دهد.

فصل سه‌ماهه و ابتدا و انتهای بازه

quarter() عدد 1 تا 4 می‌دهد. متدهای startOfMonth()، endOfMonth()، startOfYear()، endOfYear()، startOfQuarter() و endOfQuarter() روز تقویمی را انتخاب می‌کنند و ساعت را حفظ می‌کنند. اگر 00:00:00 یا 23:59:59 می‌خواهید، روی خروجی startOfDay() یا endOfDay() را صدا بزنید. برای query پایگاه داده، بازه از شروع فعلی تا قبل از شروع بعدی، وابستگی به دقت ثانیه در انتهای بازه را حذف می‌کند؛ مثال‌های کاربردی را ببینید.

اختلاف تاریخ‌ها

اختلاف‌ها علامت‌دارند و از مقدار فعلی منهای مقدار دیگر به دست می‌آیند. diffInDays() روی مقدار اصلی JDNها را کم می‌کند و ساعت را نادیده می‌گیرد. اختلاف ثانیه، دقیقه و ساعت بر اساس ساعت محلی است؛ دقیقه و ساعت به سمت صفر بریده می‌شوند. diffInMonths() و diffInYears() روی view، واحد کامل تقویمی را بر اساس روز ماه حساب می‌کنند و ساعت را نادیده می‌گیرند. طبق این قاعده، ۲۸ فوریه که با محدود کردن روز به دست آمده، یک ماه کامل بعد از ۳۱ ژانویه نیست؛ مثال بالا همین را نشان می‌دهد. زمان نسبی ساعت روز را هم بررسی می‌کند.

مقایسه

متدهای equals()، lessThan()، greaterThan()، lessThanOrEqual() و greaterThanOrEqual()، JDN و ثانیه را مقایسه می‌کنند و برچسب منطقه زمانی را نادیده می‌گیرند. CivilDateTime::compare() را می‌توان به usort داد. min() و max() حداقل یک مقدار می‌خواهند و هنگام برابری اولین مقدار را حفظ می‌کنند. between($a, $b, $inclusive = true) ترتیب دو مرز را خودش تشخیص می‌دهد؛ isSameDay() فقط JDN را مقایسه می‌کند. برای مقایسه لحظه‌ها در مناطق زمانی مختلف از timestamp استفاده کنید.

عبور از مرز ام‌القری در محاسبات

جابه‌جایی روز و هفته روی JDN انجام می‌شود و می‌تواند از محدوده هر تقویم خارج شود. سازنده مقدار اصلی محدوده تقویم را بررسی نمی‌کند. پیش از خواندن نتیجه، isInSupportedRange() را روی view مقصد بررسی کنید. جابه‌جایی ماه و سال ام‌القری به جدول نیاز دارد و ممکن است همان هنگام محاسبه خطا بدهد. مثال مرز محدوده را ببینید.