Download the PHP package thelia/dealer-module without Composer

Dealer 4.0.4

author : Penalver Antony [email protected]

This module Thelia generates a CRUD interface for dealers (points of sale / drives), their opening hours, and — since 4.0.x — a pickup slot engine for click & collect / drive checkout.

Compatibility

Thelia >= 2.1.3 Developped for : Thelia 2.2.1

Installation

Manually

• Copy the module into directory and be sure that the name of the module is Dealer.
• Activate it in your thelia administration panel

Composer

Add it in your main thelia composer.json file

Updating from an earlier version

Dealer::update() runs every Config/update/*.sql file whose name is greater than the currently installed version, in order. Updating to 4.0.4 runs, among others:

• 4.0.2.sql — creates dealer_pickup_config and dealer_order_pickup (fresh installs before 4.0.2 were missing these tables even though the code already used them).
• 4.0.3.sql — adds dealer.timezone (default Europe/Paris).
• 4.0.4.sql — adds dealer_shedules.exception and backfills it (1 for any row that was closed, weekly-recurring, or had a period bound — i.e. anything that used to be inferred as an exceptional entry), and adds a unique constraint on dealer_order_pickup.order_id (one pickup reservation per order).

No manual step is required; activating/updating the module through the back-office triggers it.

Usage

You can find main Dealer interface on modules admin menu.

Opening hours & exceptions

A dealer's opening hours live in a single table, dealer_shedules, distinguished by the explicit exception column — it is not inferred from the other columns, because an exceptional weekly opening with no period bound would otherwise look exactly like a base row:

• Base weekly hours (exception = false): the recurring hours for a weekday (day, begin, end). This is what the back-office weekly grid manages.
• Exceptional entries (exception = true): a closure or an exceptional opening, each with its own recurrence:
  • a single date (period_begin = period_end, or either left open-ended),
  • a period (period_begin … period_end),
  • weekly, unbounded in time (a day with no period — e.g. "every Sunday, all summer" needs a period; "every Sunday" without one is open-ended),
  • yearly (recurring = true): applies every year on period_begin's month/day, the year is ignored (e.g. December 25th).
  • A closure with no begin/end closes the whole day; a closure with hours only removes that time range, and exceptional openings can restore hours inside or outside the base grid.

Dealer\Service\ScheduleApplicability::appliesOn() is the single source of truth for "does this row apply on this calendar date?" (weekday, period, yearly recurrence) — the pickup slot engine, the schedule validation and the legacy adapters all resolve against it, so they agree.

Back-office

The schedules tab (dealer edit page) is organized around three blocks:

• Weekly grid — one row per weekday, inline time slots, add/remove, copy-to-other-days; saved as a whole in a single AJAX call (POST .../schedules/week, see below) that replaces every base row in one transaction. Validation covers the whole week in one round-trip and errors are attached to their weekday.
• Exceptions list — closures and exceptional openings together, with badges and a human summary of the recurrence; a modal lets you pick the type, the repetition (single date / period / weekly / yearly), a whole-day switch for closures, with inline validation errors.
• Customer preview — the upcoming pickup days and slots exactly as the engine computes them (PickupSlotService::getAvailableSlots()), refreshed after each save, so a manager can check the effect of hours, exceptions and pickup settings without leaving the tab.

Pickup slots

dealer_pickup_config (one row per dealer) drives the slot grid:

dealer.timezone (default Europe/Paris) anchors the computation: schedule hours are naive wall-clock times in the dealer's own timezone, so "now" and every generated slot datetime are computed in it — otherwise a server running in another timezone (e.g. UTC) offsets "now" and keeps already-past slots on offer.

Algorithm (Dealer\Service\PickupSlotService::getAvailableSlots())

1. Resolve "now" (or an explicit from) in the dealer's timezone, add prep_delay_minutes.
2. Scan forward day by day, up to a hard cap of 60 days, until orderable_days days with at least one slot have been collected.
3. For each day, resolve the effective open ranges: base weekly hours, minus exceptional closures (whole day or partial), plus exceptional openings — via ScheduleApplicability.
4. Cut each open range into slots of slot_duration_minutes, drop any slot before the prep-delay cutoff.
5. Decrement each slot's remaining capacity against orders already booked on it, excluding cancelled and refunded orders (dealer_order_pickup joined to order/order_status, one query per scan window instead of one per slot).

Two Twig functions (Dealer\Twig\DealerPickupExtension) expose this to front and back templates:

Front contract (checkout)

The theme is responsible for letting the customer pick a slot and storing the choice in session before payment:

Dealer\EventListener\OrderListener (subscribed on TheliaEvents::ORDER_PAY) then:

1. Before the core order creation — re-validates the slot strictly (same grid, prep delay, window and capacity as what the engine currently offers) under a named MySQL advisory lock (GET_LOCK, keyed by dealer + slot, 5s timeout) so two concurrent checkouts cannot both take the last place. A slot that is full, stale, off-grid or forged raises Thelia\Domain\Checkout\Exception\InvalidDeliveryException and aborts the checkout — nothing is charged and no order is created without a slot.
2. After the order is created — persists the reservation into dealer_order_pickup, still under the same lock, then releases it and clears the session keys. A persistence failure at this point is logged but never aborts the order (the slot was already validated under lock).

The enforcement only applies when the order's delivery module is one of the module's dealer_pickup_delivery_modules config value (comma-separated module codes, default LocalPickup) — a stale session pickup choice cannot block a home-delivery order placed later in the same session.

Order pickup management

The BO order detail page shows the booked pickup slot (dealer, address, datetime) via a hook rendered on the order-view template.

Dealer\Controller\OrderPickupController (POST /admin/module/Dealer/order-pickup/update) lets a manager move it, in two modes:

• slot (default): pick one of the slots the engine currently offers for that dealer — validated through the same isSlotAvailable() check as a customer choice.
• custom: force a free datetime, bypassing hours and quota — meant for the case that motivates this feature: an exceptional closure was just added and existing pickups need rescheduling by hand. The manager takes responsibility for the datetime; the customer is not notified automatically.

Endpoints (back-office)

All three require the admin.dealer.schedules resource and the corresponding access level (UPDATE or VIEW), and check a CSRF token via Thelia\Tools\TokenProvider on the _token query parameter.

Deprecated

Kept for backward compatibility with the legacy Smarty front and existing integrations, but no longer the source of truth — new code should target PickupSlotService:

• Dealer\Service\SchedulesService::getOpenDays() / findOpenDay() / findHardHours() / findOpenHours() — replaced by PickupSlotService::getAvailableSlots().
• Dealer\Service\DealerUtils (and its getDealerSchedules()) — ignores the exceptional entries entirely; replaced by the dealer loops for presentation, or PickupSlotService for effective opening.
• Dealer\Model\DealerShedulesQuery::filterByPeriodNotNull() / filterByPeriodNull() — replaced by filterByException(true) / filterByException(false): the base/exceptional distinction is now an explicit column, not inferred from the presence of a period.

Loop

DealerLoop

Input arguments

Output arguments

ContactLoop

Input arguments

Output arguments

ContactInfoLoop

Input arguments

Output arguments

SchedulesLoop

Input arguments

Output arguments

RegularSchedulesLoop

Input arguments

Output arguments

ExtraSchedulesLoop

Input arguments