Custom Calendars in PHP

Adding new calendars to Calends is a fairly straightforward process. Extend the CalendarDefinition abstract class, and implement three methods. Then, simply construct an instance of your calendar system, and Calends will do the rest.

Define

Extend the CalendarDefinition class, implementing the following methods:

class Calends\CalendarDefinition

toInternal(mixed $date, string $format) → TAITime

Параметры

• $date (mixed) – The input date. Should support strings at the very minimum.

• $format (string) – The format string for parsing the input date.

Результат

The parsed internal timestamp.

Тип результата

TAITime

Бросает исключение

CalendsException – when an error occurs

Converts an input date/time representation to an internal TAITime.

fromInternal(TAITime $stamp, string $format) → string

Параметры

• $stamp (TAITime) – The internal timestamp value.

• $format (string) – The format string for formatting the output date.

Результат

The formatted date/time.

Тип результата

string

Бросает исключение

CalendsException – when an error occurs

Converts an internal TAITime to a date/time string.

offset(TAITime $stamp, mixed $offset) → TAITime

Параметры

• $stamp (TAITime) – The internal timestamp value.

• $offset (mixed) – The input offset. Should support strings at the very minimum.

Результат

The adjusted internal timestamp.

Тип результата

TAITime

Бросает исключение

CalendsException – when an error occurs

Adds the given offset to an internal TAITime.

Registration

Register

Once it is registered with the library, your calendar system can be used from anywhere in your application. To register a system, simply construct an instance:

$customCalendars[] = new MyCalendarSystem('example', 'yyyy-mm-dd@HH-MM-SS');

The first argument is the calendar system’s name. The second is a default format string which will be passed to your calendar system whenever users leave the format string blank or unset with Calends methods.

Unregister

There are two ways to unregister a calendar system once it’s no longer needed. The first is to simply destruct the instance you created to register it. For that reason, it’s important to store all your calendar systems to variables rather than simply constructing them in place. Well, that and the fact you need the calendar system object to persist in order to handle requests from the rest of the library.

The other way to unregister a calendar system is to do so manually, using the instance you created to register it in the first place:

Calends\CalendarDefinition::unregister()

Removes a calendar system from the callback list.

Check and List

static Calends\CalendarDefinition::isRegistered(string $name) → bool

Параметры

• $name (string) – The calendar system name to check for.

Результат

Whether or not the calendar system is currently registered.

Тип результата

bool

Returns whether or not a calendar system has been registered, yet.

static Calends\CalendarDefinition::listRegistered → array

Результат

The sorted list of calendar systems currently registered.

Тип результата

[string]

Returns the list of calendar systems currently registered.

Types and Values

Now we get to the inner workings that make calendar systems function – even the built-in ones. The majority of the «magic» comes from the TAITime object itself, as a reliable way of storing the exact instants being calculated, and the only way times are handled by the library itself. A handful of methods provide basic operations that calendar system developers can use to simplify their conversions (adding and subtracting the values of other timestamps, and importing/exporting timestamp values from/to string and numeric types, in particular), and a couple of helpers exclusively handle adding and removing UTC leap second offsets. As long as you can convert your dates to/from Unix timestamps in a string or numeric type, the rest is handled entirely by these helpers in the library itself.

class Calends\TAITime

TAITime stores a TAI64NARUX instant in a reliable, easily-converted format. Each 9-digit fractional segment is stored in a separate 32-bit integer to preserve its value with a very high degree of accuracy, without having to rely on string parsing or external arbitrary-precision mathematics libraries.

property seconds(float)

The number of TAI seconds since CE 1970-01-01 00:00:00 TAI. Should be an integer value; the float type is used, here, only to be able to hold a full signed 64-bit integer value regardless of architecture.

Примечание

TAI vs UTC

You may have noticed that a TAI64Time object stores times in TAI seconds, not Unix seconds, with a timezone offset of TAI rather than UTC. This distinction is very important as it will affect internal calculations and comparisons to mix the two up. TAI time is very similar to Unix time (itself based on UTC time), with one major difference. While Unix/UTC seconds include the insertion and removal of «leap seconds» to keep the solar zenith at local noon (which is useful for day-to-day living and planning), TAI seconds are a continuous count, unconcerned with dates whatsoever. Indeed, the only reason a date was given in the description above was to make it easier for human readers to know exactly when 0 TAI took place.

In other words, once you have a Unix timestamp of your instant calculated, be sure to convert it using fromUTC before returning the result to the rest of the library. And then, of course, you’ll also need to convert instants from the library back using toUTC before generating outputs.

property nano(integer)

The first 9 digits of the timestamp’s fractional component.

property atto(integer)

The 10th through 18th digits of the fractional component.

property ronto(integer)

The 19th through 27th digits of the fractional component.

property udecto(integer)

The 28th through 36th digits of the fractional component.

property xindecto(integer)

The 37th through 45th digits of the fractional component.

add(TAITime $z) → TAITime

Параметры

• $z (TAITime) – The timestamp to add to the current one.

Результат

The sum of the two timestamps.

Тип результата

TAITime

Calculates the sum of two TAITime values.

sub(TAITime $z) → TAITime

Параметры

• $z (TAITime) – The timestamp to subtract from the current one.

Результат

The difference of the two timestamps.

Тип результата

TAITime

Calculates the difference of two TAITime values.

toString() → string

Результат

The decimal string representation of the current timestamp.

Тип результата

string

Returns the decimal string representation of the TAITime value.

Примечание

TAITime also implements __toString, so you can use that instead of calling this function directly, if you prefer.

fromString(string $in) → TAITime

Параметры

• $in (string) – The decimal string representation of a timestamp to calculate.

Результат

The calculated timestamp.

Тип результата

TAITime

Calculates a TAITime from its decimal string representation.

toHex() → string

Результат

The hexadecimal string representation of the current timestamp.

Тип результата

string

Returns the hexadecimal string representation of the TAITime value.

fromHex(string $in) → TAITime

Параметры

• $in (string) – The hexadecimal string representation of a timestamp to calculate.

Результат

The calculated timestamp.

Тип результата

TAITime

Calculates a TAITime from its hexadecimal string representation.

toNumber() → float

Результат

The numeric representation of the current timestamp.

Тип результата

float

Returns the float representation of the TAITime value.

fromNumber(numeric $in) → TAITime

Параметры

• $in (integer or float) – The arbitrary-precision floating point representation of a timestamp to calculate.

Результат

The calculated timestamp.

Тип результата

TAITime

Calculates a TAITime from its numeric (integer or float) representation.

fromUTC() → TAITime

Результат

The calculated timestamp.

Тип результата

TAITime

Removes the UTC leap second offset from a TAITime value.

toUTC() → TAITime

Результат

The calculated timestamp.

Тип результата

TAITime

Adds the UTC leap second offset to a TAITime value.