Phoca Cart – Booking Feature User Manual

Welcome to the comprehensive guide for the Phoca Cart Booking Feature. This manual provides step-by-step instructions for store administrators and developers on configuring booking products, managing slots, testing the customer checkout workflow, and administering bookings in the backend.

Phoca Cart – Booking Feature User Manual

1. Introduction & Core Concepts

The Phoca Cart Booking feature extends Phoca Cart to support scheduled appointments and calendar-based rentals.

Key Concept: Bookings vs. Subscriptions

Subscriptions handle recurring memberships or access fees over time.
Bookings handle calendar availability, reserved capacity, and specific execution dates/times tied directly to standard Phoca Cart orders.

The Two Booking Modes

Feature	Time Slot Mode (Mode 1)	Date Range Mode (Mode 2)
Typical Use Cases	Medical/salon appointments, tours, consultations, fitness classes	Hotel rooms, vacation rentals, vehicle/equipment rentals
Selection Type	Specific date and time block (e.g. `2026-11-15 10:00 - 11:00`)	Check-in date to Check-out date span (e.g. `2026-11-15` to `2026-11-18`)
Capacity Management	Per-slot capacity tracked in `#__phocacart_booking_slots`	Total unit capacity per product, tracked across overlapping dates
UI Presentation	Available slots grouped by day with remaining capacity counters	Check-in / Check-out calendar date inputs with night count summary

2. Plugin & System Configuration

The booking system operates with the system plugin: System - Phoca Cart Booking (plg_system_phocacartbooking), along with Joomla's Mail Templates engine and Phoca Cart's shipping configuration.

2.1 Configuring the Booking Plugin

In Joomla administration, go to System → Plugins.
Search for Phoca Cart Booking.
Open System - Phoca Cart Booking and verify it is Enabled.
In the Basic tab:
- Confirmation Status: Select which Phoca Cart Order Statuses confirm a booking and lock in the slot (default: Confirmed, Completed).
- Cancellation Status: Select which Order Statuses release reserved slots back to availability (default: Cancelled, Refunded, Failed, Denied).
- Require Login: Set whether guest checkout is disallowed for booking products (recommended: Yes, ensuring bookings link to registered customer accounts).

2.2 Configuring Booking Email Notifications

In the Email tab of System - Phoca Cart Booking:

Send Email on Booking Created: Toggle Yes to send a booking confirmation when an order is placed.
Send Email on Booking Confirmed: Toggle Yes to send an email when the booking transitions to Confirmed.
Send Email on Booking Cancelled: Toggle Yes to send an email when an order is cancelled or refunded.
Send Email on Booking Completed: Toggle Yes to send a completion/thank-you notice.
Send Booking Reminder Email: Toggle Yes to send reminder notices (scheduled via Task Plugin).
Send Email on Status Change: Toggle Yes to notify customers on any other status change.
BCC Email for Admin Notifications: Enter a store manager email address to receive BCC copies of all customer booking emails.
Click Save & Close.

2.3 Configuring Mail Templates in Joomla

Booking emails use Joomla's native Mail Templates system:

Navigate to System → Mail Templates.
Locate the templates under the com_phocacart component:
- 📅 Phoca Cart: Booking Received (com_phocacart.booking.created)
- ✅ Phoca Cart: Booking Confirmed (com_phocacart.booking.confirmed)
- 🚫 Phoca Cart: Booking Cancelled (com_phocacart.booking.cancelled)
- 🎉 Phoca Cart: Booking Completed (com_phocacart.booking.completed)
- ⏰ Phoca Cart: Booking Reminder (com_phocacart.booking.reminder)
- 📋 Phoca Cart: Booking Status Changed (com_phocacart.booking.status_changed)
Click any template to customize:
- Subject: E.g. {SITE_NAME} - Booking #{BOOKING_ID} Confirmed
- Body (Plain Text): Text version of the email.
- HTML Body: Rich HTML email version including the {HTML.DOCUMENT} tag which renders the structured layout (header, status badge, date details, and customer account button).
Available dynamic tags:
- {USER_NAME}, {USER_EMAIL}: Customer details
- {PRODUCT_NAME}, {PRODUCT_TITLE}, {PRODUCT_SKU}: Product info
- {BOOKING_ID}, {BOOKING_STATUS}: Booking identifier and status text
- {BOOKING_DATE_START}, {BOOKING_DATE_END}: Booking dates
- {BOOKING_TIME_START}, {BOOKING_TIME_END}: Booking times (Time Slot mode)
- {BOOKING_NIGHTS}: Number of nights (Date Range mode)
- {ORDER_NUMBER}: Linked order number
- {ACCOUNT_URL}: Link to the customer's "My Bookings" page
- {SITE_NAME}, {SITE_LINK}, {SITE_URL}: Website details

