Recurr

https://github.com/simshaun/recurr
Admin
Recurr is a PHP library for working with recurrence rules (RRULE) and converting them into DateTime...
Tokens:72,745
Snippets:497
Trust Score:9.1
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install Recurr via Composer

Source: https://github.com/simshaun/recurr/blob/master/README.md

The recommended method for installing the Recurr library.

```bash
composer require simshaun/recurr
```

--------------------------------

### Instantiating a Recurrence Object

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/recurrence.md

Example of manually creating a new Recurrence instance with specific start, end, and index values.

```php
$recurrence = new Recurrence(
    new \DateTime('2013-06-12 20:00:00'),
    new \DateTime('2013-06-12 21:00:00'),
    1,
);
```

--------------------------------

### getWeekStart(): string

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/rule.md

Returns the current week start day as a string from 'MO' to 'SU'.

```APIDOC
## getWeekStart(): string

### Description
Returns the current week start day as a string. The return value is one of 'MO', 'TU', 'WE', 'TH', 'FR', 'SA', 'SU'.

### Method
getWeekStart

### Return Value
- string - The week start day (e.g., 'MO').

### Source
`src/Recurr/Rule.php:1126`
```

--------------------------------

### Inclusive filtering example

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/recurrence-collection.md

Shows the difference between exclusive and inclusive filtering when a recurrence starts exactly on the boundary.

```php
use Recurr\Rule;
use Recurr\Transformer\ArrayTransformer;

// Inclusive variant: a recurrence that starts exactly on the boundary survives
$start = new \DateTime('2014-06-01 04:00:00');
$rule = new Rule('FREQ=MONTHLY;COUNT=2', $start);
$collection = (new ArrayTransformer())->transform($rule);

echo count($collection->startsBetween($start, $start));        // 0 (exclusive)
echo count($collection->startsBetween($start, $start, true)); // 1 (inclusive)
```

--------------------------------

### Manage Termination Limits

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/rule.md

Example demonstrating the mutual exclusivity of COUNT and UNTIL limits.

```php
$rule = new Rule('FREQ=DAILY;COUNT=5', new \DateTime('2013-06-12 20:00:00'));
$rule->setUntil(null);            // default: no limit
$rule->setCount(10);              // now COUNT=10
$rule->setUntil(new \DateTime()); // COUNT is nullified again
```

--------------------------------

### Constructing a Recurr Rule

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/configuration.md

Example of initializing a Rule object with a start date, timezone, frequency, day constraints, and an end date, followed by generating the RRULE string.

```php
$rule = (new \Recurr\Rule())
    ->setStartDate(new \DateTime('2013-06-12 20:00:00', new \DateTimeZone('America/New_York')))
    ->setTimezone('America/New_York')
    ->setFreq('DAILY')
    ->setByDay(['MO', 'TU'])
    ->setUntil(new \DateTime('2017-12-31'));

echo $rule->getString(); // FREQ=DAILY;UNTIL=20171231T000000;BYDAY=MO,TU
```

--------------------------------

### startsAfter method signature

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/recurrence-collection.md

Filters for start dates after the specified date.

```php
public function startsAfter(\DateTime|\DateTimeImmutable $after, bool $inc = false): RecurrenceCollection
```

--------------------------------

### Basic filtering and chaining example

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/recurrence-collection.md

Demonstrates how to transform a rule into a collection and apply basic or chained filters.

```php
use Recurr\Rule;
use Recurr\Transformer\ArrayTransformer;

$rule = new Rule('FREQ=MONTHLY;COUNT=5', new \DateTime('2014-06-17 04:00:00'));
$collection = (new ArrayTransformer())->transform($rule);

// Basic filtering
$july = $collection->startsBetween(
    new \DateTime('2014-07-01 00:00:00'),
    new \DateTime('2014-07-31 23:59:59'),
);

// Chaining filters
$augustOrLater = $collection
    ->startsAfter(new \DateTime('2014-07-31 23:59:59'))
    ->endsBefore(new \DateTime('2015-12-31 00:00:00'));

echo count($augustOrLater);
```

--------------------------------

### Configure Rule with RDates and ExDates

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/rule.md

Example of initializing a Rule object and setting both inclusion and exclusion dates.

```php
$rule = (new Rule())
    ->setFreq('DAILY')
    ->setRDates(['2013-06-15T12:00:00'])
    ->setExDates(['2013-06-14']);
```

--------------------------------

### startsBefore method signature

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/recurrence-collection.md

Filters for start dates before the specified date.

```php
public function startsBefore(\DateTime|\DateTimeImmutable $before, bool $inc = false): RecurrenceCollection
```

--------------------------------

### Usage of setVirtualLimit and getVirtualLimit

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/array-transformer-config.md

Example showing how to check the default virtual limit and update it to a new value.

```php
$config = new ArrayTransformerConfig();
echo $config->getVirtualLimit(); // 732

$config->setVirtualLimit(5000);
echo $config->getVirtualLimit(); // 5000
```

--------------------------------

### ArrayTransformer Constructor Usage

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/array-transformer.md

Examples of initializing the ArrayTransformer with default settings or an explicit configuration object.

```php
use Recurr\Transformer\ArrayTransformer;

$transformer = new ArrayTransformer();                       // defaults
$transformer = new ArrayTransformer(new ArrayTransformerConfig()); // explicit
```

--------------------------------

