Using Calends in PHP

Calends exposes a very small handful of things for use outside the library itself. One is the Calends class, documented here, which should be the only interface users of the library ever need to touch.

Another thing Calends exposes is the TAITime class, used to store and manipulate the instants of time which make up a Calends instance. The rest are interfaces for extending the library’s functionality. These are covered in the Custom Calendars in PHP section.

Примечание

Calends objects are immutable - all methods return a new Calends object where they might otherwise alter the current one. This has the side effect of using more memory to perform manipulations than updating values on an existing object would. It makes many operations safer, though, than mutable objects would allow.

class Calends\Calends: The main entry point to Calends and its functionality. Calends objects can only be created with the Calends\Calends::create function, and not directly. Calends does implement the Serializable interface, though, so it’s safe to serialize/unserialize instances if you want.

Create

static Calends\Calends::create($value, $calendar, $format)

Параметры

$value (mixed) – The value to parse the date(s)/time(s) from.
$calendar (string) – The calendar system to parse the date(s)/time(s) with.
$format (string) – The format the date(s)/time(s) is/are expected to use.

Результат

A new Calends object

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

Calends

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

CalendsException – when an error occurs

Creates a new Calends object, using $calendar to select a calendar system, and $format to parse the contents of $value into the Calends object’s internal instants. The type of $value can vary based on the calendar system itself, but generally speaking can always be a string.

In any case, the value can always be an associative array, where the keys are any two of start, end, and duration. If all three are provided, duration is ignored in favor of calculating it directly.

The calendar system then converts $value to a TAITime instant, which the Calends object sets to the appropriate internal value.

Read

Calends\Calends::date($calendar, $format)

Параметры

$calendar (string) – The calendar system to format the date/time with.

$format (string) – The format the date/time is expected to be in.

Результат

The start date of the Calends object

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

string

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

CalendsException – when an error occurs

Retrieves the start date of the Calends object as a string. The value is generated by the calendar system given in $calendar, according to the format string in $format.

Calends\Calends::endDate($calendar, $format)

Параметры

$calendar (string) – The calendar system to format the date/time with.

$format (string) – The format the date/time is expected to be in.

Результат

The end date of the Calends object

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

string

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

CalendsException – when an error occurs

Retrieves the end date of the Calends object as a string. The value is generated by the calendar system given in $calendar, according to the format string in $format.

Calends\Calends::duration()

Результат

The duration of the Calends object

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

string

Retrieves the duration of the Calends object as a decimal string. This value will be 0 if the Calends object is an instant.

Update

Calends\Calends::withDate($value, $calendar, $format)

Параметры

$value (mixed) – The value to parse the date/time from.

$calendar (string) – The calendar system to parse the date/time with.

$format (string) – The format the date/time is expected to use.

Результат

A new Calends object

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

Calends

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

CalendsException – when an error occurs

Returns a Calends object with a start date based on the current Calends object’s value. The inputs are the same as for Calends\Calends::create, above, except the string → value map option isn’t available, since you’re already specifically setting the start value explicitly.

Calends\Calends::withEndDate($value, $calendar, $format)

Параметры

$value (mixed) – The value to parse the date/time from.

$calendar (string) – The calendar system to parse the date/time with.

$format (string) – The format the date/time is expected to use.

Результат

A new Calends object

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

Calends

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

CalendsException – when an error occurs

Returns a Calends object with an end date based on the current Calends object’s value. The inputs are the same as for Calends\Calends::create, above, except the string → value map option isn’t available, since you’re already specifically setting the end value explicitly.

Calends\Calends::withDuration($duration, $calendar)

Параметры

$duration (string) – The value to parse the new duration from.

$calendar (string) – The calendar system to parse the date/time with.

Результат

A new Calends object

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

Calends

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

CalendsException – when an error occurs

Returns a Calends object with a duration set by adjusting the current Calends object’s end point, and using its start point as an anchor. The $duration value is interpreted by the calendar system given in $calendar, so is subject to any of its rules.

Calends\Calends::withDurationFromEnd($duration, $calendar)

Параметры

$duration (string) – The value to parse the new duration from.

$calendar (string) – The calendar system to parse the date/time with.

Результат

A new Calends object

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

Calends

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

CalendsException – when an error occurs

