PHPackages                             davidrnk/yii2-recurring-date - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. davidrnk/yii2-recurring-date

ActiveYii2-extension[Utility & Helpers](/categories/utility)

davidrnk/yii2-recurring-date
============================

A Yii2 extension that allows users to define and handle recurring date intervals for renewals, expirations and scheduling.

v1.0.3(6mo ago)220BSD-3-ClausePHPPHP >=7.4

Since Nov 26Pushed 6mo agoCompare

[ Source](https://github.com/davidrnk/yii2-recurring-date)[ Packagist](https://packagist.org/packages/davidrnk/yii2-recurring-date)[ RSS](/packages/davidrnk-yii2-recurring-date/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (4)Dependencies (5)Versions (6)Used By (0)

yii2-recurring-date
===================

[](#yii2-recurring-date)

A Yii2 extension/widget that provides a simple and intuitive interface to define and manage recurring date patterns. It is designed to simplify the configuration of renewals, expirations, and periodic events, with clean integration into Yii2 forms and internationalization support.

Main Features
-------------

[](#main-features)

- Visual interface to configure recurring periods: no expiration, interval (days/months/years), monthly (day of the month), yearly (day + month), and specific date.
- Handling of edge cases (e.g., days 29/30/31 and February 29) with configurable adjustment policy (`previous` | `next`).
- Persistence of the recurrence scheme in a hidden field as JSON ready to be sent to the server.
- Backend function to calculate the next expiration date based on a base date and the configuration.
- Localization (i18n) with translations in English and Spanish.

Installation
------------

[](#installation)

Install the extension with Composer:

```
composer require davidrnk/yii2-recurring-date
```

Register the asset (if the widget does not do it automatically) and add the widget to your views/forms according to the usage examples.

Usage
-----

[](#usage)

The extension can be used with Yii2 models (ActiveForm) or independently.

Usage with model (ActiveForm):

```
use davidrnk\RecurringDate\Widget\RecurringDate;

echo $form->field($model, 'recurrence_config')->widget(RecurringDate::class, [
    // options
    'options' => ['class' => 'form-control my-custom-class'],
    'labels' => [
        'title_modal' => 'Configure recurrence',
        // you can override other labels
    ],
]);
```

Usage without model:

```
echo davidrnk\RecurringDate\Widget\RecurringDate::widget([
    'name' => 'recurrence',
    'value' => json_encode(['type' => 'monthly', 'day' => 1]),
    'options' => ['class' => 'form-control'],
]);
```

The widget renders a read-only text control with a button to open a modal where recurrence is configured. The resulting JSON is saved in a hidden field (`input.hidden`) and is the content you should store in the database.

JSON Format (persisted)
-----------------------

[](#json-format-persisted)

The widget persists the configuration in JSON format with the following main structure (examples):

- No expiration

```
{"type": "no_expiration"}
```

- Interval

```
{ "type": "interval", "value": 10, "unit": "days" }
```

- Monthly (day of the month) + optional adjustment

```
{ "type": "monthly", "day": 31, "adjust": "previous" }
```

- Yearly (day + month) + optional adjustment

```
{ "type": "yearly", "day": 29, "month": 2, "adjust": "previous" }
```

- Specific date

```
{ "type": "specific_date", "date": "2025-12-31" }
```

Relevant keys:

- `type`: one of `no_expiration`, `interval`, `monthly`, `yearly`, `specific_date`.
- `value`, `unit`: used by `interval` (unit: `days|months|years`).
- `day`: day of the month (1-31).
- `month`: month (1-12).
- `date`: ISO date for `specific_date`.
- `adjust`: policy when the day does not exist in the period (values: `previous` — adjust to the last valid day of the month, or `next` — move to the next day).

Calculation of the Next Expiration Date
---------------------------------------

[](#calculation-of-the-next-expiration-date)

In the backend, the library provides a function to calculate the resulting date based on a base date and the JSON configuration. In the code the function is called:

```
use davidrnk\RecurringDate\Core\RecurringDateEngine;

$nextDueDate = RecurringDateEngine::calculateExpiration($startDate, $configArray);
// returns DateTime instance or null if configuration is invalid
```

In the documentation and examples of this README, we refer to this date as `nextDueDate`. If `calculateExpiration` returns `null`, the combination of parameters is invalid or could not be calculated.

Quick example:

```
$start = new \DateTime('2025-01-31');
$cfg = ['type' => 'monthly', 'day' => 31, 'adjust' => 'previous'];
$next = RecurringDateEngine::calculateExpiration($start, $cfg);
echo $next ? $next->format('Y-m-d') : 'invalid';
```

Configuration and Customization
-------------------------------

[](#configuration-and-customization)

The widget exposes several ways to adjust its visual and textual behavior:

- `options` (array): HTML attributes for the visible text field (e.g., `class`, `style`, `placeholder`).
- `labels` (array): you can override texts and labels used in the modal. Examples of keys you can customize:
    - `title_modal`, `type`, `configure`, `preview`, `save`, `cancel`, `quantity`, `unit`, `month_day`, `adjust`, `adjust_previous`, `adjust_next`, etc.
- Translations: the extension includes files in `src/messages/en` and `src/messages/es`. The displayed texts are also sent to JavaScript for preview.

Example of label customization:

```
echo $form->field($model, 'recurrence_config')->widget(RecurringDate::class, [
    'labels' => [
        'title_modal' => 'Schedule repetition',
        'adjust_previous' => 'Adjust to the last day of the month',
    ],
]);
```

Validations and UX Behavior
---------------------------

[](#validations-and-ux-behavior)

- The widget validates on the client side combinations that are clearly invalid (e.g., 31 in months with 30 days, February 31) and blocks saving when the selection is fatal.
- For non-fatal cases (e.g., day >= 29 in monthly or February 29 in yearly), it shows a warning and allows the user to select the `adjust` policy.
- The `adjust` value is persisted in JSON and is considered by `RecurringDateEngine::calculateExpiration`.

Internationalization (i18n)
---------------------------

[](#internationalization-i18n)

The default language of the extension is English. Translations are included in `src/messages/en` and `src/messages/es`. Strings used in views and JavaScript translations are defined and loaded from `RecurringDate::getJSTranslations()`.

If you need to add another language, add a file in `src/messages/XX/davidrnk.recurring.php` with the required keys.

Tests
-----

[](#tests)

Unit tests for PHP are included for the calculation logic (`tests/RecurringDateEngineTest.php`) and should be executed with:

```
vendor/bin/phpunit tests/RecurringDateEngineTest.php
```

Best Practices and Notes
------------------------

[](#best-practices-and-notes)

- Save the persisted JSON directly in a text field in the database (e.g., `recurrence_config`), and use `RecurringDateEngine::calculateExpiration` to obtain the next expiration date when needed.
- Decide and document the default `adjust` policy for your domain (by default the extension uses `previous` — clamp to the last valid day). This avoids surprises when calculating next dates.
- Review the locale configuration (`Yii::$app->language`) to ensure the UI displays the desired translations.

Contributing
------------

[](#contributing)

Pull requests and issues are welcome. For major changes, first open an issue describing the proposed change.

License
-------

[](#license)

BSD-3-Clause — see `LICENSE` file.

###  Health Score

32

—

LowBetter than 69% of packages

Maintenance66

Regular maintenance activity

Popularity9

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity39

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~4 days

Total

4

Last Release

199d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/2d0eb16c8a0c992470bc0c7114f0289eead53c37d0005aec2237586fdd648538?d=identicon)[davidrnk](/maintainers/davidrnk)

---

Top Contributors

[![davidrnk](https://avatars.githubusercontent.com/u/41210711?v=4)](https://github.com/davidrnk "davidrnk (12 commits)")

---

Tags

daterecurringrecurrenceyii2

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/davidrnk-yii2-recurring-date/health.svg)

```
[![Health](https://phpackages.com/badges/davidrnk-yii2-recurring-date/health.svg)](https://phpackages.com/packages/davidrnk-yii2-recurring-date)
```

###  Alternatives

[rlanvin/php-rrule

Lightweight and fast recurrence rules for PHP (RFC 5545)

70011.4M54](/packages/rlanvin-php-rrule)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)