### Recurrence getStart Method

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/recurrence.md

Retrieves the start datetime of the occurrence.

```php
public function getStart(): \DateTime|\DateTimeImmutable
```

--------------------------------

### Instantiating Weekday Objects

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/weekday.md

Examples of creating Weekday instances using both string codes and integer representations.

```php
use Recurr\Weekday;
use Recurr\Exception\InvalidWeekday;

$monday     = new Weekday('MO', null);   // any Monday
$firstMon   = new Weekday('MO', 1);      // first Monday
$lastFriday = new Weekday('FR', -1);     // last Friday
$sunday     = new Weekday(0, null);      // 0 = Sunday
```

--------------------------------

### Usage of enableLastDayOfMonthFix

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/array-transformer-config.md

Example showing how to enable the month-end fix and its effect on recurring date generation.

```php
$config = new ArrayTransformerConfig();
$config->enableLastDayOfMonthFix();

$transformer = new ArrayTransformer($config);

$rule = new \Recurr\Rule(
    'FREQ=MONTHLY;COUNT=5',
    new \DateTime('2013-01-31 20:00:00', new \DateTimeZone('America/New_York')),
    null,
    'America/New_York',
);

foreach ($transformer->transform($rule) as $r) {
    echo $r->getStart()->format('Y-m-d').PHP_EOL;
}
// 2013-01-31
// 2013-02-28
// 2013-03-31
// 2013-04-30
// 2013-05-31
```

--------------------------------

### Recurrence setStart Method

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/recurrence.md

Sets the start datetime for the occurrence.

```php
public function setStart(\DateTime|\DateTimeImmutable $start): void
```

--------------------------------

### Creating Rule instances from string and array

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/rule.md

Examples of using the static factory methods to create Rule objects.

```php
$rule = Rule::createFromString('FREQ=WEEKLY;BYDAY=MO,WE,FR', new \DateTime('2013-06-12'));
$rule = Rule::createFromArray(['FREQ' => 'YEARLY', 'BYMONTH' => '1,6']);
```

--------------------------------

### Set Week Start Method

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/rule.md

Defines the start of the week for the recurrence rule. Accepts one of MO, TU, WE, TH, FR, SA, SU and throws an InvalidArgument exception if an invalid value is provided.

```php
public function setWeekStart(string $weekStart): static
```

--------------------------------

### Recurr\Recurrence::getStart

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/recurrence.md

Returns the start datetime of the occurrence.

```APIDOC
## Recurr\Recurrence::getStart

### Description
Returns the start datetime of the occurrence.

### Method
Method

### Signature
```php
public function getStart(): \DateTime|\DateTimeImmutable
```

### Returns
- **\DateTime|\DateTimeImmutable** - The start datetime of the occurrence.
```

--------------------------------

### Usage of isLastDayOfMonthFixEnabled

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/array-transformer-config.md

Example showing how to verify the status of the last day of month fix.

```php
$config = new ArrayTransformerConfig();
var_dump($config->isLastDayOfMonthFixEnabled()); // false
$config->enableLastDayOfMonthFix();
var_dump($config->isLastDayOfMonthFixEnabled()); // true
```

--------------------------------

### UppercaseTranslator implementation

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/text-transformer.md

An example implementation of the TranslatorInterface that converts strings to uppercase.

```php
use Recurr\Transformer\TranslatorInterface;

class UppercaseTranslator implements TranslatorInterface
{
    public function trans(string $string, array $params = []): string|array
    {
        return strtoupper($string);
    }
}
```

--------------------------------

### Configure Monthly Positional ByDay

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/rule.md

Example of setting the first Monday and last Friday of each month using positional BYDAY values.

```php
$rule = (new Rule())
    ->setFreq('MONTHLY')
    ->setByDay(['+1MO', '-1FR']); // first Monday and last Friday of each month
```

--------------------------------

### Updating Transformer Configuration

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/array-transformer.md

Example of creating a new configuration object, modifying its virtual limit, and applying it to an existing transformer instance.

```php
$config = new ArrayTransformerConfig();
$config->setVirtualLimit(100);
$transformer->setConfig($config);
```

--------------------------------

### Converting Weekday to String

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/weekday.md

Examples of how Weekday objects are rendered as strings, including positional modifiers.

```php
use Recurr\Weekday;

echo new Weekday('MO', 1);  // "1MO"
echo new Weekday('FR', -1); // "-1FR"
echo new Weekday('TU', null); // "TU"
```

--------------------------------

### Get ByDay as Weekdays

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/rule.md

Method signature for retrieving BYDAY values as Weekday objects.

```php
/**
 * @return Weekday[]
 *
 * @throws InvalidWeekday
 */
public function getByDayAsWeekdays(): array
```

--------------------------------

### Recurr\Recurrence::setStart

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/recurrence.md

Sets the start datetime of the occurrence.

```APIDOC
## Recurr\Recurrence::setStart

### Description
Sets the start datetime of the occurrence.

### Method
Method

### Signature
```php
public function setStart(\DateTime|\DateTimeImmutable $start): void
```

### Parameters
- **$start** (\DateTime|\DateTimeImmutable) - Required - The start datetime to set.
```

--------------------------------

### Initializing Recurr Rule

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/rule.md

Examples of creating a Rule instance from an RRULE string or an associative array, including error handling for invalid rules.