2.4 Configuring Shipping for Bookings

Booking products are services or accommodation and do not require physical shipping:

In admin, navigate to Phoca Cart → Configuration (Options) → Shipping tab.
Find the setting Skip Shipping Method:
- Select Yes (all products are downloadable or gift vouchers or subscriptions or bookings) (Option 1).
Click Save & Close. Now, carts containing only booking items (or digital products, vouchers, subscriptions) will automatically bypass the shipping step during checkout.

3. Creating a Booking Product (Step-by-Step)

In Joomla admin, navigate to Components → Phoca Cart → Products (phocacartitems).
Click New in the toolbar.
Fill in standard product details:
- Title: e.g., Executive Meeting Room or 60-Minute Consultation.
- Category: Select the desired category.
- Price: Enter the base price per booking / night.
Set Type: Select Booking (Product Type 7).
Notice that the Booking Options tab becomes available in the product edit form.

Mode 1: Time Slot Mode

Configure these settings under the Booking Options tab:

Booking Mode: Choose Time Slot.
Capacity per Slot: Default capacity for new slots (e.g. 1 for 1-on-1 consultations, 10 for a group class).
Advance Booking Days: Maximum days into the future that slots are visible (e.g., 30).
Minimum Advance Notice (Hours): Cut-off time before slot start (e.g., 2 hours minimum advance notice).
User Group on Confirmation (Optional): Automatically assign confirmed customers to a Joomla user group (e.g., Members).
Click Save.

Mode 2: Date Range Mode

Configure these settings under the Booking Options tab:

Booking Mode: Choose Date Range.
Total Capacity: Number of available units (e.g. 5 identical hotel rooms or rental bikes).
Check-in Time: Standard check-in time formatted HH:MM:SS (e.g. 14:00:00).
Check-out Time: Standard check-out time formatted HH:MM:SS (e.g. 10:00:00).
Minimum Advance Hours: Minimum hours before check-in date when booking is allowed (e.g. 24).
Maximum Advance Days: How far ahead reservations can be made (e.g. 365 days).
Click Save.

4. Managing Time Slots in Admin

Note: This step applies specifically to Time Slot Mode. In Date Range Mode, availability is calculated continuously across date spans.

Creating Available Slots

Navigate to Components → Phoca Cart → Booking Slots (phocacartbookingslots).
Click New.
Fill in the slot details:
- Product: Select your Time Slot booking product.
- Slot Date: The calendar date for the slot (e.g., 2026-11-20).
- Start Time: Starting time (e.g., 09:00:00).
- End Time: Ending time (e.g., 10:00:00).
- Capacity: Total attendees/bookings allowed for this specific slot (e.g., 1 or 5).
- Published: Yes.
Click Save & New to add more slots, or Save & Close.

Inspecting Slot Capacity

In the Booking Slots list view, you can monitor:

Date & Time Range
Total Capacity
Booked Count: Number of confirmed slots booked by customers.
Remaining Capacity: Automatically calculated as Capacity - Booked.

5. Frontend Booking Workflow & Customer Experience

Product Page & Interactive Pickers

When a customer navigates to a Booking product on the store frontend:

Time Slot Mode UI

Available slots are dynamically retrieved for future published dates.
Slots are organized in daily groupings with localized date headers.
Each slot displays its time window (09:00 – 10:00) and the remaining spaces (3 slots remaining).
Customer clicks their desired slot radio button. The selection automatically populates the order payload.

Date Range Mode UI

Displays dedicated Check-in Date and Check-out Date calendar controls.
Past dates and dates with insufficient notice are automatically disabled.
Dates that are already fully booked are blocked and highlighted.
When valid dates are selected, an instant summary displays the duration (e.g. 3 Nights).

Shopping Cart & Checkout

Customer clicks Add to Cart.
If Require Login is enabled and the user is a guest, an informative prompt asks the customer to log in or register before booking.
The cart and checkout process proceed through Phoca Cart's standard workflow.
When the order is placed, an immutable order snapshot is saved in #__phocacart_order_bookings.

Customer Account ("My Bookings")

When a logged-in customer visits My Account (index.php?option=com_phocacart&view=account):

A dedicated My Bookings table appears alongside order history and address details.
Displays:
- Booking Date & Times
- Product Name (with link)
- Booking Mode badge (Time Slot or Date Range)
- Current Status badge (Confirmed, Pending, Cancelled)

6. Order Status Synchronization & Booking Lifecycle

