example-plugin, Namespace QuickTribePlugin\ExamplePlugin) – mit Quellen, Tests, Übersetzungen und der gebauten Oberfläche (dist/).
Dasselbe Plugin liegt dem Auslieferungspaket unter plugins/example-plugin/ bei – inaktiv und sofort aktivierbar (Variante Docker Compose, siehe Plugins installieren). Wer es nicht braucht, löscht den Ordner.
Was es tut
- Menüpunkt „Mitbringen“ in der Community: führt auf die Seite „Mitbringliste“ mit den eigenen Einträgen für kommende Termine, einer Einleitung des Teams und dem Hinweis, wie viele Sachen je Termin erlaubt sind.
- Termin-Ansicht im Kalender: Neben den Angaben zum Termin steht seine Mitbringliste. Mitglieder tragen ein, was sie mitbringen (mit Menge), und entfernen eigene Einträge; wer zugesagt hat, sieht zusätzlich einen Zugangscode des Teams (etwa für Tür oder WLAN). Wer den Termin verwaltet, lädt die Liste als CSV oder PDF und erinnert mit Ohne Eintrag erinnern alle Zusagenden ohne Eintrag. Nach dem Ende des Termins ist die Liste geschlossen.
- Kalenderliste: Jede Karte zeigt, wie viele Einträge die Liste des Termins hat.
- Abgesagte Termine: Sagt das Team einen Termin ab (oder wird er abgesagt, weil die Mindestteilnehmerzahl nicht erreicht ist), ruht seine Mitbringliste: Die Einträge bleiben stehen, Neues und „Ohne Eintrag erinnern“ gibt es so lange nicht, im Termin steht ein Hinweis. Findet der Termin doch statt, gilt alles wieder.
- Benachrichtigungen: Nach einer Zusage kommt die Glocke „Was bringst du mit?“; über jeder Seite der Community erinnert ein Hinweis an eigene Einträge für die nächsten zwei Tage.
- Zusatzangaben: Im Event-Editor gibt es ein Feld „Hinweis zur Mitbringliste“, im Profil die freiwillige Angabe „Ernährung“, die nur die Person selbst und das Team sehen.
- Datenschutz: Einträge werden 30 Tage nach dem Ende des Termins gelöscht; der Datenexport enthält sie, eine Kontolöschung entfernt sie.
- Kursseite: Hat ein Kurs Live-Termine, zeigt seine Seite zu jedem die Zahl der Einträge auf der Mitbringliste.
- E-Mail-Serien: Der Platzhalter
{example-plugin.items}nennt in Serien mit Auslöser „Event-Zusage“, was die Person zum Termin eingetragen hat. - Formulare: Der Feldtyp „Ernährung“ fragt in Anmeldeformularen vegetarisch, vegan oder ohne Einschränkung ab.
Was es zeigt
Nicht im Beispiel – beschrieben in den übrigen Kapiteln:
- Eingaben im Event-Editor (
EventInputExtension, Slotcalendar.event.editor.fields), siehe Erweiterungen von Kern-Antworten; - E-Mails mit eigener Vorlage (
mailer(),templates/email/), siehe E-Mails; - Dateien:
storage(), Uploads,Response::streamund XLSX, siehe Speicher und Response; Lifecycleund die Prüfung von Einstellungen über Felder hinweg (settingsValidator), siehe Lebenszyklus und Einstellungen;- Menüpunkte im Benutzermenü und im Plattform-Admin sowie Seiten und Endpunkte ohne Community, siehe Menüpunkte;
- Erweiterungen und Slots für Mitglieder, Leaderboard, Beiträge und Lektionen, siehe Slots;
- Eingaben an Beitrag, Kurs und Lektion (
InputExtension), der Filter der Rangliste und Landingpage-Bausteine, siehe Filter-Hooks; state(),cache()undlimiter(), siehe Einstellungen und Übersetzung, Adressen, Limits, Cache.
Dateien
src/ExamplePlugin.php – alle Erweiterungspunkte stehen in register(), die Arbeit machen kleine Klassen:
Muster zum Übernehmen
-
Sichtbarkeit in jedem Handler: Vor jeder Antwort prüft der Handler, ob der Betrachter das Event sehen darf (
events()->viewable()); fremde, gesperrte und unbekannte Events ergeben gleichermaßen404. CSV, PDF und Erinnerung gibt es nur für Personen, die den Termin verwalten (events()->canManage()). -
Obergrenze auch bei gleichzeitigen Anfragen: Zählen und Einfügen laufen in
db()->transactional(), gezählt wird sperrend (SELECT … FOR UPDATE); bricht die Datenbank eine von zwei gleichzeitigen Transaktionen ab (RetryableException), versucht es der Handler erneut. -
Oberfläche und Server einig: Ob jemand eintragen, entfernen oder erinnern darf, liefert der Server mit (
canAdd,canRemove,canRemind); die Oberfläche zeigt Knöpfe nur danach. Gegen Wettläufe verwerfen Seite und Slot veraltete Antworten über einen Zähler je Ladevorgang. -
Vorschau-Events (ab Plugin-API 1.3): An einer Vorschau (
draft, ausevents()->occurrence()) nimmt die Liste keine Einträge an (409,canAdd/canRemindfalsch) – zusagen kann dort noch niemand. Die Hooks kommen trotzdem wie bei jedem Event, Einträge eines zurückgestellten Events ziehen mit und verschwinden mitevent.deleted. -
Abgesagte Termine (ab Plugin-API 1.9): „Abgesagt“ ist ein Zustand des einzelnen Termins, den der Kern zurücknehmen kann – Zusagen bleiben bestehen. Das Plugin löscht deshalb nichts und speichert den Zustand nicht selbst:
ItemsApifragt bei jedem Zugriffevents()->isCancelled()(Listen: einmalcancelledKeys()), lehnt Eintragen und Erinnern mit409ab und liefertcancelledfür den Hinweis im Slot; Entfernen bleibt möglich.event.cancelledzieht nur die eigenen offenen Glocken zurück (forget()),event.reinstatedhat nichts zu reparieren. Eigene Glocken zu Absage und Rücknahme verschickt das Plugin nicht – der Kern benachrichtigt alle Zusagenden und Wartenden schon per Glocke, Push und E-Mail: -
Verschobene Termine: Der Kern verschiebt keine Daten der Plugins.
event.updatedmitscheduleChangedzieht die Einträge eines Einzeltermins auf den neuen Beginn um und löscht bei Serien die Einträge entfallener Termine (occurrenceExists()). -
Erinnerungen nur an Berechtigte, und so, dass sie ankommen: Die Aufgabe prüft je Person einen Viewer (
members()->viewerFor(),canWrite,events()->lockReason()) und ersetzt die ungelesene Glocke „Was bringst du mit?“ mitforget(), bevor sie ohnecollapseerinnert: -
Einzahl und Mehrzahl als eigene Texte statt ICU-Plural, in PHP mit
match, in Vue mit einer Bedingung (siehe Übersetzungen). - Kurze Beschriftungen im Menü: Menüpunkte stehen neben denen von QuickTribe; „Mitbringen“ ist kurz und verwechselt sich mit keinem Punkt der Plattform.
Ausprobieren
Auf einer Installation (Betreiber und Plattform-Admins):- Im Auslieferungspaket für Docker Compose liegt das Plugin schon unter
plugins/example-plugin/. Bei Portainer, Coolify und ohne Docker die ZIP-Datei entpacken und den Ordnerexample-pluginwie unter Plugins installieren ablegen – mit den Rechten von dort. Fehlt im Ordner das gebautedist/, nehmen Sie die Fassung aus dem Auslieferungspaket. - Unter Plattform-Admin → Plugins die Mitbringliste (Beispiel-Plugin) aktivieren – oder auf der Konsole
php bin/console app:plugin:enable example-plugin. - In einer Community unter Einstellungen → Plugins einschalten – oder
php bin/console app:plugin:enable example-plugin --community=<slug>. - Einen kommenden Termin im Kalender öffnen und etwas eintragen. Die Einstellungen der Community öffnet unter Einstellungen → Plugins der Link Einstellungen beim Plugin; die plattformweiten stehen auf seiner Detailseite unter Plattform-Admin → Plugins.
plugins/example-plugin/. Die Demo-Daten (php bin/console app:fixtures:load) schalten es plattformweit und in der Community demo ein; die Oberfläche lädt dort ohne Build direkt aus frontend/. Bauen und testen:
Als Vorlage verwenden
- Ordner kopieren und umbenennen – der Ordnername ist die neue Plugin-ID (siehe Namensregeln).
- In
plugin.jsonid,name,namespace(QuickTribePlugin\<Name>) undentryanpassen,versionauf0.1.0setzen; in allen PHP-Dateien – auch untertests/– den NamespaceQuickTribePlugin\ExamplePluginersetzen. - In
migrations/die Tabelle umbenennen:plg_<id>__…, dabei wird-in der ID zu_. Den Tabellennamen in den Indexnamen ebenfalls ersetzen. - Im Frontend
PLUGIN_IDinfrontend/extra.tssetzen und das Literal'settings.plugin.example-plugin'inSettingsInfo.vuean die neue ID anpassen; in den Tests die KonstantenIDundTABLEund im Playwright-SzenarioPLUGIN. dist/löschen, nicht benötigte Teile entfernen, neu bauen (npm run build:plugins <id>),php bin/console app:plugin:validate plugins/<id>und die Tests laufen lassen.