Bookings — Documentation

Developer documentation for Bookings (BABA.Bookings). Everything below is written for the person installing and extending the plugin, not for the end customer.

1. Requirements

2. Installation

Marketplace: System → Updates & Plugins → search "Bookings" → Install.

Manual:

# copy the folder to plugins/baba/bookings, then
php artisan october:migrate
php artisan october:util purge manifest   # only needed when copying by hand

Migrations create seven tables (baba_bookings_*) and seed a working demo — three services, two staff members, a week of opening hours — so the booking form works immediately. Delete the demo rows when you add your own.

Do not install the plugin through a symlink into another directory. October's File::checkBaseDir() rejects real paths outside the project, which makes backend views render blank without an error.

3. Two-minute setup

1. System → Settings → Bookings — timezone, slot interval, minimum notice, booking horizon.
2. Bookings → Staff — add a person, tick the services they offer. Each staff record has a Calendar feed URL (visible on the edit page) for Google/Apple/Outlook.
3. Bookings → Working hours — one row per weekday (Monday 09:00–17:00). Add a second row for the same day to model a lunch break or a split shift.
4. Bookings → Time off — holidays (whole day) or partial absences (e.g. 12:00–13:00).
5. Bookings → Services — name, duration, price, deposit, buffers, capacity.
6. Create two CMS pages (see §5) and point Settings → Booking page at the manage page.

4. The availability rules

A slot is offered only when all of the following hold:

Slots are generated on the interval from Settings → Slot interval (default 15 min), starting at the window's opening time.

Time model. Everything is stored in UTC and displayed in the timezone from Settings. Slot generation iterates in UTC, so daylight-saving transitions behave correctly: the hour that does not exist locally is never offered, and the hour that happens twice is charged as real time.

Double bookings. BookingManager::create() opens a transaction, re-checks the slot with the overlapping rows locked, and only then inserts. Two customers clicking the same 09:00 produce one booking and one "that time was just booked" message. Moving a booking from the backend runs the same check.

5. Frontend

Create a page for the form and another for the customer's manage link:

title = "Book"
url = "/book"

[bookingForm]
==
{% framework %}
{% styles %}
{% component 'bookingForm' %}
{% scripts %}

title = "Manage your booking"
url = "/booking"

[bookingManage]
==
{% framework %}
{% styles %}
{% component 'bookingManage' %}
{% scripts %}

The three tags matter: without {% framework %} the buttons do nothing, without {% styles %} the form renders unstyled, without {% scripts %} the AJAX layer never initialises. Most themes already have them in the layout — if yours does, you only need the {% component %} line.

Component bookingForm

Properties in the page file:

[bookingForm]
service = "strategy-session"
days = "10"
==

Component bookingManage

It reads ?reference=…&email=… from the confirmation email, or ?reference=…&sig=… from the Stripe return URL. Both are matched server-side; a guessed reference alone is not enough.

Styling

The form uses only bk- prefixed classes in assets/css/form.css. Recolour it by setting one custom property:

.bk-widget { --bk-accent: #1f7a5c; }

6. Backend

Statuses: pending, confirmed, completed, cancelled, no_show. Only pending and confirmed occupy the calendar.

7. Data model

Booking::starts_at and ends_at are always UTC. Use localStartsAt() / localEndsAt() to display them.

8. Events

Event::listen('baba.bookings.created', function ($booking) {
    // send to Slack, create an invoice, tag the customer…
});

The built-in mail listeners wrap themselves in try/catch and log failures, so a broken mailer never loses a booking. Your own listeners run after those.

9. Emails and reminders

Five Twig templates live in mail/ and are registered as baba.bookings::mail.{confirmed,pending,cancelled,reminder,admin_new}. Edit them in Settings → Mail Templates.

Data available to every template: booking, customer, service, staff, when, when_short, duration, price, deposit, currency, reference, manage_url, booking_page, backend_url, business, subject, terms_url.

Reminders need the scheduler:

* * * * * php /path/to/artisan schedule:run

The plugin registers an hourly job and marks reminder_sent_at, so it is safe to run as often as you like. Manual run: php artisan bookings:reminders.

10. Calendar feeds

Every staff member has a token URL:

https://example.com/bookings/calendar/{token}.ics

Read-only, RFC 5545, works in Google Calendar, Apple Calendar and Outlook. The token is 32 random characters; treat the URL as a secret. Turn the whole feature off in Settings → Notifications → Publish staff calendar feeds.

11. Stripe payments (optional)

Deposits are tracked by default — nothing is charged. To actually charge the deposit:

1. Settings → Payments → Payment collection = Stripe Checkout.
2. Paste the pk_… and sk_… keys.
3. In Stripe, add the endpoint https://example.com/bookings/payments/stripe, listen for checkout.session.completed, and paste the whsec_… signing secret.

The webhook verifies the Stripe-Signature header (HMAC-SHA256 over {timestamp}.{body} with a 300 s tolerance). Invalid or stale signatures get 400. When the session completes, the booking is marked deposit_paid and paid_at is set.

If Stripe is unreachable during booking, the appointment is still created and the customer is told to pay on the day — a payment outage never swallows a booking.

12. Permissions

A receptionist normally needs only access_bookings.

13. Extending

Add a field to the booking form. Three steps: add the column in a migration, add it to controllers/bookings/config_form.yaml so it works in the backend, then render the input in components/bookingform/body.htm and pass the posted value through BookingForm::onSubmit() into BookingManager::create().

Change the availability rules. They live in classes/Availability.php, which has no framework dependencies — edit it and update tests/run.php (run with php tests/run.php).

Custom pricing. Override Service::quote() or listen to an event before creation; Pricing::quote() is a pure function you can call anywhere.

14. Troubleshooting

15. Tests

The availability engine, pricing, ICS writer and Stripe signature verifier have no framework dependencies and ship with a standalone runner:

php tests/run.php     # 26 assertions

Bookings — Upgrade Guide

How updates arrive

Installed from the marketplace? System → Updates & Plugins → Check for updates.

Installed from the repository? Pull the tag and run the migrations:

git pull
php artisan october:migrate
php artisan october:util purge manifest   # only if you added/renamed plugin files

Before any update: take a database backup. No migration in this plugin has ever dropped customer data, and none are written to — but a backup turns a mistake into an inconvenience instead of an incident.

Versioning policy

• Patch (1.0.x) — bug fixes, copy changes, no database changes, no action needed.
• Minor (1.x.0) — new features. Database changes are additive; this file lists anything you should run or reconfigure.
• Major (2.0.0) — breaking changes to the database schema, the component API or the class names. This file will contain step-by-step migration instructions.

October 3.5 and 4.x are supported from the same codebase. A release that drops one of them will be a minor bump and is listed here.

Compatibility

1.0.2 — current release

No action needed. No schema change, no configuration change.

What changed since 1.0.1:

• Default settings are seeded on install. A fresh install now shows a populated settings page (timezone, 15-minute slots, 120-minute notice, 60-day horizon, 24-hour reminder) instead of blank number fields.
• Signed manage links. The Stripe return URL now carries an HMAC signature, so the customer lands on their booking instead of a "find your booking" form.
• Seat badges only for group services. A single-capacity service no longer shows "2 left" when two staff members can take the appointment; group services show the real remaining seat count, capped at capacity.
• Backend form buttons are plain data-request markup instead of the Ui helper, which is what makes October 3.5 work.

If you already run 1.0.1 on a live site, the only thing you may want to copy across is the new updates/seed_settings.php values — or just set them by hand in Settings → Bookings.

1.0.1 — development release

First version. Not published to the marketplace, so there is no upgrade path from it; install 1.0.2 instead.

Template for the next release

## x.y.z — date

**Action required:** <none | run migrations | re-save settings | update component markup>

### Changed
- …

### Added
- …

### Fixed
- …

### Database
- new columns / tables, and what happens to existing rows