Bookings in Phoca Cart are directly synchronized with the store's Order Status engine:

[Customer Checkout] 
       │
       ▼
Order Created ───────► Booking Created with "Pending" Status
       │               (Slot temporarily held)
       │
[Payment Received / Admin Confirms Order]
       │
       ▼
Order Status: "Confirmed" / "Paid"
       │
       ▼
Plugin Event: onPhocaCartAfterOrderStatusUpdate
       ├── Booking Status updated to "Confirmed"
       ├── Slot capacity incremented in #__phocacart_booking_slots
       ├── User group added (if configured)
       └── Audit entry logged in #__phocacart_booking_history
       │
[Order Cancelled or Refunded]
       │
       ▼
Order Status: "Cancelled" / "Refunded"
       ├── Booking Status updated to "Cancelled"
       ├── Slot capacity released (booked count decremented)
       ├── User group removed (if assigned)
       └── Cancellation audit entry logged

7. Administering Bookings in Backend

Bookings List View

Navigate to Components → Phoca Cart → Bookings (phocacartbookings).

Here you can:

View all customer bookings in real time.
Filter by:
- Status (Confirmed, Pending, Cancelled, Completed, No-Show)
- Product
- Date Start Range
Sort by date start ascending or descending.
Directly see the Customer User Name, Order ID, Product Title, and Date/Time Range.

Editing a Booking & Audit History

Click any booking in the list to open the edit view (phocacartbooking):

Customer & Order: Displays User ID and linked Order ID.
Dates & Times: Review check-in/check-out or slot start/end.
Status Control: Manually change status (e.g. mark as Completed or No-Show).
Notes: Internal administrative notes regarding the booking.
History Tab: Displays the full audit trail from #__phocacart_booking_history, showing every timestamp, status change, and event trigger (order creation, admin update, payment webhook).

8. Step-by-Step Testing & Verification Guide

Follow this testing checklist to verify your installation:

Test Scenario A: Time Slot Appointment

Create a Time Slot product named Test Consultation (Type: Booking, Mode: Time Slot).
Go to Booking Slots and create 2 slots for tomorrow:
- Slot 1: 10:00 - 11:00, Capacity: 1.
- Slot 2: 14:00 - 15:00, Capacity: 2.
Open the product on the frontend.
Verify both slots appear under tomorrow's date with correct remaining counts.
Select Slot 1 (10:00 - 11:00) and complete checkout.
Check Booking Slots in admin: Slot 1 now displays Booked: 1, Remaining: 0.
Refresh the frontend product page: Slot 1 is no longer selectable. Slot 2 is still available.

Test Scenario B: Date Range Rental

Create a Date Range product named Apartment Sea View (Type: Booking, Mode: Date Range, Capacity: 1).
Open the product on the frontend.
Select Check-in: 2026-12-01, Check-out: 2026-12-05.
Confirm the UI calculates 4 Nights.
Complete checkout for the reservation.
Open the product page again: selecting any range overlapping 2026-12-01 to 2026-12-05 alerts the customer that dates are unavailable.

Test Scenario C: Cancellation & Capacity Release

In the admin, navigate to Orders and find the test order from Scenario A.
Change the Order Status to Cancelled.
Navigate to Booking Slots: Verify Slot 1 has returned to Booked: 0, Remaining: 1.
Navigate to Bookings: Verify the customer's booking status shows Cancelled.
Open the booking's History tab: Confirm the cancellation transition was logged.

Test Scenario D: Booking Email Notifications

Ensure System - Phoca Cart Booking plugin has email options enabled (under the Email tab).
Set a test email in the BCC Email for Admin Notifications field.
Place a booking order on the frontend as a logged-in user.
Verify Booking Received Email:
- Check the customer's inbox (or mail log): An email with subject 📅 [Site Name] - Booking #[ID] Received is delivered.
- Verify the email body contains the customer name, product title, booking ID, dates, and account link.
- Verify a BCC copy is delivered to the administrator.
In the backend, change the Order Status to Confirmed (or Completed).
Verify Booking Confirmed Email:
- Customer receives ✅ [Site Name] - Booking #[ID] Confirmed.
- The booking status in the email displays Confirmed.
In the backend, change the Order Status to Cancelled.
Verify Booking Cancelled Email:
- Customer receives 🚫 [Site Name] - Booking #[ID] Cancelled.

Test Scenario E: Automatic Night Calculation & Cart Checkout

