Recurring Dates Field
Provides a recurring/repeating dates field type that supports RFC 5545 RRULE format for defining complex recurring date patterns.
date_recur
Install
composer require 'drupal/date_recur:^3.8'
Overview
The Recurring Dates Field module provides a comprehensive solution for handling recurring dates in Drupal. It extends the core datetime_range field type to support RFC 5545 iCalendar recurrence rules (RRULE), enabling users to define complex repeating date patterns such as daily, weekly, monthly, or yearly occurrences with various constraints.
The module uses the rlanvin/php-rrule library to parse and generate occurrences from RRULE strings. It stores occurrences in dedicated database tables for efficient Views integration and querying. A pluggable interpreter system allows administrators to configure how recurring rules are converted to human-readable text for display.
Key capabilities include timezone-aware date handling, support for infinite and finite recurrence patterns, occurrence caching with configurable precreation intervals, and comprehensive Views integration for filtering and displaying recurring date content.
Features
- Provides a date_recur field type that extends datetime_range with RRULE support for defining recurring date patterns
- Full RFC 5545 iCalendar recurrence rule support including FREQ, INTERVAL, COUNT, UNTIL, BYDAY, BYMONTH, BYMONTHDAY, BYYEARDAY, BYWEEKNO, BYHOUR, BYMINUTE, BYSECOND, BYSETPOS, WKST, and EXDATE
- Automatic occurrence caching in dedicated database tables for efficient querying and Views integration
- Configurable precreation interval for infinite recurring dates (1-5 years ahead)
- Pluggable interpreter system for converting RRULE strings to human-readable text in multiple languages (de, en, es, fi, fr, it, nl)
- Basic widget with start/end date pickers, timezone selector, and RRULE textarea input
- Basic formatter displaying dates, human-readable interpretation, and configurable number of upcoming occurrences
- Granular frequency and part configuration allowing administrators to restrict which RRULE features users can employ
- Views integration with occurrence filter, relationship to occurrence table, and date field plugins
- Event system dispatching events on field value save, entity delete, and revision delete for custom processing
- Timezone-aware storage and display with proper UTC conversion
- Support for both date-only and datetime field configurations
Use Cases
Event Calendar with Recurring Events
Create a content type for events with a date_recur field. Configure the field to allow weekly and monthly frequencies with BYDAY and BYMONTHDAY parts. Use Views with the occurrence filter to display events occurring within a date range, and the occurrence relationship to list all upcoming instances. Configure an interpreter to show 'Every Monday and Wednesday' instead of raw RRULE strings.
Appointment Scheduling System
Use date_recur fields on appointment content types to define recurring availability slots. Set the precreate interval to 2 years to generate occurrence data for scheduling. Create Views with the occurrence filter to find available slots within a selected time period. The occurrence cache table enables efficient querying without runtime RRULE calculation.
Class or Course Scheduling
Define courses that meet on specific patterns (e.g., every Tuesday and Thursday from 2-4pm). Configure field settings to restrict frequencies to WEEKLY and parts to BYDAY, UNTIL, and COUNT to prevent overly complex rules. The formatter shows the class schedule in plain English while storing the precise RRULE for occurrence generation.
Maintenance Schedule Management
Track equipment maintenance schedules with date_recur fields. Use MONTHLY frequency with BYMONTHDAY to schedule maintenance on specific days each month, or YEARLY with BYMONTH for annual inspections. Subscribe to the FIELD_VALUE_SAVE event to trigger notifications or create work orders when schedules are updated.
Custom Occurrence Processing
Implement an event subscriber for date_recur_field_value_save to sync occurrences with external calendar systems (Google Calendar, Outlook) or to create individual nodes/entities for each occurrence. The event provides access to the field item list and entity context for custom processing logic.
Tips
- Use the precreate setting wisely - longer intervals generate more occurrence rows but enable querying further into the future
- When using Views with date_recur fields, add the occurrence relationship first, then add fields/filters from the occurrence table for proper occurrence-based queries
- Configure interpreter settings to match your site's language and date format preferences for consistent user experience
- Restrict allowed frequencies and parts in field settings if you don't need the full complexity of RRULE - this simplifies the user experience
- For infinite recurring rules, the occurrence cache only contains precreated dates - plan your precreate interval based on how far ahead users need to query
- Subscribe to date_recur events for custom processing rather than using entity hooks, as the events provide the specific field context
- The RRULE textarea in the basic widget accepts standard iCalendar format - users can paste RRULEs from other calendar applications
- When creating custom formatters or widgets, use the DateRecurHelper::create() factory method to get occurrence data from field values
Technical Details
Admin Pages 3
/admin/config/regional/recurring-date-interpreters
Manage recurring date interpreters that convert RRULE strings into human-readable text. Interpreters are reusable configurations that can be selected in field formatter settings to control how recurring rules are displayed to users.
/admin/config/regional/recurring-date-interpreters/add
Create a new recurring date interpreter configuration. First select the plugin type, then configure plugin-specific settings.
/admin/config/regional/recurring-date-interpreters/manage/{date_recur_interpreter}
Modify settings for an existing recurring date interpreter.
Permissions 1
Hooks 5
hook_theme
Defines three theme hooks for rendering recurring date components: date_recur_basic_widget, date_recur_settings_frequency_table, and date_recur_basic_formatter.
hook_field_info_alter
Marks date_recur field type and any subclasses with a special flag (is_date_recur) used for occurrence table management and Views integration.
hook_field_views_data
Provides Views integration for date_recur attached fields, including occurrence table relationship and field handlers.
hook_views_data
Provides Views integration for date_recur base fields and occurrence filter plugin registration.
hook_views_data_alter
Removes default Views handlers from date_recur base fields that would conflict with the module's custom handlers.
Troubleshooting 6
Run 'composer require rlanvin/php-rrule' in your Drupal root directory to install the required library, then clear caches.
Ensure you've added the occurrence relationship to your View before adding occurrence-based fields or filters. Check that the occurrence cache table exists (date_recur__[entity_type]__[field_name]) and contains data.
Create an interpreter at /admin/config/regional/recurring-date-interpreters and select it in the field formatter settings. Verify the interpreter plugin is properly configured.
The module validates timezones on update. Run the provided update hook which will identify invalid timezone values that need manual correction in the database.
Check field settings to ensure at least one frequency with at least one part is enabled. If 'Allow all frequency and parts' is unchecked and no frequencies are enabled, the RRULE input will be hidden.
Each date_recur field creates its own occurrence cache table. For infinite rules, occurrence data is precreated based on the precreate interval. Consider reducing the precreate interval or using COUNT/UNTIL limits on rules to reduce database size.
Security Notes 4
- The module has 'covered' security advisory coverage from Drupal's security team
- Timezone values are validated against PHP's timezone_identifiers_list() to prevent injection of invalid values
- RRULE strings are validated using the php-rrule library's parser to ensure only valid rules are stored
- The rrule_max_length storage setting provides protection against extremely long RRULE strings that could impact performance