srhinow / beekeeping-manager-bundle

2.4.1 2026-10-08 19:34 UTC

Requires

• php: ^8.2
• bacon/bacon-qr-code: ^2.0.8 || ^3.0
• contao/core-bundle: ^5.3
• doctrine/dbal: ^3.6 || ^4.0
• menatwork/contao-multicolumnwizard-bundle: ^3.5
• symfony/http-client: ^6.4 || ^7.0
• symfony/rate-limiter: ^6.4 || ^7.0
• symfony/security-bundle: ^6.4 || ^7.0
• symfony/uid: ^6.4 || ^7.0
• tecnickcom/tcpdf: ^6.2

Requires (Dev)

• contao/manager-plugin: ^2.0
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^10.5 || ^11.5
• symfony/yaml: ^6.4 || ^7.0

Conflicts

• contao/manager-plugin: <2.0 || >=3.0

LGPL-3.0-or-later

• Sven Rhinow

• manager
• bee
• contao
• beehive
• beekeeping

Published on Packagist.org on 2026-10-08 17:46 UTC

README

Imkerei-Verwaltung für das Contao-Backend: Standorte, Bienenvölker, Beuten, Stockkarten, Material, Wetter und frei pflegbare Auswahllisten.

Voraussetzungen

• PHP ^8.2
• Contao ^5.3
• menatwork/contao-multicolumnwizard-bundle ^3.5

Funktionen

• Standorte mit Geokodierung der Adresse über LocationIQ und der Anzahl lebender Völker
• Bienenvölker je Standort (Beute, Rasse, Zeichnungsfarbe, Abstammung, Bild)
• Stockkarte je Volk, je Standort oder gesamt. Eintragsarten: Bemerkung, Bewertung, Futter, Waben, Material, Medikament, Standortwechsel und Status. Ist keine eigene Bemerkung eingetragen, wird die Beschreibung automatisch erzeugt. Einträge lassen sich für mehrere Völker zugleich anlegen.
• Export der Stockkarte eines Volkes als CSV oder PDF (TCPDF), optional nach Jahr gefiltert
• Wetter am ersten Standort mit Koordinaten: aktuelle Werte und 5-Tage-Vorhersage über OpenWeatherMap
• Einstellungen: Auswahllisten, Beuten, Rähmchenmaße und Material-Kategorien
• REST-API für eine Imker-App (offline-fähig): Abgleich von Standorten, Beuten, Völkern und Stockkarte, Schreiben von Völkern und Stockkarten-Einträgen, Anmeldung per Token
• Imker-App (PWA) unter /bkm/app/: Völker und Stockkarte am Bienenstand pflegen, auch ohne Netz. Installierbar auf Handy und Desktop
• QR-Codes pro Beute: A4-Bogen mit Etiketten zum Aufkleben (Einstellungen → Beuten oder Standort → Völker). Gescannt öffnet die App das Volk in der Beute oder bietet an, darin ein neues Volk anzulegen

Konfiguration

Die API-Schlüssel kommen aus Umgebungsvariablen (z. B. .env.local):

LOCATIONIQ_API_KEY=…
OPENWEATHERMAP_API_KEY=…

Fehlt ein Schlüssel, entfällt nur die jeweilige Funktion. Das Backend meldet das, statt abzubrechen.

Die QR-Codes der Beuten enthalten die Adresse der App. Ohne weitere Angabe nimmt das Backend seine eigene Adresse. Ist Contao von außen unter einer anderen Adresse erreichbar (z. B. hinter einem Proxy), diese setzen:

BKM_APP_URL=https://example.org

API für die Imker-App

Die API liegt unter /bkm/api/v1 und ist in docs/openapi.yaml beschrieben. Eine Postman-Collection zum Ausprobieren liegt unter docs/postman/.

• Zugang: Unter Einstellungen → App → App-Zugänge einen Zugang anlegen und „Koppeln“. Das Backend zeigt das Token einmalig als QR-Code und Text. Alternativ meldet sich die App mit POST /bkm/api/v1/login (Benutzername, Passwort, ggf. Zwei-Faktor-Code) an. Jede weitere Anfrage schickt Authorization: Bearer <token>.
• Rechte: Die App arbeitet als der Backend-Benutzer des Tokens. Nötig ist das Recht auf das Modul „Standorte“.
• Abgleich: GET /bootstrap beim ersten Start, danach GET /sync?since=<cursor> für Änderungen und POST /sync für die Vorgänge der App. Es gelten dieselben Speicherregeln wie im Backend.
• Protokoll: Logins und Abgleiche stehen im Contao-System-Log.

Imker-App

Die App liegt unter https://<domain>/bkm/app/ und braucht HTTPS. Gekoppelt wird sie über den QR-Code im Backend (oder „App auf diesem Gerät öffnen“), alternativ per Login. Sie hält eine Kopie der Daten in IndexedDB vor. Änderungen landen in einer Outbox und werden übertragen, sobald es Netz gibt. Ein Service Worker hält die App selbst offline verfügbar.

Die QR-Etiketten der Beuten führen auf /bkm/app/beute/<uuid>. Die App öffnet dort das Volk in der Beute; ist die Beute frei, bietet sie „Neues Volk in dieser Beute“ an. Über „+“ → „QR-Code scannen“ liest die App die Codes auch selbst. Das braucht man auf dem iPhone: Dort öffnet die Kamera-App den Link in Safari und nicht in der installierten App.

Die Quellen liegen in assets/app/ (Vue 3, Vite, Pinia, Dexie, vite-plugin-pwa). Der fertige Build liegt in public/app/ und wird mitversioniert, damit eine Installation kein Node braucht. Nach Änderungen an der App:

docker run --rm -u $(id -u):$(id -g) -e npm_config_cache=/tmp/npm -v "$PWD":/b -w /b/assets/app node:22-alpine \
    sh -c 'npm ci && npx vitest run && npm run build'

Die Tabellen haben dafür eine Spalte uuid. Die Migration vergibt sie beim contao:migrate an bestehende Datensätze.

Tests

composer update
vendor/bin/phpunit -c phpunit.xml.dist
vendor/bin/phpstan analyse

Die GitLab-CI (.gitlab-ci.yml) führt Syntaxprüfung, PHPUnit und PHPStan zweimal aus: mit den niedrigsten erlaubten Abhängigkeiten auf PHP 8.2 (Contao 5.3, Symfony 6.4, DBAL 3.6) und mit den höchsten auf PHP 8.5. Ein dritter Job prüft docs/openapi.yaml mit Redocly. Der Job app testet die Imker-App und prüft, dass public/app zum Quelltext passt.