Open a Date Range booking product with price set to e.g. €50.
On the frontend product page, select check-in 2026-12-10 and check-out 2026-12-15 (5 nights).
Verify that the quantity input is hidden and the UI displays 5 nights.
Click Book Now to add to cart.
Proceed to the Shopping Cart and Checkout:
- Verify the item shows Quantity = 5 with unit price €50 → Subtotal €250.
- Verify the quantity is displayed as a read-only badge and cannot be manually edited by the customer.
- If Skip Shipping option 1 is enabled, verify the shipping selection step is bypassed.
Complete the order and verify the order total matches the calculated price (€250).

Test Scenario F: Cart Conflict Validation

Add a Date Range booking to the cart for dates 2026-12-10 to 2026-12-15.
Return to the same product page and try to add the exact same dates 2026-12-10 to 2026-12-15 to the cart again.
Verify that the system blocks the action and displays the error message: The selected booking dates or time slot are already in your shopping cart.
Try to select overlapping dates (e.g. 2026-12-12 to 2026-12-18) and add to cart.
Verify that the conflict check blocks the overlapping booking.

In the admin, navigate to Components → Phoca Cart → Bookings (administrator/index.php?option=com_phocacart&view=phocacartbookings).
Scroll below the booking table to find the Booking Calendar.
Use the navigation buttons (‹ / ›) to browse to the month containing test bookings.
Verify that booking pills appear on the calendar with color coding:
- Green pills for Confirmed bookings.
- Blue pills for Pending bookings.
- Departure (⇥) and Arrival (⇤) indicators on turnover days with amber highlighting.
For Time Slot products, verify that multiple slots on the same day appear as distinct pills with time indications (e.g. (09:00-10:00) and (14:00-15:00)).
Click any booking pill:
- Verify that the Booking Details modal window opens cleanly.
- Verify the modal shows: Booking #, Status badge, Customer name/email, Order link, Product title, Dates, Time slot, Quantity, and Notes.
- Click the order link in the modal → opens the order in a new tab.
- Click the Edit button in the modal footer → opens the booking edit screen.

9. Technical Architecture & Assets

Asset Separation Rules (Phoca Cart Standards)

CSS: Frontend booking styles are consolidated in: /media/com_phocacart/css/main.css (No inline <style> tags are placed in layouts or views).
JavaScript: Interactive picker behavior is consolidated in: /media/com_phocacart/js/phoca/phocacartbooking.js (Loaded cleanly via WebAssetManager com_phocacart.booking).
Layouts: Layout files (components/com_phocacart/layouts/booking_*) contain only semantic HTML markup with data attributes.

Database Tables Summary

#__phocacart_booking_slots: Available time blocks and capacities.
#__phocacart_bookings: Active customer booking records.
#__phocacart_order_bookings: Order snapshot at time of checkout.
#__phocacart_booking_history: Timestamped audit trail of status changes.

10. Troubleshooting & FAQ

Q: Why don't any time slots appear on my product page?
A: Ensure that you have created slots in Booking Slots for that specific product, that the slot dates are in the future, and that the slot status is Published.

Q: Guest customers receive an error when clicking Add to Cart.
A: Check the plugin settings in System - Phoca Cart Booking. If Require Login is enabled, guests must create an account or sign in to reserve a booking.

Q: Can I change slot capacity after slots are created?
A: Yes. You can open any slot in Booking Slots and adjust the Capacity number at any time.

Q: What happens if an admin cancels an order?
A: The system plugin automatically detects the order status transition, updates the booking to Cancelled, and immediately frees up the slot capacity for new customers.

11. Advanced Features & Enhancements (v6.2.0)

11.1 Automatic Night Calculation & Quantity

For Date Range (accommodation) booking products:

The quantity selector is automatically hidden on the product detail page — customers cannot manually alter it.
The system automatically calculates and sets quantity = number of nights selected (e.g. check-in 10.05., check-out 13.05. = 3 nights → quantity set to 3).
In the checkout process, the quantity field is rendered as a read-only badge to prevent price tampering.
During order creation and final validation, the server validates that the quantity matches the exact number of nights in the selected date range.

11.2 Cart & Date Conflict Validation

The system prevents duplicate and overlapping bookings:

Duplicate Prevention: Adding the exact same booking dates or timeslot twice is blocked with COM_PHOCACART_BOOKING_DATES_ALREADY_IN_CART.
Overlap Conflict Detection: Selecting dates that conflict with another reservation in the cart or with confirmed bookings in the database is blocked.
Slot Capacity Enforcement: For Time Slot mode, adding more slots to cart than available capacity is rejected with COM_PHOCACART_BOOKING_SLOT_CAPACITY_EXCEEDED.

11.3 Custom Booking Button Text

In the product's Booking tab, vendors can specify a custom button label:

