ks-nossenerland-bundle/README.md

mummert/ks-nossenerland-bundle

Contao-Bundle fuer projektspezifische Erweiterungen rund um Veranstaltungen im Kirchspiel Nossener Land.

Ziel dieses Bundles ist die Kapselung bestehender, produktiver Logik (ohne fachliche Aenderung) als installierbares Paket.

Funktionsueberblick

Das Bundle erweitert vor allem die Event-Verwaltung und den Event-Output in Contao:

• DCA-Erweiterung fuer tl_calendar_events (zusatzliche Felder, Palettenanpassung, Callback fuer Aliasbildung)
• Template-Hooks zur Anreicherung von Event-, Orts- und Angebotsdaten
• iCal-Hook zur Anpassung von VEvent-Daten
• CLI-Commands fuer
  • Export von Events zum EVLKS-Kalender (SOAP + Aufraeumen nicht mehr vorhandener Eintraege)
  • Export von Events in eine JSON-Datei fuer externe Nutzung

Technische Bestandteile

1) DCA-Anpassungen fuer Kalender-Events

Datei: contao/dca/tl_calendar_events.php

• Fuegt u. a. Felder hinzu:
  • catalog_ort
  • catalog_kontakt
  • catalog_pfarrbereiche
  • godi_options
  • subtitle
  • contributors
  • evlkscalendar
  • export
  • external_location
• Passt Paletten an (Legenden/Felder) und entfernt Standard-Location-Felder aus der Default-Palette.
• Aktiviert Alias-Neuaufbau ueber onsubmit_callback.

2) Alias-Bildung fuer Events

Datei: src/EventListener/CalendarAliasListener.php

• Erzeugt beim Speichern eines Events einen sprechenden Alias aus:
  • Eventtitel
  • Ortstitel (ctlg_orte)
  • Datum
• Nutzt Transliterations-/Kuerzungslogik und sorgt fuer Eindeutigkeit durch Suffix -1, -2, ...

3) Backend-Listing/Options-Callbacks

Datei: src/DataContainer/CalendarEvents.php

• Formatiert Kinddatensaetze im Event-Backend-Listing.
• Liefert Select-Optionen aus:
  • ctlg_orte
  • ctlg_contacts
  • ctlg_districts

4) Template-Hooks (parseTemplate)

Dateien:

• src/EventListener/EventFullListener.php
  • Reichert event_full um Ort, Alias, Koordinaten, District-Informationen an.
• src/EventListener/EventJsonDataListener.php
  • Laedt JSON aus https://ics.mummert.dev/kirchenjahr.json und injiziert passenden Datensatz nach Datum in event_full und event_upcoming_all.
• src/EventListener/OfferListener.php
  • Reichert Angebots-/Kontakt-Templates (cm_master_angebote, cm_master_contacts, cm_listing_angebote) mit Gemeinde-/District-Daten an.
• src/EventListener/PlaceListener.php
  • Reichert Orts-Listing (cm_listing_orte) mit Gemeinde-IDs und District-Aliases an.

5) iCal-Anpassung

Datei: src/EventListener/ModifyIcalDataListener.php

Hook: editVEvent

• Setzt/normalisiert iCal-Felder wie DTSTART, DESCRIPTION, LOCATION, GEO, ORGANIZER.
• Verarbeitet Kontakt- und Mitwirkendeninformationen aus Eventfeldern.

6) Event-Export zum EVLKS-Kalender

Dateien:

• src/Command/ExportEventsCommand.php
• src/Service/SoapClientService.php

Command: nossener-land:export-events

Ablauf:

1. Holt zukuenftige Events aus tl_calendar_events (derzeit pid IN (1,2,3) und evlkscalendar != 1).
2. Mappt Eventdaten fuer EVLKS (inkl. Place-Mapping, Eventtyp, Personen/Kontakt, Zeiten).
3. Exportiert per SOAP.
4. Holt Remote-Events per JSON (vid) und loescht externe Events, die lokal nicht mehr im Exportlauf enthalten sind.

Hinweis:

• Das Place-Mapping ist statisch in SoapClientService hinterlegt.
• Der SOAP-Zugang ist aktuell in config/services.yml konfiguriert.

7) JSON-Export fuer Website/Consumer

