Logo
PERIOD

This is the documentation for version 4.0 which will be supported until 2022-08-21. Please consider upgrading your code to the latest stable version

Helper functions

Since version 4.2 both functions are deprecated and you are encouraged to use the classes instead.

Since this package relies heavily on DateTimeImmutable and DateInterval objects and because it is sometimes complicated to get your hands on such objects the package comes bundled with two simple functions defined under the League\Period namespace:

  • League\Period\datepoint;
  • League\Period\duration;

datepoint

the League\Period\datepoint function is deprecated since version 4.2. Your encouraged to use the League\Period\Datepoint class instead.

function League\Period\datepoint(mixed $datepoint): DateTimeImmutable;

Returns a DateTimeImmutable object or throws:

  • a TypeError if the submitted parameters have the wrong type.
  • a PHP Exception if creating a DateTimeImmutable fails.

parameters

  • $datepoint can be:
    • a DateTimeInterface implementing object
    • a string parsable by the DateTime constructor.
    • an integer interpreted as a timestamp.

Because we are using PHP's parser, values exceeding ranges will be added to their parent values.

If no timezone information is given, the returned DateTimeImmutable object will use the current timezone.

examples

Using the $datepoint argument

use function League\Period\datepoint;

datepoint('yesterday'); // returns new DateTimeImmutable('yesterday')
datepoint('2018');      // returns new DateTimeImmutable('@2018')
datepoint(2018);        // returns new DateTimeImmutable('@2018')
datepoint(new DateTime('2018-10-15'));  // returns new DateTimeImmutable('2018-10-15')
datepoint(new DateTimeImmutable('2018-10-15'));  // returns new DateTimeImmutable('2018-10-15')

duration

The League\Period\duration function is deprecated since version 4.2. Your encouraged to use the League\Period\Duration class instead.

function League\Period\duration(mixed $duration): DateInterval;

Converts its single input into a DateInterval object or throws a TypeError otherwise.

parameter

$duration can be:

  • a League\Period\Period object;
  • a DateInterval object;
  • a string parsable by the DateInterval::createFromDateString method.
  • an integer interpreted as the interval expressed in seconds.

WARNING: When the string is not parsable by DateInterval::createFromDateString a DateInterval object representing the 0 interval is returned as described in PHP bug #50020.

Examples

use League\Period\Period;
use function League\Period\duration;

duration('1 DAY');                  // returns new DateInterval('P1D')
duration(2018);                     // returns new DateInterval('PT2018S')
duration(new DateInterval('PT1H')); // returns new DateInterval('PT1H')
duration(new Period('now', 'tomorrow'));
// returns (new DateTime('yesterday'))->diff(new DateTime('tomorrow'))