srhinow / schwarmalarm-bundle
Möglichkeit Imker und Bienenschwarmfänger zu verwalten.
Maintainers
Package info
gitlab.com/srhinow/schwarmalarm-bundle
Type:contao-bundle
pkg:composer/srhinow/schwarmalarm-bundle
Requires
- php: ^8.3
- contao/core-bundle: ^5.7
- guzzlehttp/guzzle: ^7.0
Requires (Dev)
- contao/manager-plugin: ^2.0
- friendsofphp/php-cs-fixer: ^3.0
- phpunit/phpunit: ^11.5
README
Contao-Bundle zur Verwaltung von Imkern und Bienenschwarmfängern. Ermöglicht die Erfassung von Imker-Einträgen mit Geo-Koordinaten sowie die öffentliche Suche über PLZ/Ort mit Kartenansicht.
Voraussetzungen
| Abhängigkeit | Version |
|---|---|
| PHP | ^8.3 |
| Contao | ^5.3 |
| Guzzle HTTP | ^7.0 |
Installation
composer require srhinow/schwarmalarm-bundle
Nach der Installation:
php vendor/bin/contao-console contao:migrate
php vendor/bin/contao-console cache:clear
Backend-Module
Das Bundle fügt unter Schwarmalarm folgende Backend-Bereiche hinzu:
| Modul | Tabelle | Funktion |
|---|---|---|
| Imker | tl_schwarmalarm_beekeeper | Imker-Einträge verwalten, Geo-Koordinaten setzen, veröffentlichen |
| Einstellungen | tl_schwarmalarm_properties | API-Zugangsdaten, E-Mail-Benachrichtigung |
| PLZ-Koordinaten | tl_zip_coordinates | PLZ → Geo-Koordinaten-Mapping für die Autocomplete-Suche |
CSV-Export
Im Imker-Modul steht ein CSV-Export aller Einträge zur Verfügung (Button in der Kopfzeile der Liste).
Frontend-Module
| Modultyp | Beschreibung |
|---|---|
beekeeper_search_form | Suchformular mit PLZ/Ort-Autocomplete und Entfernungsauswahl |
beekeeper_search_list | Ergebnisliste der gefundenen Imker mit optionaler Entfernungsanzeige |
beekeeper_search_map | Leaflet-Kartenansicht der Suchergebnisse (OpenStreetMap) |
beekeeper_verify_link | Verifizierungsseite für Opt-out-Links per E-Mail |
Suchformular
Das Suchformular (beekeeper_search_form) speichert PLZ/Ort, Entfernung und ermittelte Geo-Koordinaten in der Contao-Session. Alle anderen Module lesen diese Session aus, sodass Formular und Ergebnisliste/Karte auf verschiedenen Seiten oder Seitenbereichen platziert werden können.
Die Autocomplete-Suche greift auf die tl_zip_coordinates-Tabelle zurück und liefert Vorschläge ab zwei eingegebenen Zeichen.
Schwarmzeit-Einschränkung
Die Ergebnisliste kann auf eine konfigurierbare Schwarmzeit eingeschränkt werden. Start und Ende werden im Backend-Modul als Datum im Format TT.MM (z. B. 01.04 für den 1. April) hinterlegt. Außerhalb der Saison zeigt das Modul einen Hinweistext statt der Ergebnisse.
Templates
Alle Frontend-Templates liegen als Twig-Dateien in contao/templates/ und können in der Contao-Templateverwaltung überschrieben werden:
| Template | Verwendung |
|---|---|
mod_beekeeper_search_form.html.twig | Suchformular |
mod_beekeeper_search_shortform.html.twig | Kompaktes Suchformular (alternative Auswahl) |
mod_beekeeper_search_list.html.twig | Ergebnisliste |
mod_beekeeper_search_map.html.twig | Kartenansicht |
mod_beekeeper_message.html.twig | Einzelne Statusmeldung |
mod_beekeeper_entries_empty.html.twig | Meldung bei leerer Ergebnisliste |
item_html_list.html.twig | Einzelner Tabelleneintrag in der Ergebnisliste |
Alle sichtbaren Texte in den Templates werden über Sprachdateien definiert (TL_LANG['MSC']['bk_*']) und sind in Deutsch und Englisch enthalten.
Sprachdateien
Das Bundle liefert vollständige Sprachdateien für Deutsch (de) und Englisch (en) für alle DCA-Tabellen sowie Frontend-Texte.
Notification Center — Insert Tags
Das Bundle stellt folgenden Insert Tag für das Notification Center bereit:
E-Mail-Verifizierung (beekeeper_verify_link)
Das Modul liest den URL-Parameter ?key=... aus, sucht den zugehörigen Imker-Eintrag und setzt bei Erfolg verified = 1. Sind darüber hinaus Geo-Koordinaten vorhanden (lat und lon ≠ 0), wird der Eintrag automatisch auf published = 1 gesetzt und erscheint damit in den Suchergebnissen.
Konfigurierbare Meldungen im Modul:
- Kein/ungültiger Key —
message_false_url - Eintrag nicht gefunden —
message_no_entry - Bereits verifiziert —
message_allready_verified - Weiterleitung — optionale
jumpTo-Seite nach erfolgreicher Verifizierung
Der Aktivierungslink wird über das Notification Center versendet. Der Verifikations-Key wird serverseitig bei der Formularabgabe über den prepareFormData-Hook generiert (bin2hex(random_bytes(16))) und steht in NC-Nachrichten als ##form_key## zur Verfügung:
{{link_url::PAGE_ID}}?key=##form_key##
{{beekeeper_edit_link::EMAIL}}
Erzeugt einen absoluten Backend-Deeplink zur Bearbeitung des Imker-Eintrags mit der angegebenen E-Mail-Adresse.
Verwendung in NC-Benachrichtigungen:
{{beekeeper_edit_link::##form_email##}}
Das NC ersetzt ##form_email## zuerst durch die tatsächliche E-Mail-Adresse, anschließend löst Contao den Insert Tag auf und gibt eine vollständige URL zurück, z. B.:
https://example.com/contao?do=tl_schwarmalarm_beekeeper&act=edit&id=42
Wird keine übereinstimmende E-Mail gefunden, gibt der Tag eine leere Zeichenkette zurück.
Services
| Service | Klasse | Funktion |
|---|---|---|
srhinow.schwarmalarm.service.beekeeper | BeekeeperService | Geo-Suche, Entfernungsberechnung, Schwarmzeit-Prüfung |
srhinow.schwarmalarm.service.osm_geodata | OsmGeoData | Nominatim-Abfrage für Adresse → Koordinaten |
srhinow.schwarmalarm.service.be_csv_export | BeCSVExport | CSV-Export der Imker-Tabelle |
Entwicklung
composer install
vendor/bin/phpunit
Lizenz
LGPL-3.0-or-later — siehe LICENSE.