Civil Date PHP Package

IslamicCalendar extends TabularIslamicCalendar
in package

Defines validation, conversion, and calendar-length behavior for the Islamic civil calendar.

The calendar uses tabular Islamic month lengths by default. Authoritative month lengths can be configured before calendrical use, and then become part of the calendar's effective month and year lengths.

Table of Contents

Constants

EPOCH_JDN  : int = 1948440
Julian Day Number of 1 Muharram 1 AH in the tabular Islamic calendar.

Methods

assertValidDay()  : void
Validates a calendar day.
assertValidMonth()  : void
Validates a calendar month.
assertValidYear()  : void
Validates a calendar year.
daysInMonth()  : int
Returns the effective number of days in an Islamic month.
daysInYear()  : int
Returns the effective number of days in an Islamic year.
id()  : Calendar
Returns the Islamic calendar identifier.
instance()  : static
Returns the shared instance for the concrete calendar system.
isLeapYear()  : bool
Determines whether an Islamic year contains 355 days.
isValidDay()  : bool
Determines whether a day number is valid for a calendar month.
isValidMonth()  : bool
Determines whether a month number is valid for a calendar year.
isValidYear()  : bool
Determines whether a year number is valid for this calendar.
monthsInYear()  : int
Returns the number of months in a year.
setAuthoritativeMonthLengths()  : void
Configures authoritative lengths for selected Islamic months.
toDayOfYear()  : int
Converts calendar date components to a day of year value.
todayTimeZone()  : DateTimeZone|null
Returns the timezone used to resolve today's date.
toJDN()  : int
Converts calendar date components to a Julian Day Number.
toMonthDay()  : array{0: int, 1: int}
Converts a day of year value to calendar month and day components.
toYearMonthDay()  : array{0: int, 1: int, 2: int}
Converts a Julian Day Number to calendar year, month, and day components.
findYear()  : int
Finds the Islamic year containing a Julian Day Number.
firstDayOfYearJDN()  : int
Returns the Julian Day Number of the first day of an Islamic year.

Constants

EPOCH_JDN

Julian Day Number of 1 Muharram 1 AH in the tabular Islamic calendar.

protected int EPOCH_JDN = 1948440

Methods

assertValidDay()

Validates a calendar day.

public final assertValidDay(int $year, int $month, int $day) : void
Parameters
$year : int

Calendar year.

$month : int

Calendar month number.

$day : int

Calendar day of month.

Tags
throws
InvalidArgumentException

If the date components are invalid.

assertValidMonth()

Validates a calendar month.

public final assertValidMonth(int $year, int $month) : void
Parameters
$year : int

Calendar year.

$month : int

Calendar month number.

Tags
throws
InvalidArgumentException

If the year or month is invalid.

assertValidYear()

Validates a calendar year.

public assertValidYear(int $year) : void
Parameters
$year : int

Calendar year.

Tags
throws
InvalidArgumentException

If the year is invalid.

daysInMonth()

Returns the effective number of days in an Islamic month.

public daysInMonth(int $year, int $month) : int
Parameters
$year : int

Islamic year.

$month : int

Islamic month number.

Tags
throws
InvalidArgumentException

If the year or month is invalid.

override
Return values
int —

Effective month length.

daysInYear()

Returns the effective number of days in an Islamic year.

public daysInYear(int $year) : int
Parameters
$year : int

Islamic year.

Tags
throws
InvalidArgumentException

If the year is zero.

override
Return values
int —

Effective year length.

instance()

Returns the shared instance for the concrete calendar system.

public final static instance() : static
Tags
see
Calendar::system()
Return values
static —

Calendar system instance.

isLeapYear()

Determines whether an Islamic year contains 355 days.

public isLeapYear(int $year) : bool
Parameters
$year : int

Islamic year.

Tags
throws
InvalidArgumentException

If the year is zero.

override
Return values
bool —

True when the year contains 355 days, false when it contains 354 days.

isValidDay()

Determines whether a day number is valid for a calendar month.

public isValidDay(int $year, int $month, int $day) : bool
Parameters
$year : int

Calendar year.

$month : int

Calendar month number.

$day : int

Calendar day of month.

Return values
bool —

True when the day is valid, false otherwise.