Returns a Calends object with a duration set by adjusting the current Calends object’s start point, and using its end point as an anchor. The $duration value is interpreted by the calendar system given in $calendar, so is subject to any of its rules.

Manipulate

Calends\Calends::add($offset, $calendar)

Параметры

$offset (string) – The value to parse the offset from.

$calendar (string) – The calendar system to parse the date/time with.

Результат

A new Calends object

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

Calends

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

CalendsException – when an error occurs

Increases the end date of the Calends object’s current value by $offset, as interpreted by the calendar system given in $calendar, and returns a new Calends object with the result.

Calends\Calends::addFromEnd($offset, $calendar)

Параметры

$offset (string) – The value to parse the offset from.

$calendar (string) – The calendar system to parse the date/time with.

Результат

A new Calends object

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

Calends

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

CalendsException – when an error occurs

Increases the start date of the Calends object’s current value by $offset, as interpreted by the calendar system given in $calendar, and returns a new Calends object with the result.

Calends\Calends::subtract($offset, $calendar)

Параметры

$offset (string) – The value to parse the offset from.

$calendar (string) – The calendar system to parse the date/time with.

Результат

A new Calends object

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

Calends

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

CalendsException – when an error occurs

Works the same as add, except it decreases the start date, rather than increasing it.

Calends\Calends::subtractFromEnd($offset, $calendar)

Параметры

$offset (string) – The value to parse the offset from.

$calendar (string) – The calendar system to parse the date/time with.

Результат

A new Calends object

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

Calends

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

CalendsException – when an error occurs

Works the same as addFromEnd, except it decreases the end date, rather than increasing it.

Calends\Calends::next($offset, $calendar)

Параметры

$offset (string) – The value to parse the offset from.

$calendar (string) – The calendar system to parse the date/time with.

Результат

A new Calends object

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

Calends

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

CalendsException – when an error occurs

Returns a Calends object of $offset duration (as interpreted by the calendar system given in $calendar), which abuts the current Calends object’s value. If $offset is empty, $calendar is ignored, and the current object’s duration is used instead.

Calends\Calends::previous($offset, $calendar)

Параметры

$offset (string) – The value to parse the offset from.

$calendar (string) – The calendar system to parse the date/time with.

Результат

A new Calends object

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

Calends

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

CalendsException – when an error occurs

Returns a Calends object of $offset duration (as interpreted by the calendar system given in $calendar), which abuts the current Calends object’s value. If $offset is empty, $calendar is ignored, and the current object’s duration is used instead.

Combine

Calends\Calends::merge($c2)

Параметры

$c2 (Calends\Calends) – The Calends object to merge.

Результат

A new Calends object

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

Calends

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

CalendsException – when an error occurs

Returns a Calends object spanning from the earliest start date to the latest end date between the current Calends object and $c2.

Calends\Calends::intersect($c2)

Параметры

$c2 (Calends\Calends) – The Calends object to intersect.

Результат

A new Calends object

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

Calends

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

CalendsException – when an error occurs

Returns a Calends object spanning the overlap between the current Calends object and $c2. If the current object and $c2 don’t overlap, throws an error.

Calends\Calends::gap($c2)

Параметры

$c2 (Calends\Calends) – The Calends object to gap.

Результат

A new Calends object

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

Calends

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

CalendsException – when an error occurs

Returns a Calends object spanning the gap between the current Calends object and $c2. If the current object and $c2 overlap (and there is, therefore, no gap to return), throws an error.

Compare

Calends\Calends::difference($c2, $mode)

Параметры

$c2 (Calends\Calends) – The Calends object to compare.

$mode (string) – The comparison mode.

Результат

The difference, as a decimal string

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

string

Returns the difference of the current Calends object minus $c2, using $mode to select which values to use in the calculation. Valid $modes include:

start - use the start date of both the current object and $c2

duration - use the duration of both the current object and $c2

end - use the end date of both the current object and $c2

start-end - use the start of the current object, and the end of $c2

end-start - use the end of the current object, and the start of $c2

Calends\Calends::compare($c2, $mode)

Параметры

$c2 (Calends\Calends) – The Calends object to compare.

$mode (string) – The comparison mode.

Результат

A standard comparison result

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

int

