php-rrule

The recommended way to install the library is through Composer. Run the following command to add it to your composer.json and install the dependencies.

composer require rlanvin/php-rrule

After installation, include the Composer autoloader to access the RRule\RRule class.

require 'vendor/autoload.php';

You can instantiate an RRule object by passing an array of RFC 5545 recurrence rule parts. The object is iterable, allowing you to loop through occurrences, and provides a humanReadable() method for a natural language description of the rule.

Requirements:

• PHP >= 7.3
• The intl extension is recommended for the humanReadable() method to work correctly.

use RRule\RRule;

$rrule = new RRule([
	'FREQ' => 'MONTHLY',
	'INTERVAL' => 1,
	'DTSTART' => '2015-06-01',
	'COUNT' => 6
]);

foreach ($rrule as $occurrence) {
	echo $occurrence->format('D d M Y'),", ";
}
// Mon 01 Jun 2015, Wed 01 Jul 2015, Sat 01 Aug 2015, Tue 01 Sep 2015, Thu 01 Oct 2015, Sun 01 Nov 2015

echo $rrule->humanReadable(),"\n";
// monthly on the 1st of the month, starting from 01/06/2015, 6 times

Use these methods to check the termination conditions of a rule:

• isFinite(): Returns true if the rule has an end condition (COUNT or UNTIL).
• isInfinite(): Returns true if the rule has no end condition.

if ($rrule->isInfinite()) {
    // Handle infinite recurrence
}

The static method createFromRfcString($string, $force_rset = false) is the recommended way to instantiate a rule from a string. It automatically detects whether the string represents a single RRule or an RSet (a collection of rules/dates). If $force_rset is set to true, it will always return an RSet object.

use RRule\RRule;

$rrule = RRule::createFromRfcString('FREQ=DAILY;INTERVAL=1');

Use the rfcString() method to export the current rule as a standard RFC 5545 string. You can optionally pass a boolean $include_timezone (defaults to true) to determine whether to include timezone identifiers on DTSTART and UNTIL.

$rfcString = $rrule->rfcString();
// or
$rfcString = (string) $rrule;

To get the actual dates generated by the recurrence set, use getOccurrences() or iterate over the object directly.

• getOccurrences($limit = null): Returns an array of \DateTime objects. If $limit is provided, it returns up to $n$ occurrences. If the set is infinite and no limit is provided, it throws a \LogicException.
• Iteration: Since RSet implements Iterator, you can use it directly in a foreach loop.
• occursAt($date): Returns true if the provided date is part of the recurrence set, taking into account all inclusions and exclusions.

// Using getOccurrences
$dates = $rset->getOccurrences(10);

// Using foreach
foreach ($rset as $date) {
    echo $date->format('Y-m-d') . PHP_EOL;
}

// Checking a specific date
if ($rset->occursAt('2023-01-01')) {
    // ...
}

You can instantiate an RSet by passing a single RFC-compliant text block to the constructor. The parser supports DTSTART, RRULE, EXRULE, RDATE, and EXDATE properties. Each property must be followed by a colon (:).

If multiple DTSTART properties are found in the string, an \InvalidArgumentException is thrown.

$rfcString = "DTSTART:20230101T000000Z\nRRULE:FREQ=MONTHLY;BYDAY=1SU\nEXDATE:20230205T000000Z";
$rset = new RRule\RSet($rfcString);

The count() method returns the total number of occurrences in the rule.

Warning: Calling count() on an infinite rule will throw a \LogicException. For finite rules, this method may incur a performance penalty as it may need to iterate through the entire recurrence to calculate the total.

try {
    $total = $rrule->count();
} catch (\LogicException $e) {
    // Rule is infinite
}

An RSet is considered infinite if any of its constituent RRULEs are infinite.

• isInfinite(): Returns true if the set has no end condition.
• isFinite(): Returns true if the set has an end condition.
• count(): Returns the total number of occurrences. Warning: Calling count() on an infinite set will throw a \LogicException. For finite sets, this may incur a performance penalty if the total hasn't been cached yet.