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
- Parâmetros
$date (
mixed
) – The input date. Should support strings at the very minimum.$format (
string
) – The format string for parsing the input date.
- Retorno
The parsed internal timestamp.
- Tipo de retorno
- Gera
CalendsException
– when an error occurs
Converts an input date/time representation to an internal
TAITime
.
- fromInternal(TAITime $stamp, string $format) string
- Parâmetros
$stamp (
TAITime
) – The internal timestamp value.$format (
string
) – The format string for formatting the output date.
- Retorno
The formatted date/time.
- Tipo de retorno
string
- Gera
CalendsException
– when an error occurs
Converts an internal
TAITime
to a date/time string.
- offset(TAITime $stamp, mixed $offset) TAITime
- Parâmetros
$stamp (
TAITime
) – The internal timestamp value.$offset (
mixed
) – The input offset. Should support strings at the very minimum.
- Retorno
The adjusted internal timestamp.
- Tipo de retorno
- Gera
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
- Parâmetros
$name (
string
) – The calendar system name to check for.
- Retorno
Whether or not the calendar system is currently registered.
- Tipo de retorno
bool
Returns whether or not a calendar system has been registered, yet.
- static Calends\CalendarDefinition::listRegistered array
- Retorno
The sorted list of calendar systems currently registered.
- Tipo de retorno
[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 aTAI64NARUX
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; thefloat
type is used, here, only to be able to hold a full signed 64-bit integer value regardless of architecture.Nota
TAI vs UTC
You may have noticed that a TAI64Time object stores times in
TAI seconds
, notUnix seconds
, with a timezone offset ofTAI
rather thanUTC
. 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 when0 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 usingtoUTC
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
- Parâmetros
$z (
TAITime
) – The timestamp to add to the current one.
- Retorno
The sum of the two timestamps.
- Tipo de retorno
Calculates the sum of two
TAITime
values.
- sub(TAITime $z) TAITime
- Parâmetros
$z (
TAITime
) – The timestamp to subtract from the current one.
- Retorno
The difference of the two timestamps.
- Tipo de retorno
Calculates the difference of two
TAITime
values.
- toString() string
- Retorno
The decimal string representation of the current timestamp.
- Tipo de retorno
string
Returns the decimal string representation of the
TAITime
value.Nota
TAITime
also implements__toString
, so you can use that instead of calling this function directly, if you prefer.
- fromString(string $in) TAITime
- Parâmetros
$in (
string
) – The decimal string representation of a timestamp to calculate.
- Retorno
The calculated timestamp.
- Tipo de retorno
Calculates a
TAITime
from its decimal string representation.
- toHex() string
- Retorno
The hexadecimal string representation of the current timestamp.
- Tipo de retorno
string
Returns the hexadecimal string representation of the
TAITime
value.
- fromHex(string $in) TAITime
- Parâmetros
$in (
string
) – The hexadecimal string representation of a timestamp to calculate.
- Retorno
The calculated timestamp.
- Tipo de retorno
Calculates a
TAITime
from its hexadecimal string representation.
- toNumber() float
- Retorno
The numeric representation of the current timestamp.
- Tipo de retorno
float
Returns the
float
representation of theTAITime
value.
- fromNumber(numeric $in) TAITime
- Parâmetros
$in (
integer
orfloat
) – The arbitrary-precision floating point representation of a timestamp to calculate.
- Retorno
The calculated timestamp.
- Tipo de retorno
Calculates a
TAITime
from its numeric (integer
orfloat
) representation.
- fromUTC() TAITime
- Retorno
The calculated timestamp.
- Tipo de retorno
Removes the UTC leap second offset from a TAITime value.