Files
typo3-13/docs/calendars.md
T
frommeandClaude Opus 5.5 5455973dba feat: Kalender-Code replaces the product's calendar hotel
Every hotel field now has one job. The hotel's code and aliases are
import codes only (dates, lookups); a new Kalender-Code (calendar_code)
decides the availability a record shows and may be shared by a house's
summer and winter records. The product's "Unterkunft für
Belegungskalender" is replaced by the checkbox "Kalender anzeigen"
(show_calendar): a product page shows the calendar of the hotel it
displays, the season still decides which one.

- Price calendar, price tables, Belegungskalender, iCal feeds and
  /api/calendar-hotels read the Kalender-Code. A feed without one answers
  404 instead of an empty calendar.
- The upgrade wizard epProductsCalendarCode fills both fields from
  calendar_hotel, preserving today's calendars; the deploy runs it between
  the schema update and the switch. calendar_hotel stays in the database,
  so the previous release keeps working. ep:calendar-codes lists the
  product pages whose calendar differs from it.
- HotelCodeResolver is the one lookup of import codes (date import,
  /api/hotel, Travelinfo); a code on several records resolves to the
  record whose own code it is, then the lowest uid, with a warning.
  Saving a code that is already another visible record's import code is
  refused with a message naming that record.
- /api/product without hotel attaches the product's only visible
  Unterkunft (422 otherwise) and adds board_description,
  additional_services and calendar_hotel_code.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-11-16 17:18:00 +01:00

7.7 KiB
Raw Blame History

Availability and prices on product pages

TYPO3 shows three things built from contingent data. None of them talks to bpn-connect directly: all go through MyE&P, which keeps a local snapshot of bpn-connect's availability and holds the group house prices.

What Where Shown for MyE&P endpoint
Price calendar + price tables product detail, tab "Termine/Preise" products with a calendar and season summer (s) contingents/calendar, contingents/prices
Belegungskalender (availability calendar) product detail, sidebar products with a calendar and season not summer contingents/availability (+ contingents/calendar for the months to leave out)
iCal feed for booking portals https://www.ep-reisen.de/contingents/<hotel>.ical every hotel with a Kalender-Code contingents/availability

So every product with a calendar shows exactly one. The MyE&P side is documented in its docs/api-consumer-guide.md (EP/myep).

Hotel codes

Every field has one job:

Field Job
Hotel › Import-Code (code) and Weitere Import-Codes (matchcode aliases) The BusPro codes whose imported dates land on this record, and by which /api/hotel, /api/product?hotel= and the Travelinfo page find it (HotelCodeResolver). A code belongs to one visible record; saving it on a second one is refused. Nothing to do with the calendars.
Hotel › Kalender-Code (calendar_code) The BusPro code whose contingent this record shows: calendars, price tables, iCal feed. Empty = no calendar, the feed answers 404. Records may share it: a house's summer record (…GRP) and its winter record both carry the house's code.
Product › Kalender anzeigen (show_calendar) Whether the product page shows a calendar at all.
Product › Saison (season) Which one: s the price calendar, anything else the Belegungskalender.

The calendar on a product page is the Kalender-Code of the hotel that page shows: the hotel pinned in the Produktdetail element, else the product's only Unterkunft, else the one picked in its hotel list (Product::getCalendarHotelFor()).

MyE&P only understands BusPro codes that it syncs (e.g. DGS, LPJ, DKS). When BusPro has several entries for a house (Mitterlengau: nine), only one carries the house's contingent; the office says which one, and that is the Kalender-Code.

The product's old "Unterkunft für Belegungskalender" (calendar_hotel) is no longer read. The upgrade wizard epProductsCalendarCode filled the new fields from it; vendor/bin/typo3 ep:calendar-codes lists the product pages whose calendar differs from it, until it is removed.

Price calendar (summer)

  • Product/Detail.html, section Dates, partial Product/PriceCalendar; AjaxCalendarController::priceCalendarAction → contingents/calendar (status and price per day), priceTableAction → contingents/prices for the current and the next year (loaded when scrolled into view).
  • Only works for hotels that are an accommodation with prices in MyE&P (summer group houses).