```php
use Recurr\Rule;

// From an RRULE string with a timezone
$rule = new Rule(
    'FREQ=MONTHLY;COUNT=5',
    new \DateTime('2013-06-12 20:00:00', new \DateTimeZone('America/New_York')),
    null,
    'America/New_York',
);

// From an array of parts (FREQ is required)
$rule = new Rule(['FREQ' => 'DAILY', 'INTERVAL' => '2'], '2013-06-12 20:00:00');

// Error handling: malformed rules throw InvalidRRule
try {
    new Rule('COUNT=5'); // no FREQ part
} catch (\Recurr\Exception\InvalidRRule $e) {
    echo $e->getMessage(); // "FREQ is required"
}
```

--------------------------------

### ArrayTransformerConfig usage

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/configuration.md

Example of configuring the ArrayTransformer with a custom virtual limit and enabling the last day of month fix.

```APIDOC
## ArrayTransformerConfig

### Description
Configuration object for the ArrayTransformer. Allows setting a virtual limit for infinite rules and enabling the last day of month fix.

### Methods
- **setVirtualLimit(int)** - Optional - Sets the maximum occurrences generated for an infinitely recurring rule. Default is 732.
- **enableLastDayOfMonthFix()** - Optional - Enables the last day of month fix.
- **disableLastDayOfMonthFix()** - Optional - Disables the last day of month fix.
- **isLastDayOfMonthFixEnabled()** - Optional - Returns whether the last day of month fix is enabled.

### Example
```php
use Recurr\Transformer\ArrayTransformer;
use Recurr\Transformer\ArrayTransformerConfig;

$config = new ArrayTransformerConfig();
$config->setVirtualLimit(2000);
$config->enableLastDayOfMonthFix();

$transformer = new ArrayTransformer($config);
// or: $transformer->setConfig($config);
```
```

--------------------------------

### getWeekStartAsNum(): int

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/rule.md

Returns the week start day as an integer where 0=Monday and 6=Sunday.

```APIDOC
## getWeekStartAsNum(): int

### Description
Returns the week start day as an integer representation. The return value is between 0 and 6, where 0=Monday and 6=Sunday.

### Method
getWeekStartAsNum

### Return Value
- int - The week start day as a number (0-6).

### Source
`src/Recurr/Rule.php:1134`
```

--------------------------------

### Basic usage of ArrayTransformer

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/array-transformer.md

Example of transforming a daily recurrence rule with a count limit into a collection and iterating over the results.

```php
use Recurr\Rule;
use Recurr\Transformer\ArrayTransformer;

$rule = new Rule('FREQ=DAILY;COUNT=5', new \DateTime('2014-06-17 04:00:00'));
$transformer = new ArrayTransformer();

$collection = $transformer->transform($rule); // 5 Recurrence objects

foreach ($collection as $recurrence) {
    echo $recurrence->getStart()->format('Y-m-d H:i').PHP_EOL;
}
```

--------------------------------

### Recurrence Constructor Definition

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/recurrence.md

The constructor accepts optional start and end datetimes and a positional index.

```php
public function __construct(
    \DateTime|\DateTimeImmutable|null $start = null,
    \DateTime|\DateTimeImmutable|null $end = null,
    protected int $index = 0,
)
```

--------------------------------

### Create Rule Object from String

Source: https://github.com/simshaun/recurr/blob/master/README.md

Initialize a new Rule object using an RRULE string, start date, optional end date, and timezone.

```php
$timezone    = 'America/New_York';
$startDate   = new \DateTime('2013-06-12 20:00:00', new \DateTimeZone($timezone));
$endDate     = new \DateTime('2013-06-14 20:00:00', new \DateTimeZone($timezone)); // Optional
$rule        = new \Recurr\Rule('FREQ=MONTHLY;COUNT=5', $startDate, $endDate, $timezone);
```

--------------------------------

### setWeekStart(string $weekStart): static

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/rule.md

Sets the week start day for the recurrence rule. Accepts one of MO, TU, WE, TH, FR, SA, SU (case-insensitive) and throws an InvalidArgument exception if an invalid value is provided.

```APIDOC
## setWeekStart(string $weekStart): static

### Description
Sets the week start day for the recurrence rule. The value must be one of MO, TU, WE, TH, FR, SA, SU (case-insensitive input is uppercased). This is significant for WEEKLY frequencies with INTERVAL > 1 and YEARLY BYWEEKNO rules. Default is 'MO'.

### Method
setWeekStart

### Parameters
- **$weekStart** (string) - Required - One of MO, TU, WE, TH, FR, SA, SU.

### Return Value
- static - Returns the current Rule instance for method chaining.

### Exceptions
- InvalidArgument - Thrown when the week start is not one of MO, TU, WE, TH, FR, SA, SU.

### Source
`src/Recurr/Rule.php:1112`
```

--------------------------------

### Mutating a Recurrence Object

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/recurrence.md

Example of creating a Recurrence object and using setter methods to update its values.

```php
use Recurr\Recurrence;

// Cloning values from an existing recurrence before mutating
$recurrence = new Recurrence(index: 2);
$recurrence->setStart(new \DateTime('2000-01-01'));
$recurrence->setEnd(new \DateTime('2000-01-01 01:00:00'));

echo $recurrence->getStart()->format('c'); // 2000-01-01T00:00:00+00:00
echo $recurrence->getIndex();              // 2
```

