PPPHP

Calendar & Events — CalendarService + Designer

The Calendar is a standalone event-management app (like Google Calendar) that PPPHP can add to any generated application. It provisions its own tables, lets users create and share events, schedule meetings, invite people and groups, set reminders, and import/export iCal — all without a business table. This guide covers how to enable it, customize it in the Designer, and call its PHP API from your own code.

Contents

Enabling the Calendar

Open the Tables module, open the Create ▾ menu (the arrow beside Create Table) and choose Calendar. Toggle Enable the Calendar app in this project and pick your defaults (default view, first day of week, menu label, personal calendars, in-app notifications, email reminders), then Save & enable. On the next Build, the calendar is generated at generated/calendar/index.php and a menu link is added.

The enable switch lives only in this modal — it is what turns the calendar on for the project. Everything about how it looks and behaves is edited in the Designer (below). The settings both places share — default view, week start, menu label, personal calendars, in-app notifications and email reminders — stay in step: whichever you save last is copied to the other, so the dialog always opens showing what the build will use (before 1.0.224 a choice made in the dialog was silently overridden by the Designer page). The calendar creates its tables automatically the first time a signed-in user opens it.

Customizing in the Designer

Open Designer → Common Pages → Calendar. What you see on the canvas is exactly what the build generates. The calendar is one smart component whose regions are individually clickable: click the Header, Toolbar, Sidebar, Grid or Footer and the Properties panel focuses on that region. Click the calendar background (or use the component chip) to edit all settings at once.

Every control here provably changes the generated app — the Designer only exposes settings the live calendar can honour, so what you design is what you get. The preview opens on today's month in the app's own theme colour, and shows a week of hour rows when the default view is Week or Day (weekend shading tints Saturday and Sunday there too). To start over, use Reset to default on the page; it restores the standard template.

Region reference

RegionSettings
HeaderHeading, subtitle, menu label, alignment, accent colour, and heading typography (font, size, colour).
ToolbarDefault view; show/hide each view (Week, Day, Agenda, Year — Month is always on); Today button; prev/next arrows; Import/Export buttons; the “New event” button and its label.
SidebarShow/hide the whole side panel, and per-section toggles: Create button, mini-month navigator, Calendars list, Categories, Upcoming events.
GridWeek-start day, weekend shading, Today colour, grid-line colour.
FooterShow an optional caption line under the calendar, with custom text.
AppearanceBase font for the whole calendar app.
NotificationsPersonal calendars, in-app notifications, email reminders.

Fonts & colours. Font pickers use the app’s bundled web fonts (add more via the local fonts pipeline). Colour and size fields accept CSS values (e.g. #ef4444, 1.8rem); they are sanitised at build time before being written into the page.

Tables & the visibility model

The calendar self-provisions five pp_ tables (created on first run, healed on upgrade):

Who can see an event? A user sees an event if they own it, OR it is public, OR it is shared to them (directly, via a group, or to everyone), OR they are an attendee — and admins see all. Editing requires ownership, an edit-share, or admin.

Invitations always reach the invitee: the event lives in the organiser's calendar, which the invitee cannot list, so the sidebar's calendar switches only hide the calendars you turned off — they never filter out what someone invited you to. An invitee answers straight from the event popover (Going? Yes · Maybe · No); the organiser sees the ✓ next to their name. An RSVP can only be given to an event the user can already see — it can never be used to join a private event. Someone else's calendar is labelled with its owner (“Asha Gurung's calendar”), and the invite picker and avatars use each user's full name when the users table has a fullname column.

Server API — CalendarService

The calendar service ships inside every build, so you can call it from your own event handlers, scheduled tasks or custom pages. Resolve the current user’s context first:

use PpPhp\Core\Calendar\CalendarSchema;
use PpPhp\Core\Calendar\CalendarService;

CalendarSchema::ensure();                 // create/heal tables (safe to call anytime)
$ctx = CalendarService::contextFromApp(); // ['uid' => int, 'groups' => int[], 'isAdmin' => bool]

Reading

// Calendars the user can see (always includes their personal calendar)
$cals = CalendarService::calendars($ctx);

// Events visible to the user in a date window (recurrence expanded to occurrences)
$events = CalendarService::events($ctx, '2026-07-01', '2026-07-31');

// Optionally restrict to specific calendar ids
$events = CalendarService::events($ctx, $from, $to, [1, 4]);

// One event with its shares, attendees and reminders
$ev = CalendarService::getEvent($ctx, $eventId);

Writing

$id = CalendarService::createEvent($ctx, [
    'title'      => 'Sprint review',
    'starts_at'  => '2026-07-15 15:00',
    'ends_at'    => '2026-07-15 16:00',
    'location'   => 'Room 2',
    'color'      => '#2563eb',
    'visibility' => 'groups',                 // inherit|private|public|groups|users
    'rrule'      => 'FREQ=WEEKLY;BYDAY=TU',   // optional recurrence
    'reminders'  => [['minutes' => 15, 'method' => 'notify']],
    'shares'     => [['principal' => 'group', 'id' => 3, 'permission' => 'view']],
    'attendees'  => [7, 12],
]);