Returns -1 if the current Calends object is less than $c2, 0 if they are equal, and 1 if the current object is greater than $c2, using $mode to select which values to use in the comparison. Valid $modes are the same as for Calends\Calends::difference, above.

Calends\Calends::contains($c2)

Параметры

$c2 (Calends\Calends) – The Calends object to compare.

Результат

The result of the comparison

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

bool

Checks whether the current Calends object contains all of $c2.

Calends\Calends::overlaps($c2)

Параметры

$c2 (Calends\Calends) – The Calends object to compare.

Результат

The result of the comparison

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

bool

Checks whether the current Calends object overlaps with $c2.

Calends\Calends::abuts($c2)

Параметры

$c2 (Calends\Calends) – The Calends object to compare.

Результат

The result of the comparison

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

bool

Checks whether the current Calends object abuts $c2 (that is, whether one begins at the same instant the other ends).

Calends\Calends::isSame($c2)

Параметры

$c2 (Calends\Calends) – The Calends object to compare.

Результат

The result of the comparison

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

bool

Checks whether the current Calends object covers the same span of time as $c2.

Calends\Calends::isShorter($c2)

Параметры

$c2 (Calends\Calends) – The Calends object to compare.

Результат

The result of the comparison

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

bool

Compares the duration of the current Calends object and $c2.

Calends\Calends::isSameDuration($c2)

Параметры

$c2 (Calends\Calends) – The Calends object to compare.

Результат

The result of the comparison

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

bool

Compares the duration of the current Calends object and $c2.

Calends\Calends::isLonger($c2)

Параметры

$c2 (Calends\Calends) – The Calends object to compare.

Результат

The result of the comparison

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

bool

Compares the duration of the current Calends object and $c2.

Calends\Calends::isBefore($c2)

Параметры

$c2 (Calends\Calends) – The Calends object to compare.

Результат

The result of the comparison

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

bool

Compares the entirety of the current Calends object with the start date of $c2.

Calends\Calends::startsBefore($c2)

Параметры

$c2 (Calends\Calends) – The Calends object to compare.

Результат

The result of the comparison

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

bool

Compares the start date of the current Calends object with the start date of $c2.

Calends\Calends::endsBefore($c2)

Параметры

$c2 (Calends\Calends) – The Calends object to compare.

Результат

The result of the comparison

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

bool

Compares the end date of the current Calends object with the start date of $c2.

Calends\Calends::isDuring($c2)

Параметры

$c2 (Calends\Calends) – The Calends object to compare.

Результат

The result of the comparison

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

bool

Checks whether the entirety of the current Calends object lies between the start and end dates of $c2.

Calends\Calends::startsDuring($c2)

Параметры

$c2 (Calends\Calends) – The Calends object to compare.

Результат

The result of the comparison

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

bool

Checks whether the start date of the current Calends object lies between the start and end dates of $c2.

Calends\Calends::endsDuring($c2)

Параметры

$c2 (Calends\Calends) – The Calends object to compare.

Результат

The result of the comparison

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

bool

Checks whether the end date of the current Calends object lies between the start and end dates of $c2.

Calends\Calends::isAfter($c2)

Параметры

$c2 (Calends\Calends) – The Calends object to compare.

Результат

The result of the comparison

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

bool

Compares the entirety of the current Calends object with the end date of $c2.

Calends\Calends::startsAfter($c2)

Параметры

$c2 (Calends\Calends) – The Calends object to compare.

Результат

The result of the comparison

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

bool

Compares the start date of the current Calends object with the end date of $c2.

Calends\Calends::endsAfter($c2)

Параметры

$c2 (Calends\Calends) – The Calends object to compare.

Результат

The result of the comparison

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

bool

Compares the end date of the current Calends object with the end date of $c2.

Export

It’s possible to export Calends values in a couple of ways. It implements Serializable and JsonSerializable, as well as the __toString method, so the regular mechanisms for each of those are readily available and usable. In addition, it also offers support for JSON-decoding values directly:

static Calends\Calends::jsonUnserialize($encoded)

Параметры

$encoded (string) – The JSON-encoded value to import.

Результат

A new Calends object

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

Calends

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

CalendsException – when an error occurs

Error Handling

class Calends\CalendsException: A very simple exception class, directly extending Exception. It is thrown by the library for all encountered errors.