# 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` ## Konfiguration per Environment-Variablen Die folgenden Variablen werden fuer produktiven Betrieb erwartet: - `KS_NOSSENERLAND_SOAP_WSDL_URL` - `KS_NOSSENERLAND_SOAP_ENDPOINT_URL` - `KS_NOSSENERLAND_SOAP_API_KEY` - `KS_NOSSENERLAND_SOAP_VID` - `KS_NOSSENERLAND_KIRCHENJAHR_JSON_URL` (optional, Default vorhanden) - `KS_NOSSENERLAND_EXTERNAL_DB_DSN` - `KS_NOSSENERLAND_EXTERNAL_DB_USER` - `KS_NOSSENERLAND_EXTERNAL_DB_PASSWORD` Beispiel DSN: ```text mysql:host=localhost;dbname=nossener-land_1;charset=utf8mb4 ``` ## Console-Commands (manuell) Im Contao-Projektverzeichnis ausfuehren: ```bash 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. ```cron */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. ```cron */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: ```cron */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).