{"id":15033531,"url":"https://github.com/simshaun/recurr","last_synced_at":"2025-05-12T13:32:35.808Z","repository":{"id":453227,"uuid":"10655361","full_name":"simshaun/recurr","owner":"simshaun","description":"PHP library for working with recurrence rules (RRULE); meant to help with recurring calendar events.","archived":false,"fork":false,"pushed_at":"2024-12-12T15:41:10.000Z","size":356,"stargazers_count":1522,"open_issues_count":53,"forks_count":145,"subscribers_count":35,"default_branch":"master","last_synced_at":"2025-04-23T17:09:19.725Z","etag":null,"topics":["php","recurrence","recurrence-rules","recurring-events"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simshaun.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-06-13T00:19:10.000Z","updated_at":"2025-03-18T12:54:48.000Z","dependencies_parsed_at":"2024-09-30T20:00:37.634Z","dependency_job_id":"e07d60ee-2a65-4a4a-bedf-8c05160d33b9","html_url":"https://github.com/simshaun/recurr","commit_stats":{"total_commits":154,"total_committers":42,"mean_commits":"3.6666666666666665","dds":0.7207792207792207,"last_synced_commit":"5e736ab1679aeff0a52d683eecce91cb4f830da3"},"previous_names":[],"tags_count":67,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simshaun%2Frecurr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simshaun%2Frecurr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simshaun%2Frecurr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simshaun%2Frecurr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simshaun","download_url":"https://codeload.github.com/simshaun/recurr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253748007,"owners_count":21957848,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["php","recurrence","recurrence-rules","recurring-events"],"created_at":"2024-09-24T20:21:35.674Z","updated_at":"2025-05-12T13:32:35.752Z","avatar_url":"https://github.com/simshaun.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Recurr \n\n[![tests](https://github.com/simshaun/recurr/workflows/tests/badge.svg)](https://github.com/simshaun/recurr/actions)\n[![Latest Stable Version](https://poser.pugx.org/simshaun/recurr/v/stable.svg)](https://packagist.org/packages/simshaun/recurr) \n[![Total Downloads](https://poser.pugx.org/simshaun/recurr/downloads.svg)](https://packagist.org/packages/simshaun/recurr) \n[![Latest Unstable Version](https://poser.pugx.org/simshaun/recurr/v/unstable.svg)](https://packagist.org/packages/simshaun/recurr) \n[![License](https://poser.pugx.org/simshaun/recurr/license.svg)](https://packagist.org/packages/simshaun/recurr)\n\nRecurr is a PHP library for working with recurrence rules ([RRULE](https://tools.ietf.org/html/rfc5545)) and converting them in to DateTime objects.\n\nRecurr was developed as a precursor for a calendar with recurring events, and is heavily inspired by [rrule.js](https://github.com/jkbr/rrule).\n\nInstalling Recurr\n------------\n\nThe recommended way to install Recurr is through [Composer](http://getcomposer.org).\n\n```bash\ncomposer require simshaun/recurr\n```\n\nUsing Recurr \n-----------\n\n### Creating RRULE rule objects ###\n\nYou can create a new Rule object by passing the ([RRULE](https://tools.ietf.org/html/rfc5545)) string or an array with the rule parts, the start date, end date (optional) and timezone.\n\n```php\n$timezone    = 'America/New_York';\n$startDate   = new \\DateTime('2013-06-12 20:00:00', new \\DateTimeZone($timezone));\n$endDate     = new \\DateTime('2013-06-14 20:00:00', new \\DateTimeZone($timezone)); // Optional\n$rule        = new \\Recurr\\Rule('FREQ=MONTHLY;COUNT=5', $startDate, $endDate, $timezone);\n```\n\nYou can also use chained methods to build your rule programmatically and get the resulting RRULE.\n\n```php\n$rule = (new \\Recurr\\Rule)\n    -\u003esetStartDate($startDate)\n    -\u003esetTimezone($timezone)\n    -\u003esetFreq('DAILY')\n    -\u003esetByDay(['MO', 'TU'])\n    -\u003esetUntil(new \\DateTime('2017-12-31'))\n;\n\necho $rule-\u003egetString(); //FREQ=DAILY;UNTIL=20171231T000000;BYDAY=MO,TU\n```\n\n### RRULE to DateTime objects ###\n\n```php\n$transformer = new \\Recurr\\Transformer\\ArrayTransformer();\n\nprint_r($transformer-\u003etransform($rule));\n```\n\n1. `$transformer-\u003etransform(...)` returns a `RecurrenceCollection` of `Recurrence` objects.\n2. Each `Recurrence` has `getStart()` and `getEnd()` methods that return a `\\DateTime` object.\n3. If the transformed `Rule` lacks an end date, `getEnd()` will return a `\\DateTime` object equal to that of `getStart()`.\n\n\u003e Note: The transformer has a \"virtual\" limit (default 732) on the number of objects it generates.\n\u003e This prevents the script from crashing on an infinitely recurring rule.\n\u003e You can change the virtual limit with an `ArrayTransformerConfig` object that you pass to `ArrayTransformer`.\n\n### Transformation Constraints ###\n\nConstraints are used by the ArrayTransformer to allow or prevent certain dates from being added to a `RecurrenceCollection`. Recurr provides the following constraints:\n\n- `AfterConstraint(\\DateTime $after, $inc = false)`\n- `BeforeConstraint(\\DateTime $before, $inc = false)`\n- `BetweenConstraint(\\DateTime $after, \\DateTime $before, $inc = false)`\n\n`$inc` defines what happens if `$after` or `$before` are themselves recurrences. If `$inc = true`, they will be included in the collection. For example,\n\n```php\n$startDate   = new \\DateTime('2014-06-17 04:00:00');\n$rule        = new \\Recurr\\Rule('FREQ=MONTHLY;COUNT=5', $startDate);\n$transformer = new \\Recurr\\Transformer\\ArrayTransformer();\n\n$constraint = new \\Recurr\\Transformer\\Constraint\\BeforeConstraint(new \\DateTime('2014-08-01 00:00:00'));\nprint_r($transformer-\u003etransform($rule, $constraint));\n```\n\n\u003e Note: If building your own constraint, it is important to know that dates which do not meet the constraint's requirements do **not** count toward the transformer's virtual limit. If you manually set your constraint's `$stopsTransformer` property to `false`, the transformer *might* crash via an infinite loop. See the `BetweenConstraint` for an example on how to prevent that.\n\n### Post-Transformation `RecurrenceCollection` Filters ###\n\n`RecurrenceCollection` provides the following chainable helper methods to filter out recurrences:\n\n- `startsBetween(\\DateTime $after, \\DateTime $before, $inc = false)`\n- `startsBefore(\\DateTime $before, $inc = false)`\n- `startsAfter(\\DateTime $after, $inc = false)`\n- `endsBetween(\\DateTime $after, \\DateTime $before, $inc = false)`\n- `endsBefore(\\DateTime $before, $inc = false)`\n- `endsAfter(\\DateTime $after, $inc = false)`\n\n`$inc` defines what happens if `$after` or `$before` are themselves recurrences. If `$inc = true`, they will be included in the filtered collection. For example,\n\n    pseudo...\n    2014-06-01 startsBetween(2014-06-01, 2014-06-20) // false\n    2014-06-01 startsBetween(2014-06-01, 2014-06-20, true) // true\n\n\u003e Note: `RecurrenceCollection` extends the Doctrine project's [ArrayCollection](https://github.com/doctrine/collections/blob/master/lib/Doctrine/Common/Collections/ArrayCollection.php) class.\n\nRRULE to Text\n--------------------------\n\nRecurr supports transforming some recurrence rules into human readable text.\nThis feature is still in beta and only supports yearly, monthly, weekly, and daily frequencies.\n\n```php\n$rule = new Rule('FREQ=YEARLY;INTERVAL=2;COUNT=3;', new \\DateTime());\n\n$textTransformer = new TextTransformer();\necho $textTransformer-\u003etransform($rule);\n```\n\nIf you need more than English you can pass in a translator with one of the\nsupported locales *(see translations folder)*.\n\n```php\n$rule = new Rule('FREQ=YEARLY;INTERVAL=2;COUNT=3;', new \\DateTime());\n\n$textTransformer = new TextTransformer(\n    new \\Recurr\\Transformer\\Translator('de')\n);\necho $textTransformer-\u003etransform($rule);\n```\n\nWarnings\n---------------\n\n- **Monthly recurring rules **\n  By default, if your start date is on the 29th, 30th, or 31st, Recurr will skip following months that don't have at least that many days.\n  *(e.g. Jan 31 + 1 month = March)* \n\nThis behavior is configurable:\n\n```php\n$timezone    = 'America/New_York';\n$startDate   = new \\DateTime('2013-01-31 20:00:00', new \\DateTimeZone($timezone));\n$rule        = new \\Recurr\\Rule('FREQ=MONTHLY;COUNT=5', $startDate, null, $timezone);\n$transformer = new \\Recurr\\Transformer\\ArrayTransformer();\n\n$transformerConfig = new \\Recurr\\Transformer\\ArrayTransformerConfig();\n$transformerConfig-\u003eenableLastDayOfMonthFix();\n$transformer-\u003esetConfig($transformerConfig);\n\nprint_r($transformer-\u003etransform($rule));\n// 2013-01-31, 2013-02-28, 2013-03-31, 2013-04-30, 2013-05-31\n```\n\n\nContribute\n----------\n\nFeel free to comment or make pull requests. Please include tests with PRs.\n\n\nLicense\n-------\n\nRecurr is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimshaun%2Frecurr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimshaun%2Frecurr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimshaun%2Frecurr/lists"}