--------------------------------

### Apply AfterConstraint to recurrence rules

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/constraints.md

Demonstrates using AfterConstraint to fetch dates starting from a specific point. Setting the third parameter to false ensures the count constraint budget is not consumed by dates before the constraint.

```php
use Recurr\Rule;
use Recurr\Transformer\ArrayTransformer;
use Recurr\Transformer\Constraint\BeforeConstraint;
use Recurr\Transformer\Constraint\AfterConstraint;

// Building a custom two-limit pipeline with countConstraintFailures semantics
$rule = new Rule('FREQ=DAILY', new \DateTime('2014-01-01')); // unlimited
$transformer = new ArrayTransformer();

// AfterConstraint fetches ahead until $after; countConstraintFailures=false
// keeps the COUNT budget untouched by un-wanted early dates.
$collection = $transformer->transform(
    $rule,
    new AfterConstraint(new \DateTime('2014-03-01 00:00:00')),
    false,
);

echo count($collection); // up to the virtual limit (732 default)
```

--------------------------------

### Rule configuration setters

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/configuration.md

Chained setter methods for configuring the recurrence rule, such as frequency, interval, count, until, week start, and BYxxx parts.

```APIDOC
## Rule configuration setters

### Description
Chained setter methods for configuring the recurrence rule, such as frequency, interval, count, until, week start, and BYxxx parts.

### Methods
- **setFreq($freq)** - Sets the frequency (required for transform).
- **setInterval($interval)** - Sets the interval (default: 1).
- **setCount($count)** - Sets the count (default: null).
- **setUntil($until)** - Sets the until date (default: null).
- **setWeekStart($weekStart)** - Sets the week start day (default: 'MO').
- **setBySecond($bySecond)** - Sets by-second rule (default: null).
- **setByMinute($byMinute)** - Sets by-minute rule (default: null).
- **setByHour($byHour)** - Sets by-hour rule (default: null).
- **setByDay($byDay)** - Sets by-day rule (default: null).
- **setByMonthDay($byMonthDay)** - Sets by-month-day rule (default: null).
- **setByYearDay($byYearDay)** - Sets by-year-day rule (default: null).
- **setByWeekNumber($byWeekNumber)** - Sets by-week-number rule (default: null).
- **setByMonth($byMonth)** - Sets by-month rule (default: null).
- **setBySetPosition($bySetPosition)** - Sets by-set-position rule (default: null).
- **setRDates($rDates)** - Sets RDATEs (default: [] when nulled, else null).
- **setExDates($exDates)** - Sets EXDATEs (default: null).
- **getString($timezoneType)** - Returns the RRULE string. $timezoneType defaults to Rule::TZ_FLOAT; 'fixed' emits UTC Z/TZID= output.

### Example
```php
$rule = (new \Recurr\Rule())
    ->setStartDate(new \DateTime('2013-06-12 20:00:00', new \DateTimeZone('America/New_York')))
    ->setTimezone('America/New_York')
    ->setFreq('DAILY')
    ->setByDay(['MO', 'TU'])
    ->setUntil(new \DateTime('2017-12-31'));

echo $rule->getString(); // FREQ=DAILY;UNTIL=20171231T000000;BYDAY=MO,TU
```
```

--------------------------------

### Serializing rules to string

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/rule.md

Examples of serializing a Rule object to an RRULE string using both floating and fixed (UTC) timezone formats.

```php
$rule = (new Rule())
    ->setStartDate(new \DateTime('2013-06-12 20:00:00'))
    ->setFreq('DAILY')
    ->setByDay(['MO', 'TU'])
    ->setUntil(new \DateTime('2017-12-31'));
echo $rule->getString();
// FREQ=DAILY;UNTIL=20171231T000000;BYDAY=MO,TU

// Fixed (UTC) timezone variant: UNTIL is emitted as UTC with a trailing Z,
// and DTSTART/DTEND carry an explicit TZID prefix when marked for inclusion.
$fixed = (new Rule())
    ->setStartDate(new \DateTime('2013-06-12 20:00:00'), true) // include DTSTART in the string
    ->setTimezone('America/New_York')
    ->setFreq('DAILY')
    ->setByDay(['MO', 'TU'])
    ->setUntil(new \DateTime('2017-12-31', new \DateTimeZone('America/New_York')));
echo $fixed->getString(Rule::TZ_FIXED);
// FREQ=DAILY;UNTIL=20180101T050000Z;DTSTART;TZID=America/New_York:20130612T200000;BYDAY=MO,TU
```

--------------------------------

### setByYearDay(?array $byYearDay) / getByYearDay(): ?array

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/rule.md

Sets or gets the BYYEARDAY part. Valid values are 1-366 or -366...-1.

```APIDOC
## setByYearDay(?array $byYearDay) / getByYearDay(): ?array

### Description
Sets or gets the BYYEARDAY part. Valid values are 1-366 or -366...-1.

### Method
setByYearDay / getByYearDay

### Parameters
#### setByYearDay
- **$byYearDay** (?array) - Required - Array of year days. Passing null clears the part.

### Return Value
- setByYearDay: static
- getByYearDay: ?array

### Source
src/Recurr/Rule.php:1022 / :1032
```

--------------------------------

### Rule::__construct

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/rule.md

Creates a new Rule instance. Accepts an RRULE string or associative array, optional start and end dates, and a timezone. Throws InvalidRRule if the rule is invalid.