Belegungskalender (winter)

  • Product/Detail.html, section AvailabilityCalendar, loaded by htmx when it scrolls into view (intersect once, so the hidden copy of the sidebar on the other breakpoint does not load); AjaxCalendarController::availabilityAction, template AjaxCalendar/Availability.html, month select calendar_controller.js.
  • All months in one response; the select only switches between them. 12 months from the current one, extended to the last month MyE&P has data for.
  • Months with prices are left out: they are summer, covered by the price calendar. Only summer months have prices today; that is the whole distinction. If contingents/calendar fails, all months are shown (not cached).
  • Colours as on TYPO3 10: green available (OK, and days without data), yellow on request (ON_REQUEST), red not available (BLOCKED), past days grey; a status change from the previous day is drawn as a diagonal. The availability-* classes are built in PHP, so they are safelisted in tailwind.config.js; without that Tailwind purges them.
  • Works for every hotel MyE&P syncs, with or without an accommodation (see below).

iCal feed

  • IcalController::contingentsAction, IcalService; route /contingents/{hotel}.ical on the ep-reisen site (config/sites/ep-reisen/config.yaml, page 9, type 1710), {hotel} is the hotel's path segment. The feed shows the record's Kalender-Code; without one it answers 404.
  • One Unavailable event per run of BLOCKED or ON_REQUEST days with the same status, as on TYPO3 10.
  • Never cached. When MyE&P has no availability it answers 503 with Retry-After: 900 instead of an empty calendar, which the portals would read as "every day free"; they keep their last import.

Which hotels MyE&P has availability for

MyE&P syncs its snapshot from bpn-connect every 15 minutes during the day and hourly at night, for the calendar codes of its accommodations plus every code in TYPO3's /api/calendar-hotels (see cms-api.md), which lists the Kalender-Code of every visible hotel record. So a hotel offered only in winter needs nothing in MyE&P: giving the record a Kalender-Code is enough; it is synced with the next run.

contingents/availability answers:

  • 400 for a code that is not synced (not an accommodation, not in TYPO3's list),
  • 502 when the hotel's snapshot is missing or older than 6 hours (sync failing),
  • 200 with one entry per known day otherwise.

contingents/calendar and contingents/prices additionally need an accommodation with prices.

MyE&P's GET /api/contingents/status lists every synced code with its source, prices, last sync and last error: the first place to look when a calendar does not load.

Caching

  • The AJAX responses (price calendar, price tables, Belegungskalender) are page-cached on the AJAX page for at most 1 hour (cache_period = 3600) and never past midnight (cache_clearAtMidnight, past days must turn grey). Browsers do not cache them (sendCacheHeaders = 0).
  • Errors are not cached (disablePageCache()): the next visitor triggers a new attempt.
  • Every AJAX URL carries a cHash (required for tx_epproducts_ajax), so each hotel and year has its own cache entry.
  • Entries are tagged ep_hotel_<code>. Nothing flushes them automatically; a deploy flushes all caches. To refresh by hand: vendor/bin/typo3 cache:flush --group pages, or flush the tag via the CacheManager for a single hotel.
  • On top of that comes MyE&P's sync interval, so a calendar is at most about 1¼ hours behind bpn-connect.

When a calendar does not load

The message is "Der Kalender konnte aktuell nicht geladen werden."; the iCal feed answers 503.

Cause How to tell Fix
No calendar at all product's "Kalender anzeigen" off, or the shown hotel has no Kalender-Code tick it / set the Kalender-Code of the hotel the page shows
Kalender-Code is not a BusPro code (…GRP, …SO) MyE&P 400, bpn-connect 404 set the house's BusPro code as Kalender-Code
Code not synced by MyE&P not in contingents/status; MyE&P 400 check that the hotel record is visible (then its code is in /api/calendar-hotels)
Sync failing for the hotel contingents/status: available: false, lastError MyE&P / bpn-connect
MyE&P unreachable or its OAuth failing all hotels fail; TYPO3 log EP.EpProducts.MyEP.ApiClient MyE&P
Price calendar only: no accommodation or no prices MyE&P 400 / empty prices are maintained in MyE&P's Groups admin

TYPO3 logs every failed MyE&P call in var/log/typo3_*.log (component EP.EpProducts.MyEP.ApiClient, for the iCal feed also EP.EpProducts.Service.IcalService).