Field: Booking tab → Custom Button Text (booking_button_text)
Default: Displays "Book Now" (COM_PHOCACART_BOOK_NOW) if left blank.
In product category and list views, booking-type products always route directly to the product detail view where the booking picker and calendar reside.

11.4 Skip Shipping for Booking Products

In Phoca Cart → Configuration → Shipping, the Skip Shipping Method setting option 1 applies to bookings:

Option 1: Yes (all products are downloadable or gift vouchers or subscriptions or bookings) — suppresses shipping selection during checkout when the cart contains downloadable, subscription, voucher, or booking products.

11.5 Booking Status Lifecycle & Unification

Booking statuses are tightly coupled with Phoca Cart's dynamic order status workflow:

Order Created: Booking record created with status Pending Payment (or Confirmed if initial order status is in confirmation list).
Order Confirmed / Completed: System plugin maps order status to booking status Confirmed or Completed (and assigns configured user groups).
Order Cancelled / Refunded: System plugin maps order status to booking status Cancelled, immediately releasing slot capacity back to the available pool.
Configuration: In Plugins → System - Phoca Cart Booking, configure the order statuses that trigger confirmation (default: 2, 6) or cancellation (default: 3, 5, 7, 8).

11.6 Mail Templates & Email Notifications for Bookings

Customers automatically receive dedicated emails when their booking status changes.

Email Triggers

Event	Trigger Condition	Template Key
Created	Order placed, booking created	`com_phocacart.booking.created`
Confirmed	Order confirmed by admin or payment	`com_phocacart.booking.confirmed`
Cancelled	Order cancelled or refunded	`com_phocacart.booking.cancelled`
Completed	Order marked as completed	`com_phocacart.booking.completed`
Reminder	Upcoming booking notification	`com_phocacart.booking.reminder`
Status Changed	Any other status transition	`com_phocacart.booking.status_changed`

Template Customization

Mail templates can be managed in System → Mail Templates:

Each template supports both HTML ({HTML.DOCUMENT}) and plain text formats.
Available tags: {USER_NAME}, {PRODUCT_NAME}, {BOOKING_ID}, {BOOKING_STATUS}, {BOOKING_DATE_START}, {BOOKING_DATE_END}, {BOOKING_TIME_START}, {BOOKING_TIME_END}, {BOOKING_NIGHTS}, {ORDER_NUMBER}, {ACCOUNT_URL}, {SITE_NAME}, {SITE_LINK}.

Plugin Configuration

In Plugins → System - Phoca Cart Booking under the Email tab:

Each email trigger (Created, Confirmed, Cancelled, Completed, Reminder, Status Changed) can be individually toggled.
BCC Email for Admin Notifications: Enter an administrator email address to receive a copy of all customer booking notifications.

Navigate to Phoca Cart → Bookings in the administration panel to view the interactive monthly calendar below the list table:

Bootstrap Modal: Clicking any booking pill opens an interactive, dismissible modal with comprehensive details:
- Booking # and color-coded status badge
- Customer name and email
- Order number with clickable link to the order edit screen
- Product title
- Full date range (Check-in → Check-out)
- Time slot start and end times (or "Date Range Mode" for overnight rentals)
- Booked quantity and customer notes
- Direct Edit action button linking to the full booking administration form
Multiple Timeslots Support: When a day contains multiple timeslot reservations (e.g. from an order with 2 slots on the same day), each timeslot is displayed as an independent pill with its time formatted (e.g. #12 John Doe (09:00-10:00) and #13 John Doe (14:00-15:00)), allowing detailed inspection of each slot.
Turnover Days: Days with both a departure and an arrival are highlighted in amber gradient with special indicator icons.

11.8 Frontend Calendar Improvements & Dark Mode

Date Reset Bug Fix: In Date Range mode, clicking an already-selected date immediately deselects it and clears the range. If a blocked date is encountered, the calendar gracefully resets rather than locking navigation.
Dark Mode Support: Full native support for Joomla and Phoca Cart dark mode via [data-bs-theme="dark"], styling all calendar cells, legends, modals, date inputs, and readonly quantity badges.

12. Additional FAQ

Q: Can I disable booking confirmation emails if I already send standard order confirmation emails?
A: Yes. In Plugins → System - Phoca Cart Booking, open the Email tab and toggle "Send Email on Booking Created" to "No".

Q: How do timeslots appear in the admin calendar if one customer books multiple slots?
A: Each reserved timeslot is rendered as its own distinct pill in the calendar day cell, displaying the start and end time. Clicking any pill displays the modal window for that specific slot.

Q: Where can I translate or customize booking email text?
A: You can edit the text directly in System → Mail Templates, or override the language constants in System → Language Overrides.