isValidMonth()

Determines whether a month number is valid for a calendar year.

public isValidMonth(int $year, int $month) : bool
Parameters
$year : int

Calendar year.

$month : int

Calendar month number.

Return values
bool —

True when the month is valid, false otherwise.

isValidYear()

Determines whether a year number is valid for this calendar.

public isValidYear(int $year) : bool
Parameters
$year : int

Calendar year.

Return values
bool —

True when the year is valid, false otherwise.

monthsInYear()

Returns the number of months in a year.

public monthsInYear(int $year) : int
Parameters
$year : int

Calendar year.

Tags
throws
InvalidArgumentException

If the year is invalid.

Return values
int —

Number of months in the year.

setAuthoritativeMonthLengths()

Configures authoritative lengths for selected Islamic months.

public setAuthoritativeMonthLengths(array<int, array<int, int>> $monthLengths) : void

Supplied month lengths override the tabular length for those months. Months without an override continue to use the tabular calendar. Each supplied month must have 29 or 30 days, and every affected year must have 354 or 355 days.

Once the calendar has been used for any calendrical operation, authoritative month lengths can no longer be changed.

Example:

IslamicCalendar::instance()->setAuthoritativeMonthLengths([
    1446 => [
        9 => 29,  // Ramadan 1446 has 29 days instead of 30
        10 => 30, // Shawwal 1446 has 30 days instead of 29
    ],
]);
Parameters
$monthLengths : array<int, array<int, int>>

Authoritative month lengths indexed by Islamic year and month. Each supplied month must contain either 29 or 30 days, and each affected year must contain either 354 or 355 days after applying the overrides.

Tags
throws
InvalidArgumentException

If a definition contains an invalid year, month, length, or effective year length.

LogicException

If authoritative month lengths are no longer changeable due to prior calendrical use.

toDayOfYear()

Converts calendar date components to a day of year value.

public toDayOfYear(int $year, int $month, int $day) : int
Parameters
$year : int

Calendar year.

$month : int

Calendar month number.

$day : int

Calendar day of month.

Tags
throws
InvalidArgumentException

If the date components are invalid.

Return values
int —

Day of year, where 1 is the first day of the year.

todayTimeZone()

Returns the timezone used to resolve today's date.

public todayTimeZone() : DateTimeZone|null
Return values
DateTimeZone|null —

Timezone for today, or null for the default timezone.

toJDN()

Converts calendar date components to a Julian Day Number.

public toJDN(int $year, int $month, int $day) : int
Parameters
$year : int

Calendar year.

$month : int

Calendar month number.

$day : int

Calendar day of month.

Tags
throws
InvalidArgumentException

If the date components are invalid.

see
CalendarSystem::toYearMonthDay()
CalendarDate::jdn()
Return values
int —

Julian Day Number.

toMonthDay()

Converts a day of year value to calendar month and day components.

public toMonthDay(int $year, int $dayOfYear) : array{0: int, 1: int}
Parameters
$year : int

Calendar year.

$dayOfYear : int

Day of year, where 1 is the first day of the year.

Tags
throws
InvalidArgumentException

If the year or day of year is invalid.

Return values
array{0: int, 1: int} —

Calendar [month, day] components.

toYearMonthDay()

Converts a Julian Day Number to calendar year, month, and day components.

public toYearMonthDay(int $jdn) : array{0: int, 1: int, 2: int}
Parameters
$jdn : int

Julian Day Number.

Tags
throws
DateOutOfRangeException

If the Julian Day Number cannot be converted to a valid calendar date.

see
CalendarSystem::toJDN()
CalendarDate::fromJDN()
Return values
array{0: int, 1: int, 2: int} —

Calendar [year, month, day] components.

findYear()

Finds the Islamic year containing a Julian Day Number.

protected findYear(int $jdn) : int
Parameters
$jdn : int

Julian Day Number.

Tags
override
Return values
int —

Islamic year containing the Julian Day Number.

firstDayOfYearJDN()

Returns the Julian Day Number of the first day of an Islamic year.

protected firstDayOfYearJDN(int $year) : int
Parameters
$year : int

Islamic year.

Tags
override
Return values
int —

Julian Day Number of the year's first day.

On this page

Search results