Download the PHP package blackpig-creatif/ephemeride without Composer

Éphéméride

A Livewire calendar component for displaying events in month and week views, with RRULE recurrence, multi-day spanning banners, and CSS custom property theming.

Éphéméride is deliberately data-agnostic. You implement a single interface to supply events as EphemerisEvent DTOs — the component handles all layout geometry, all-day spanning, overflow, and navigation. No Eloquent models, no migrations, no Filament dependency.

Requirements

• PHP 8.4+
• Laravel 12+
• Livewire 4+ (Alpine.js is bundled)

Installation

Publish the config (optional):

Publish the CSS (optional — include in your build pipeline if you prefer the source):

Quick Start

1. Generate an event provider

This creates app/BlackpigCreatif/Ephemeride/FestivalsProvider.php with the interface already implemented and a commented example. The Provider suffix is added automatically — passing FestivalsProvider and Festivals both produce the same class name.

Open the generated file and implement getEphemerides(). The $from/$to window covers the full visible grid range, including leading and trailing days from adjacent months or weeks, so your query should use it as-is.

2. Mount the component

3. Include the styles

Pull ephemeride.css into your build pipeline:

Or reference the published file at public/vendor/ephemeride/ephemeride.css.

EphemerisEvent

EphemerisEvent is a final readonly-property DTO. Construct instances via the static factory:

Properties

Computed property hooks

Read-only virtual properties — no storage, computed on access:

All-day events

Set both startsAt and endsAt to midnight (00:00). Multi-day all-day events — where endsAt > startsAt — render as horizontal spanning banners in both month and week views. The endsAt date is inclusive: an event from Mar 10 to Mar 12 covers all three days.

Recurring Events

Pass an RFC 5545 RRULE string to the rrule property. Éphéméride uses rlanvin/php-rrule internally — omit the RRULE: prefix.

Exclusions and additional dates are supported via exdates and rdates:

Expansion is bounded to the current grid window (not just the calendar month), so recurring events that fall on leading or trailing days from adjacent months are included correctly.

Views

Month view

A 42-cell (6×7) grid padded to six rows for layout stability. Multi-day all-day events render as horizontal spanning banners above the day cells for each week row. Per-day timed events stack up to month_max_events_per_day chips; any overflow shows a +X more label.

Week view

A CSS Grid layout (not a <table>). Day columns are aligned to the calendar week; rows represent time slots at the configured interval. Timed events are positioned and sized relative to week_start_hour. All-day events occupy a pinned row above the time grid and span multiple day columns where appropriate. Times outside week_start_hour–week_end_hour are not rendered.

Controlling available views

Theming

All colours, radii, and font references in the Blade templates use CSS custom properties. There are no hardcoded colour values.

CSS overrides

Override the root tokens in your own stylesheet after importing the package CSS:

Config-level defaults

Values in config/ephemeride.php under theme are applied as inline custom properties to every component instance:

Per-instance overrides

The :theme prop applies scoped custom properties to the component's root element, overriding config defaults for that instance only:

Available tokens

Category Filtering

Enable the filter bar by passing :filterable="true". Categories are derived automatically from the category property on the events in the current grid window — no configuration needed.

Clicking a category chip filters the rendered events to that category; clicking again clears the filter. The active category resets when the view period changes.

Event Popover

By default, clicking an event chip opens an inline popover card anchored to the chip. No configuration is required.

The popover shows the event title, date and time, category badge, image (when imageUrl is set), a truncated description, and a single CTA link (when url is set and popover_cta_label is configured).

To customise the popover layout, publish the views and edit resources/views/vendor/ephemeride/components/event-popover.blade.php.

Panel Mode

Panel mode moves the event detail display out of the inline popover and into a separate DOM element that you place anywhere on the page. This suits layouts where the detail sits to the side of, above, or below the calendar rather than floating over it.

When target-container is set to any non-empty string on the calendar component, clicking an event chip dispatches a browser CustomEvent named ephemeride-event-selected to window instead of opening a popover. Any element on the page that listens for this event can render the detail.

Step 1 -- Configure the calendar

Step 2 -- Place the panel component

<x-ephemeride::event-panel /> is the default receiver. Put it wherever you want the detail to appear. It listens globally for ephemeride-event-selected and renders the selected event automatically.

The panel is invisible when nothing is selected but always occupies layout space to prevent shift. It fades in when an event is clicked. A close button (SVG icon) clears the selection.

Multiple CTAs in the panel

When the event has a links array the panel renders each link as a styled button instead of the single url CTA. Each link has three keys:

If links is empty the panel falls back to rendering the single url field as a primary CTA, keeping backwards compatibility with any existing providers.

Custom panel template

To use your own markup, listen for the ephemeride-event-selected event directly. The event.detail object contains the full event payload:

Panel min-height

The outer panel container always reserves layout space. Override the default (10rem) for your layout:

Configuration Reference

Published to config/ephemeride.php:

Architecture

The component is thin at the boundary. It resolves the provider class via app($provider), calls getEphemerides($from, $to) with the full grid window, expands recurring events through EventExpander (using RSet to handle RRULE, EXDATE, and RDATE in a single pass), then passes the flat collection to MonthGrid or WeekGrid for placement geometry. The Livewire component class holds no event data; everything is derived on each render.

Three namespacing systems are registered independently:

Provider classes are resolved through the container, so constructor injection works as expected:

If the provider requires explicit binding:

Artisan Commands

Make Provider

Generates app/BlackpigCreatif/Ephemeride/FestivalsProvider.php — a scaffolded class implementing ProvidesEphemerides with a commented example body.

The Provider suffix is appended automatically and deduplicated, so all of the following produce FestivalsProvider:

If no name is given the command will prompt for one:

Testing

Changelog

See CHANGELOG.

Credits

• Stuart Hallewell
• All Contributors

License

MIT. See LICENSE.