```APIDOC
## Rule::__construct

### Description
Creates a new Rule instance. Accepts an RRULE string or associative array, optional start and end dates, and a timezone. Throws InvalidRRule if the rule is invalid.

### Method
Constructor

### Signature
```php
public function __construct(
    array|string|null $rrule = null,
    \DateTime|\DateTimeImmutable|string|null $startDate = null,
    \DateTime|\DateTimeImmutable|string|null $endDate = null,
    ?string $timezone = null,
)
```

### Parameters
- **$rrule** (array<string, string> | string | null) - Optional - RRULE string (e.g. 'FREQ=MONTHLY;COUNT=5') or an associative array of RRULE parts (e.g. ['FREQ' => 'MONTHLY', 'COUNT' => '5']). null/''/'0' build an empty rule.
- **$startDate** (\DateTime | \DateTimeImmutable | string | null) - Optional - First occurrence (DTSTART). Strings are parsed with new \DateTime($startDate, ...) in the rule timezone.
- **$endDate** (\DateTime | \DateTimeImmutable | string | null) - Optional - Last possible occurrence (DTEND).
- **$timezone** (?string) - Optional - IANA timezone name. When empty: taken from $startDate's timezone if it is a \DateTimeInterface, otherwise from date_default_timezone_get().

### Throws
- **Recurr\Exception\InvalidRRule** - when $rrule is a non-empty string/array that fails parsing or validation.

### Example
```php
use Recurr\Rule;

// From an RRULE string with a timezone
$rule = new Rule(
    'FREQ=MONTHLY;COUNT=5',
    new \DateTime('2013-06-12 20:00:00', new \DateTimeZone('America/New_York')),
    null,
    'America/New_York',
);

// From an array of parts (FREQ is required)
$rule = new Rule(['FREQ' => 'DAILY', 'INTERVAL' => '2'], '2013-06-12 20:00:00');

// Error handling: malformed rules throw InvalidRRule
try {
    new Rule('COUNT=5'); // no FREQ part
} catch (\Recurr\Exception\InvalidRRule $e) {
    echo $e->getMessage(); // "FREQ is required"
}
```
```

--------------------------------

### Initialize ArrayTransformerConfig

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/array-transformer-config.md

Demonstrates how to instantiate the configuration object and apply settings before passing it to the ArrayTransformer constructor.

```php
$config = new ArrayTransformerConfig();

$config->setVirtualLimit(1000);
$config->enableLastDayOfMonthFix();

$transformer = new ArrayTransformer($config);
```

--------------------------------

### setFreq / getFreq / getFreqAsText

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/rule.md

Sets or gets the frequency of the rule. Strings must be one of YEARLY, MONTHLY, WEEKLY, DAILY, HOURLY, MINUTELY, SECONDLY; integers must be 0-6.

```APIDOC
## setFreq(int|string $freq): static / getFreq(): ?int / getFreqAsText(): ?string

### Description
Sets or gets the frequency of the rule. Strings must be one of YEARLY, MONTHLY, WEEKLY, DAILY, HOURLY, MINUTELY, SECONDLY; integers must be 0-6.

### Method
setFreq / getFreq / getFreqAsText

### Signature
public function setFreq(int|string $freq): static
public function getFreq(): ?int
public function getFreqAsText(): ?string

### Parameters
#### setFreq
- **$freq** (int|string) - Required - The frequency keyword or integer (0-6).

#### getFreq
No parameters.

#### getFreqAsText
No parameters.

### Returns
- **setFreq**: static - Returns the current Rule instance for chaining.
- **getFreq**: ?int - The internal integer representation (0-6) or null.
- **getFreqAsText**: ?string - The frequency keyword (e.g., 'MONTHLY') or null when unset.

### Throws
- **InvalidArgument** - If the string is not one of YEARLY, MONTHLY, WEEKLY, DAILY, HOURLY, MINUTELY, SECONDLY, or if the integer is out of range (0-6).

### Source
- setFreq: src/Recurr/Rule.php:664
- getFreq: src/Recurr/Rule.php:688
- getFreqAsText: src/Recurr/Rule.php:693
```

--------------------------------

### setByDay(?array $byDay) / getByDay(): ?array

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/rule.md

Sets or gets the BYDAY part. Valid values are MO, TU, WE, TH, FR, SA, SU, optionally prefixed with +/-n for positional values. Throws InvalidRRule for invalid combinations.

```APIDOC
## setByDay(?array $byDay) / getByDay(): ?array

### Description
Sets or gets the BYDAY part. Valid values are MO, TU, WE, TH, FR, SA, SU, optionally prefixed with +/-n for positional values. Throws InvalidRRule for invalid combinations.

### Method
setByDay / getByDay

### Parameters
#### setByDay
- **$byDay** (?array) - Required - Array of day codes. Passing null clears the part.

### Return Value
- setByDay: static
- getByDay: ?array

### Exceptions
- InvalidRRule('BYDAY must contain at least one value')
- InvalidRRule('Cannot mix positional (e.g. -1MO) and non-positional (e.g. MO) BYDAY values')
- InvalidRRule('Positional BYDAY (e.g. -1MO) only works with MONTHLY and YEARLY frequencies')

### Example
```php
$rule = (new Rule())
    ->setFreq('MONTHLY')
    ->setByDay(['+1MO', '-1FR']); // first Monday and last Friday of each month