Datei: src/Command/ExportEventsJsonCommand.php

Command: nossener-land:export-eventstojson

Ablauf:

1. Liest Events mit export=1 AND published=1.
2. Wandelt singleSRC UUID in absolute URL um.
3. Vergibt bei Bedarf Alias.
4. Schreibt JSON nach:
   • /srv/www/ks-nossener-land/public/kirchspiel-nossener-land.de/public/events.json

Voraussetzungen

• Contao 5.7
• PHP >= 8.3
• Tabellen aus dem Umfeld von Catalog Manager, u. a.:
  • ctlg_orte
  • ctlg_contacts
  • ctlg_gemeinden
  • ctlg_districts
  • ctlg_angebote
• Netzwerkzugriff auf:
  • EVLKS SOAP/JSON Endpunkte
  • JSON-Quelle ics.mummert.dev

Console-Commands (manuell)

Im Contao-Projektverzeichnis ausfuehren:

php bin/console nossener-land:export-events
php bin/console nossener-land:export-eventstojson

Cronjobs

Die folgenden Beispiele sind direkt anwendbar. Pfade bitte auf das jeweilige Projekt anpassen.

A) EVLKS-Export (inkrementell, inkl. Aufraeumen)

Empfohlenes Intervall: alle 15 Minuten.

*/15 * * * * cd /srv/www/contao57 && /usr/bin/flock -n /tmp/ks-nossenerland-export-events.lock php bin/console nossener-land:export-events --env=prod --no-interaction >> var/log/cron-export-events.log 2>&1

Warum 15 Minuten:

• gute Balance zwischen Aktualitaet und Last
• robust bei redaktionellen Aenderungen waehrend des Tages
• vermeidet zu haeufige externe API-Aufrufe

Alternative Intervalle:

• alle 5 Minuten: wenn sehr zeitkritische Publikation noetig ist
• alle 30 Minuten: wenn Last reduziert werden soll

B) JSON-Export fuer externe Anzeige

Empfohlenes Intervall: alle 30 Minuten.

*/30 * * * * cd /srv/www/contao57 && /usr/bin/flock -n /tmp/ks-nossenerland-export-json.lock php bin/console nossener-land:export-eventstojson --env=prod --no-interaction >> var/log/cron-export-json.log 2>&1

Warum 30 Minuten:

• Daten aendern sich typischerweise weniger haeufig als EVLKS-Sync-Anforderungen
• reduziert I/O und Dateischreiblast

Alternative Intervalle:

• stuendlich: fuer sehr geringe Aenderungsfrequenz
• alle 10-15 Minuten: wenn JSON als nahezu Live-Feed genutzt wird

C) Startzeiten staffeln

Empfehlung fuer stabilen Betrieb:

• EVLKS-Export auf Viertelstunden
• JSON-Export zeitversetzt, z. B. Minute 7 und 37

Beispiel:

*/15 * * * * cd /srv/www/contao57 && /usr/bin/flock -n /tmp/ks-nossenerland-export-events.lock php bin/console nossener-land:export-events --env=prod --no-interaction >> var/log/cron-export-events.log 2>&1
7,37 * * * * cd /srv/www/contao57 && /usr/bin/flock -n /tmp/ks-nossenerland-export-json.lock php bin/console nossener-land:export-eventstojson --env=prod --no-interaction >> var/log/cron-export-json.log 2>&1

Empfohlene Betriebsregeln

• Immer flock nutzen, um Ueberlappungen bei langen Laufzeiten zu verhindern.
• Ausgabe in getrennte Logdateien schreiben.
• Nach Deployment einmal manuell beide Commands ausfuehren.
• Bei API-Problemen zuerst Logs pruefen und dann betroffene Command-Intervalle temporaer erhoehen.

Bekannte projektbezogene Punkte (kein Bugfix in diesem Schritt)

• In ExternalLocationModel sind externe DB-Zugangsdaten fest hinterlegt.
• ExportEventsJsonCommand nutzt einen fest codierten Zielpfad fuer events.json.
• SOAP-API-Zugangsdaten liegen aktuell in config/services.yml.

Diese Punkte sind bewusst unveraendert geblieben (Ziel: keine Funktionsaenderung beim Bundle-Umbau).