Calendar

Description

Calendar adds calendar and event management to Laravel Enso.

The package supports persisted calendars and events, recurring event sequences, attendees, reminders, all-day events, and custom readonly calendar sources that can project data from outside the calendar_events table.

It also ships with a builtin Birthday calendar, reminder notifications delivered through mail, database, and broadcast channels, plus the backend API and form metadata consumed by the Enso calendar frontend.

Installation

This package is normally installed as part of the Enso ecosystem.

For standalone installation in an Enso-based application:

composer require laravel-enso/calendar

Optional publishes:

php artisan vendor:publish --tag=calendar-provider
php artisan vendor:publish --tag=calendar-config
php artisan vendor:publish --tag=calendar-mail
php artisan vendor:publish --tag=calendar-factories

Birthday calendar configuration:

return [
    'birthdays' => [
        'roles' => ['*'],
    ],
];

The package also registers the reminder command:

php artisan enso:calendar:send-reminders

Features

Manages calendars with configurable colors and privacy flags.
Manages events with title, body, location, attendees, reminders, geocoordinates, and all-day support.
Supports recurring events with Once, Daily, Weekdays, Weekly, Monthly, and Yearly frequencies.
Supports recurrence update scopes: Only This, This And Future, and All.
Generates and reshapes recurring sequences through dedicated create, update, delete, and extraction services.
Exposes a builtin readonly Birthday calendar sourced from Person records.
Allows registering additional custom calendars that return readonly event projections.
Sends overdue reminders through queued mail, database, and broadcast notifications.
Registers reminder mail previews through laravel-enso/mails.
Registers form metadata and API resources used by the Enso calendar frontend.

Usage

Create and manage native calendars and events through the provided API routes, or register custom readonly calendars through the published provider:

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use App\Calendars\OrdersCalendar;

class CalendarServiceProvider extends ServiceProvider
{
    protected array $register = [
        OrdersCalendar::class,
    ];
}

A custom calendar must implement LaravelEnso\Calendar\Contracts\CustomCalendar and return event objects that implement LaravelEnso\Calendar\Contracts\ProvidesEvent.

To dispatch due reminders manually:

php artisan enso:calendar:send-reminders

::: tip Tip Use custom calendars for readonly projections coming from other bounded contexts. If users need to create or edit the events themselves, store them as native Calendar and Event records instead. :::

::: warning Note Reminder notifications depend on Laravel's scheduler. If the scheduler is not running, overdue reminders will remain pending until enso:calendar:send-reminders is executed. :::

API

Commands

enso:calendar:send-reminders

Calendar Routes

All routes are registered under the core.calendar. name prefix and /api/core/calendar path prefix.

GET /api/core/calendar -> core.calendar.index
GET /api/core/calendar/create -> core.calendar.create
POST /api/core/calendar -> core.calendar.store
GET /api/core/calendar/{calendar}/edit -> core.calendar.edit
PATCH /api/core/calendar/{calendar} -> core.calendar.update
DELETE /api/core/calendar/{calendar} -> core.calendar.destroy
GET /api/core/calendar/options -> core.calendar.options

Event Routes

Event routes are registered under the core.calendar.events. name prefix.

GET /api/core/calendar/events -> core.calendar.events.index
GET /api/core/calendar/events/create -> core.calendar.events.create
POST /api/core/calendar/events -> core.calendar.events.store
GET /api/core/calendar/events/{event}/edit -> core.calendar.events.edit
PATCH /api/core/calendar/events/{event} -> core.calendar.events.update
DELETE /api/core/calendar/events/{event} -> core.calendar.events.destroy

Models

Calendar

LaravelEnso\Calendar\Models\Calendar

Key relations:

events()

Exposed state:

name()
color()
private()
readonly()

Event

LaravelEnso\Calendar\Models\Event

Key relations:

parent()
events()
attendees()
calendar()
reminders()

Key methods:

store(?int $updateType = null)
remove(?int $updateType)
attendeeList()
updateReminders($reminders)

Supported frequencies:

Once
Daily
Weekdays
Weekly
Monthly
Yearly

Supported recurrence update scopes:

Only This
This And Future
All

Reminder

LaravelEnso\Calendar\Models\Reminder

Key methods and scopes:

send()
scopeNotSent()
scopeOverdue()
scopeShouldSend()

Custom Calendar Contracts

LaravelEnso\Calendar\Contracts\Calendar
LaravelEnso\Calendar\Contracts\CustomCalendar
LaravelEnso\Calendar\Contracts\ProvidesEvent
LaravelEnso\Calendar\Contracts\Routable

The builtin BirthdayCalendar is the reference implementation for readonly custom calendars.

Event Payload

The event resource returned to the frontend includes:

id
title
parentId
isLast
body
start
end
location
frequency
recurrenceEnds
allDay
readonly
class
route
deletable
resizable

Validation Rules

The event request validates:

calendar membership
supported frequency ids
start and end dates
start and end times
attendee ids
recurrence end dates
update scope

It also prevents:

recurring metadata on singular events
invalid subsequence backdating when updating future events

Configuration

config/enso/calendar.php

Keys:

birthdays.roles

Depends On

Required Enso packages:

Companion frontend package:

@enso-ui/calendar ↗

Contributions

are welcome. Pull requests are great, but issues are good too.

Thank you to all the people who already contributed to Enso!