```

### Source
src/Recurr/Rule.php:909 / getter :948
```

--------------------------------

### Recurr\Recurrence::getEnd

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/recurrence.md

Returns the end datetime of the occurrence. For occurrences generated by ArrayTransformer, this is start + durationInterval, where durationInterval is the diff between the rule's DTSTART and DTEND; if the rule had no end date the end equals the start.

```APIDOC
## Recurr\Recurrence::getEnd

### Description
Returns the end datetime of the occurrence. For occurrences generated by ArrayTransformer, this is start + durationInterval, where durationInterval is the diff between the rule's DTSTART and DTEND; if the rule had no end date the end equals the start.

### Method
Method

### Signature
```php
public function getEnd(): \DateTime|\DateTimeImmutable
```

### Returns
- **\DateTime|\DateTimeImmutable** - The end datetime of the occurrence.
```

--------------------------------

### setExDates(?array $exDates): static / getExDates(): ?array

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/rule.md

Sets or gets an array of dates to exclude from the generated set. Dates can be provided as strings or DateExclusion objects. Same parsing semantics as setRDates but produces DateExclusion objects. Passing null resets to null.

```APIDOC
## setExDates(?array $exDates): static

### Description
Sets an array of dates to exclude from the generated set. Dates can be provided as strings or DateExclusion objects. Same parsing semantics as setRDates but produces DateExclusion objects. Passing null resets to null.

### Method
setExDates

### Parameters
- **$exDates** (array|null) - Required - An array of dates to exclude. Each element can be a string or a DateExclusion object.

### Return Value
- static - Returns the current Rule instance for method chaining.

### Source
`src/Recurr/Rule.php:1214`

## getExDates(): ?array

### Description
Returns the array of dates to exclude from the generated set. The return value is an array of DateExclusion objects, or null if set to null.

### Method
getExDates

### Return Value
- ?array - An array of DateExclusion objects, or null if set to null.

### Source
`src/Recurr/Rule.php:1247`

### Example
```php
$rule = (new Rule())
    ->setFreq('DAILY')
    ->setRDates(['2013-06-15T12:00:00'])
    ->setExDates(['2013-06-14']);
```
```

--------------------------------

### Configure ArrayTransformer with ArrayTransformerConfig

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/configuration.md

Demonstrates how to instantiate and configure an ArrayTransformerConfig object and apply it to an ArrayTransformer instance.

```php
use Recurr\Transformer\ArrayTransformer;
use Recurr\Transformer\ArrayTransformerConfig;

$config = new ArrayTransformerConfig();
$config->setVirtualLimit(2000);
$config->enableLastDayOfMonthFix();

$transformer = new ArrayTransformer($config);
// or: $transformer->setConfig($config);
```

--------------------------------

### Using constraints and handling exceptions

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/array-transformer.md

Demonstrates applying a BeforeConstraint to a monthly rule and catching InvalidWeekday exceptions for malformed rules.

```php
use Recurr\Transformer\ArrayTransformer;
use Recurr\Transformer\Constraint\BeforeConstraint;

// With a constraint that also stops the transformer once passed
$rule = new Rule('FREQ=MONTHLY;COUNT=5', new \DateTime('2014-06-17 04:00:00'));
$collection = (new ArrayTransformer())->transform(
    $rule,
    new BeforeConstraint(new \DateTime('2014-08-01 00:00:00'))
);

// Error handling: an invalid BYDAY raises InvalidWeekday
try {
    (new ArrayTransformer())->transform(new Rule('FREQ=DAILY;BYDAY=XX', new \DateTime()));
} catch (\Recurr\Exception\InvalidWeekday $e) {
    echo 'invalid weekday: '.$e->getMessage();
}
```

--------------------------------

### startsBetween method signature

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/recurrence-collection.md

Returns recurrences whose getStart() falls inside the specified range.

```php
public function startsBetween(
    \DateTime|\DateTimeImmutable $after,
    \DateTime|\DateTimeImmutable $before,
    bool $inc = false,
): RecurrenceCollection
```

--------------------------------

### setEndDate / getEndDate

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/rule.md

Sets or gets the last possible occurrence in the set (DTEND). Optional.

```APIDOC
## setEndDate(\DateTime|\DateTimeImmutable|null $endDate): static / getEndDate(): \DateTime|\DateTimeImmutable|null

### Description
Sets or gets the last possible occurrence in the set (DTEND). Optional.

### Method
setEndDate / getEndDate

### Signature
public function setEndDate(\DateTime|\DateTimeImmutable|null $endDate): static
public function getEndDate(): \DateTime|\DateTimeImmutable|null

### Parameters
#### setEndDate
- **$endDate** (\DateTime|\DateTimeImmutable|null) - Required - The end date or null to clear.

#### getEndDate
No parameters.

### Returns
- **setEndDate**: static - Returns the current Rule instance for chaining.
- **getEndDate**: \DateTime|\DateTimeImmutable|null - The end date or null if not set.

### Source
- setEndDate: src/Recurr/Rule.php:631
- getEndDate: src/Recurr/Rule.php:638
```

--------------------------------

### Setting and retrieving frequency values

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/frequency.md

Demonstrates how to set the frequency of a Rule using either the Frequency class constants or string literals, and how to retrieve the integer or text representation.