CalendarService::updateEvent($ctx, $id, ['title' => 'Sprint review (moved)']);
CalendarService::reschedule($ctx, $id, '2026-07-16 15:00', '2026-07-16 16:00');
CalendarService::setRsvp($ctx, $id, 'accepted');
CalendarService::deleteEvent($ctx, $id);

Every write is permission-checked against $ctx. Ids are validated; user text is parameterised.

Reminders & notifications

Events carry reminders with a method: popup (a browser alert, client-side), notify (the in-app notification bell) or email. Enable the delivery paths in the Designer’s Notifications region (In-app notifications / Email reminders). When either is on, the build adds a calendar-reminders cron task that dispatches due reminders:

// Run by the generated cron once a minute; safe to call yourself.
CalendarService::dispatchReminders();

You can also circulate a new event to its audience (attendees + share targets) on creation:

// delivery: 'notify' | 'email' | 'both' | 'none'
CalendarService::circulate($ctx, $eventId, 'both');

In-app notifications are written to the app’s own notifications table (Misc → Advanced → Notifications), so they appear in the same bell your other features use. An invitation reads like “Sam Rivera invited you to Sprint planning · Tue, Oct 6, 10:00am”; opening it from the bell marks it read, and Mark all read clears the badge for good. A new reminder defaults to notify (the bell) when in-app notifications are on — a popup only shows while the calendar tab is open. Reminders dispatch on every database engine, including the Virtual DB (SQLite).

iCal import / export & recurrence

use PpPhp\Core\Calendar\CalendarIcs;

// Export visible events to an .ics string
$ics = CalendarIcs::export(CalendarService::events($ctx, $from, $to));

// Parse an uploaded .ics into event arrays (feed to createEvent)
$rows = CalendarIcs::parse($uploadedIcsString);

Recurrence uses standard RRULE (FREQ = DAILY / WEEKLY / MONTHLY / YEARLY, plus INTERVAL, COUNT, UNTIL, BYDAY). The service stores one master event (the rule without the RRULE: prefix) and expands occurrences on read via CalendarRecurrence. In iCal an all-day DTEND is the day after the last day; import converts it to the calendar's inclusive end (a one-day event stays one day) and export adds the day back. In the editor, choosing Weekly lights the event's own weekday, and the day chips follow the week start.

The generated JSON endpoint

The built calendar page (generated/calendar/index.php) is both the page shell and a JSON API, dispatched by ?action=. All writes are POST and CSRF-guarded (token in the JSON body or the X-CSRF-Token header). Actions:

ActionPurpose
bootstrapInitial payload (calendars, principals, settings).
eventsEvents in a from/to window.
eventOne event with shares/attendees/reminders.
create_event · update_event · delete_eventCRUD.
rescheduleDrag-move / resize.
create_calendarNew personal calendar.
rsvpRespond to an invitation.
principalsUsers + groups for invite/share pickers.
import · exportiCal in / out.

Front-end — PPCalendarApp.mount()

The UI is a single self-contained script bundled with the app (no CDN). The build mounts it with the options the Designer produced:

PPCalendarApp.mount(document.getElementById('pp-calendar-app'), {
    base: '.../generated/calendar/index.php',
    token: '<csrf>',
    defaultView: 'month',        // month|week|day|agenda|year
    firstDay: 0,                 // 0 = Sunday, 1 = Monday
    views: ['month','week','day','agenda','year'],  // which view buttons show
    showToday: true, showNav: true, showIcs: true,
    showNewEvent: true, newEventLabel: 'New event',
    weekendShading: false,
    showSidebar: true,           // + sideCreate / sideMiniMonth / sideCalendars / sideCategories / sideUpcoming
    appReminders: true, emailReminders: false, notifEnabled: true,
    allowPersonal: true
});

Header typography, accent, Today colour, grid-line colour and base font are applied as scoped CSS / CSS variables on the page — you don’t pass them here; the Designer bakes them into the shell.

Recipes

Seed an event from an order handler:

$ctx = CalendarService::contextFromApp();
CalendarService::createEvent($ctx, [
    'title'     => 'Deliver order #' . $orderId,
    'starts_at' => $dueDate . ' 09:00',
    'all_day'   => 0,
    'color'     => '#16a34a',
    'reminders' => [['minutes' => 60, 'method' => 'email']],
]);

A read-only, embedded calendar (no sidebar, month only): in the Designer set the Sidebar → Show side panel off, and in the Toolbar turn off every view except Month and hide the “New event” button. Rebuild — the generated page matches exactly.

Brand the calendar: set the Header accent to your brand colour, choose a heading font and size, and (optionally) a base font under Appearance. The mini-month “today”, the primary buttons and event chips all follow the accent.

See also: Notifications (the bell reminders use), Email (email reminders), and the Designer’s built-in Common Pages → Calendar live preview.