```php
use Recurr\Frequency;
use Recurr\Rule;

$rule = new Rule('FREQ=WEEKLY', new \DateTime('2013-06-12 20:00:00'));

// Equivalent forms
$rule->setFreq(Frequency::WEEKLY);
$rule->setFreq('WEEKLY');

$rule->getFreq();       // 2
$rule->getFreqAsText(); // 'WEEKLY'

// Granularity comparisons used by examples in this reference
if ($rule->getFreq() >= Frequency::HOURLY) {
    // sub-daily stepping
}
```

--------------------------------

### DateUtil basic date and modulo operations

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/date-util.md

Demonstrates the use of pymod for Python-style modulo, leap year checks, year length calculation, and retrieving the day of the week as text.

```php
use Recurr\DateUtil;

echo DateUtil::pymod(-1, 7);  // 6
echo DateUtil::pymod(8, 7);   // 1
echo DateUtil::isLeapYear(2024);   // true
echo DateUtil::isLeapYear(1900);   // false
echo DateUtil::getYearLength(new \DateTime('2023-01-01')); // 365
echo DateUtil::getDayOfWeekAsText(new \DateTime('2023-06-12')); // "MO"
```

--------------------------------

### Recurrence Index Methods

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/recurrence.md

Methods to get or set the 1-based position of the occurrence in the transformed set.

```php
public function getIndex(): int
public function setIndex(int $index): void
```

--------------------------------

### Recurrence getEnd Method

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/recurrence.md

Retrieves the end datetime. For occurrences generated by ArrayTransformer, this is calculated as start + durationInterval.

```php
public function getEnd(): \DateTime|\DateTimeImmutable
```

--------------------------------

### Configure TextTransformer with Translator

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/configuration.md

Shows how to initialize a TextTransformer with a specific locale using the Translator class to generate human-readable rule descriptions.

```php
use Recurr\Rule;
use Recurr\Transformer\TextTransformer;
use Recurr\Transformer\Translator;

$rule = new Rule('FREQ=YEARLY;INTERVAL=2;COUNT=3;', new \DateTime());
$text = new TextTransformer(new Translator('de'));
echo $text->transform($rule);
```

--------------------------------

### Define enableLastDayOfMonthFix and disableLastDayOfMonthFix methods

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/array-transformer-config.md

Method signatures for toggling the month-end behavior fix.

```php
public function enableLastDayOfMonthFix(): void
public function disableLastDayOfMonthFix(): void
```

--------------------------------

### Translator::__construct(string $locale = 'en', string $fallbackLocale = 'en')

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/text-transformer.md

Constructor that initializes the translator with a locale and fallback locale. It loads the fallback locale first, then overlays the requested locale if different.

```APIDOC
## Translator::__construct(string $locale = 'en', string $fallbackLocale = 'en')

### Description
Initializes the Translator with a locale and a fallback locale. Loads the fallback locale first so shared keys are inherited, then overlays the requested locale when different.

### Method
Constructor

### Signature
```php
public function __construct(string $locale = 'en', string $fallbackLocale = 'en')
```

### Parameters
- **$locale** (string) - Optional - The primary locale to load. Defaults to 'en'.
- **$fallbackLocale** (string) - Optional - The fallback locale to load first. Defaults to 'en'.

### Notes
Built-in locale files (13): da, de, el, en, es, eu, fr, it, nl, no, pt-br, sv, tr — see translations/.
```

--------------------------------

### Get ByDay Transformed to Weekdays

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/rule.md

Deprecated method signature for retrieving BYDAY values as Weekday objects.

```php
/**
 * @return Weekday[]
 *
 * @deprecated Since v6. Use getByDayAsWeekdays
 */
public function getByDayTransformedToWeekdays(): array
```

--------------------------------

### Transforming with custom locale and fallback

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/text-transformer.md

Demonstrates using a German translator and handling unsupported frequencies which return a fallback message instead of throwing an exception.

```php
use Recurr\Rule;
use Recurr\Transformer\TextTransformer;
use Recurr\Transformer\Translator;

// German output
$rule = new Rule('FREQ=MONTHLY;BYDAY=MO;COUNT=5', new \DateTime('2014-06-17 04:00:00'));
$text = (new TextTransformer(new Translator('de')))->transform($rule);

// Unsupported frequency falls back to a message, not an exception
$rule = new Rule('FREQ=SECONDLY;COUNT=5', new \DateTime('2014-06-17 04:00:00'));
echo (new TextTransformer())->transform($rule);
// "Unable to fully convert this rrule to text."
```

--------------------------------

### Recurr\Recurrence::__construct

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/recurrence.md

Constructor for the Recurr\Recurrence class. Initializes a new recurrence with optional start and end datetimes and an index.

```APIDOC
## Recurr\Recurrence::__construct

### Description
Creates a new Recurrence instance. The start and end datetimes are optional and default to null, leaving the properties unset. The index is a promoted property defaulting to 0.

### Method
Constructor

### Signature
```php
public function __construct(
    \DateTime|\DateTimeImmutable|null $start = null,
    \DateTime|\DateTimeImmutable|null $end = null,
    protected int $index = 0,
)
```

### Parameters
- **$start** (\DateTime|\DateTimeImmutable|null) - Optional - Occurrence start datetime. null leaves the property unset.
- **$end** (\DateTime|\DateTimeImmutable|null) - Optional - Occurrence end datetime. null leaves the property unset.
- **$index** (int) - Optional - Positional index (promoted property). Defaults to 0.

### Example
```php
$recurrence = new Recurrence(
    new \DateTime('2013-06-12 20:00:00'),
    new \DateTime('2013-06-12 21:00:00'),
    1,
);
```
```

--------------------------------

### Recurr\Rule constructor

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/configuration.md

Creates a new Rule instance with optional RRULE source, start/end dates, and timezone.

```APIDOC
## Recurr\Rule constructor

### Description
Creates a new Rule instance with optional RRULE source, start/end dates, and timezone.

### Method
`__construct($rrule = null, $startDate = null, $endDate = null, $timezone = null)`

### Parameters
- **$rrule** (array<string,string> | string | null) - Optional - RRULE string or parts array.
- **$startDate** (\DateTime | \DateTimeImmutable | string | null) - Optional - DTSTART; string forms are parsed in $timezone.
- **$endDate** (\DateTime | \DateTimeImmutable | string | null) - Optional - DTEND.
- **$timezone** (?string) - Optional - IANA timezone used for parsing and serialization. Defaults to resolved timezone.

### Timezone Resolution Order
1. Explicit $timezone argument when non-empty.
2. $startDate->getTimezone()->getName() when $startDate is a \DateTimeInterface.
3. static::$defaultTimezone captured once from date_default_timezone_get().
```

--------------------------------

### setStartDate / getStartDate

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/rule.md

Declares the first occurrence. The includeInString parameter controls whether getString() emits this date as DTSTART.

```APIDOC
## setStartDate(\DateTime|\DateTimeImmutable $startDate, ?bool $includeInString = null): static / getStartDate(): \DateTime|\DateTimeImmutable|null

### Description
Declares the first occurrence. The includeInString parameter controls whether getString() emits this date as DTSTART.

### Method
setStartDate / getStartDate

### Signature
public function setStartDate(\DateTime|\DateTimeImmutable $startDate, ?bool $includeInString = null): static
public function getStartDate(): \DateTime|\DateTimeImmutable|null

### Parameters
#### setStartDate
- **$startDate** (\DateTime|\DateTimeImmutable) - Required - The first occurrence date.
- **$includeInString** (?bool) - Optional - When not null, controls whether getString() emits this date as DTSTART; passing true sets isStartDateFromDtstart.

#### getStartDate
No parameters.

### Returns
- **setStartDate**: static - Returns the current Rule instance for chaining.
- **getStartDate**: \DateTime|\DateTimeImmutable|null - The start date or null if not set.

### Source
- setStartDate: src/Recurr/Rule.php:612
- getStartDate: src/Recurr/Rule.php:623
```

--------------------------------

### RecurrenceCollection::startsAfter

Source: https://github.com/simshaun/recurr/blob/master/README.md

Filters recurrences to those that start after the given date. The $inc parameter determines whether recurrences equal to the boundary are included.

```APIDOC
## startsAfter(\DateTime $after, $inc = false)

### Description
Filters the collection to recurrences whose start date is after $after. If $inc is true, recurrences equal to $after are included.

### Method
startsAfter

### Parameters
- **$after** (\DateTime) - Required - The lower bound of the start date range.
- **$inc** (bool) - Optional - Whether to include recurrences equal to the boundary. Defaults to false.
```

--------------------------------

### RecurrenceCollection::startsBefore

Source: https://github.com/simshaun/recurr/blob/master/README.md

Filters recurrences to those that start before the given date. The $inc parameter determines whether recurrences equal to the boundary are included.

```APIDOC
## startsBefore(\DateTime $before, $inc = false)

### Description
Filters the collection to recurrences whose start date is before $before. If $inc is true, recurrences equal to $before are included.

### Method
startsBefore

### Parameters
- **$before** (\DateTime) - Required - The upper bound of the start date range.
- **$inc** (bool) - Optional - Whether to include recurrences equal to the boundary. Defaults to false.
```

--------------------------------

### RecurrenceCollection::startsBetween

Source: https://github.com/simshaun/recurr/blob/master/README.md

Filters recurrences to those that start between the given dates. The $inc parameter determines whether recurrences equal to the boundaries are included.

```APIDOC
## startsBetween(\DateTime $after, \DateTime $before, $inc = false)

### Description
Filters the collection to recurrences whose start date is between $after and $before. If $inc is true, recurrences equal to $after or $before are included.

### Method
startsBetween

### Parameters
- **$after** (\DateTime) - Required - The lower bound of the start date range.
- **$before** (\DateTime) - Required - The upper bound of the start date range.
- **$inc** (bool) - Optional - Whether to include recurrences equal to the boundaries. Defaults to false.

### Example
2014-06-01 startsBetween(2014-06-01, 2014-06-20) // false
2014-06-01 startsBetween(2014-06-01, 2014-06-20, true) // true
```

--------------------------------

### BetweenConstraint Constructor

Source: https://github.com/simshaun/recurr/blob/master/_autodocs/api-reference/constraints.md

Initializes the constraint with lower and upper bounds, with an optional inclusive comparison flag.

```php
/**
 * @param bool $inc If comparison should be inclusive. (Include date if it equals $before or $after)
 */
public function __construct(
    protected \DateTimeInterface $after,
    protected \DateTimeInterface $before,
    protected bool $inc = false,
) {}
```
Tokens:
Raw