Mit Hooks reagiert ein Plugin auf Ereignisse in QuickTribe – etwa einen Beitritt, eine Zusage zu einem Event oder eine eingezogene Forderung:
on() nimmt nur Namen aus dem Katalog (Hook::…->value oder den Text, z. B. 'event.rsvp'); ein unbekannter Name wirft InvalidRegistration. Ein HookEvent liefert name(), communityId() (nur bei account.deleted null), data(), occurredAt() (Zeitpunkt der Aufzeichnung, UTC) und isCleanup().

Zustellung

  • Nach dem Speichern. Der Kern zeichnet einen Hook in derselben Transaktion auf, in der er die Änderung speichert, und stellt ihn erst nach dem Commit zu – in einem Request, nachdem die Antwort an den Browser gegangen ist, auf der Konsole am Ende des Befehls, im Worker als eigener Auftrag im Plugin-Prozess. Wird die Transaktion zurückgerollt, entfällt der Hook. Der HTTP-Status der Antwort spielt keine Rolle: Gespeichert ist gespeichert.
  • Empfänger sind Plugins, die plattformweit aktiv und in der betroffenen Community eingeschaltet sind; die adressierten Hooks claim.* gehen nur an das meldende Plugin (siehe Forderungen). Aufräum-Hooks (member.left, event.deleted, account.deleted, isCleanup() = true) gehen an alle plattformweit aktiven Plugins – auch an solche, die in der Community gerade ausgeschaltet sind.
  • Höchstens einmal, ohne Wiederholung, in der Reihenfolge der Aufzeichnung. Listener müssen deshalb idempotent sein, und Plugins gleichen ihre Daten zusätzlich mit einem täglichen Job ab – über die Communities ihrer eigenen Tabellen, nicht nur die eingeschalteten (siehe Abgleich und Löschfristen).
  • Folge-Hooks, die ein Listener auslöst (etwa über members()->endMembership()), laufen in der nächsten Runde; nach drei Runden verwirft der Kern weitere mit einer Warnung.
  • Fehler eines Listeners stehen im Log (plugin.<id>.hook_failed); der nächste Listener läuft trotzdem. Braucht ein Listener länger als 2 Sekunden, gibt es eine Warnung; im Worker endet ein Listener spätestens nach 120 Sekunden Rechenzeit.

Katalog

Alle IDs sind UUID-Strings, Zeitpunkte Text im Format Y-m-d\TH:i:s\Z (UTC). Die Daten enthalten immer genau die genannten Schlüssel; „oder null“ steht dabei, wo ein Wert fehlen kann.

Werte

Regeln

  • membershipId bleibt stabil je Person und Community, auch bei einem Wiedereintritt (rejoin = true).
  • Der Kern verschiebt keine Zusagen. Nach event.updated mit scheduleChanged prüft das Plugin seine Termine mit events()->occurrenceExists(). Einzeltermine darf es auf den neuen Beginn umziehen (Versatz = changes.startsAt.after − before); Termine einer Serie, die es nicht mehr gibt, gelten als entfallen. Vergleiche mit dem Ende einer Serie immer gegen recurrenceEnd.
  • Warteliste: Ein Wartelistenplatz löst keinen Hook aus; erst das Nachrücken (event.rsvp mit via: promoted).
  • Vorschau (Entwurf, ab 1.3): Events kommen mit allen Hooks wie jedes andere – event.created schon beim Anlegen mit draft: true, event.updated bei jeder Änderung (Veröffentlichen und Zurückstellen als changes.draft), event.deleted immer. Das Plugin entscheidet selbst anhand von draft: An einer Vorschau gibt es keine Zusagen, Wartelistenplätze oder Tickets; Glocken, Mails oder Angebote, die eine Zusage voraussetzen, gehören erst zum veröffentlichten Event. events() liefert draft an EventInfo, EventDraft und Occurrence – an einem selbst gebauten Occurrence (eigener Konstruktor-Aufruf) ist draft nicht verlässlich, maßgeblich ist events()->occurrence() bzw. events()->get(). Die Slots calendar.event.detail.aside und calendar.list.card.footer erscheinen bei einer Vorschau nicht, der Editor-Slot schon; extra (Zusatzfelder, validate(), store()) läuft wie bei jedem Event.
  • Kontolöschung: Zuerst kommen member.left mit account_deleted je Mitgliedschaft und account.deleted, danach ruft der Kern PrivacyAware::deleteUserData() (siehe Datenschutz). So können Listener Betroffene – etwa Mitfahrer – noch benachrichtigen, bevor die Daten verschwinden.
  • Moderation: Die Hooks folgen dem Wechsel des Status – eine Sperre ist member.left mit banned, das Aufheben member.unbanned; Freigabe member.approved, Ablehnung member.left mit rejected.
  • Aufräum-Hooks erreichen auch Plugins, die in der Community ausgeschaltet sind: Ein Plugin räumt so seine Daten auf, selbst wenn der Owner es vorübergehend ausgeschaltet hat.
  • Beiträge (ab 1.2): Geburtstags-Einträge lösen keine post.*-Hooks aus, Kommentare darunter kein comment.created. Hooks enthalten nie Inhalte – weder Text noch Antworten noch Kommentare –, nur IDs, Zustände und den Titel offener Beiträge.
  • Titel nie ungeprüft an Mitglieder ausgeben. Auch ein offener Beitrag (restricted: false) kann später in eine gesperrte Kategorie wandern oder gelöscht werden. Wer Titel speichert und anzeigt, zeigt sie nur Personen, die den Beitrag selbst sehen dürfen, und aktualisiert bzw. entfernt sie bei post.updated und post.deleted.
  • Abgesagte Termine (ab 1.9): Eine Absage entfernt keine Zusagen – es kommt kein event.rsvp_cancelled und kein duty.released, und events()->isGoing(), goingKeys() und attendees() liefern die Zusagen weiter. Solange der Termin abgesagt ist, nimmt der Kern für ihn keine Zusagen, Wartelistenplätze, Dienst-Slots und Check-ins an (also auch kein event.rsvp, duty.booked, event.checked_in), verschickt keine Erinnerungen und vergibt weder Punkte noch Dienst-Einträge; Schritte einer E-Mail-Serie entfallen (sequence.step_sent mit emailed: false). Dein Plugin sollte es genauso halten: für abgesagte Termine nichts erinnern und nichts Neues anbieten, Vorhandenes aber behalten – nach event.reinstated gilt alles wieder. Die Angemeldeten benachrichtigt der Kern selbst (Glocke, Push und eine E-Mail, die sich nicht abschalten lässt), bei Absage und Rücknahme. Den Zustand liest das Plugin mit events()->isCancelled() bzw. cancelledKeys(); reason ist Text des Teams und wird nur escaped ausgegeben.
  • Dienste (ab 1.6): Ein Slot an einer bestehenden Zusage löst duty.booked, aber kein event.rsvp aus; duty.released mit slot_released lässt die Zusage bestehen. duty.completed kommt je Mitgliedschaft und Termin höchstens einmal – auch wer Dienst-Event und Slot zugleich hat, bekommt einen Eintrag (source: slot). Den Stand liest das Plugin über duties(). Mit Bestätigung durch das Team (ab 1.9) kommt duty.completed erst mit der Bestätigung (oder wenn die Community die Bestätigung ausschaltet) – für wartende und abgelehnte Dienste gibt es keinen Hook, und weil ein bestätigter Dienst bestätigt bleibt, auch keinen Widerruf.
  • Formulare (ab 1.2): form.approved kommt nur für die Freigabe eines Formulars durch das Team; Beitritts- und Plan-Freigaben melden member.approved bzw. die Mitgliedschafts-Hooks.

Forderungen

Die Hooks claim.* (ab Plugin-API 1.1, siehe Forderungen und Lastschrift) sind adressiert: Sie gehen nur an das Plugin, das die Forderungen gemeldet hat (source), solange es plattformweit aktiv ist – auch wenn es in der Community ausgeschaltet ist –, und nie an andere Plugins. Forderungen der Kasse selbst lösen keine Hooks aus. Ein Hook bündelt alle Forderungen eines Laufs bzw. einer Aktion; das Plugin gleicht trotzdem regelmäßig über debits()->list() mit dem gespeicherten Cursor ab, weil Hooks höchstens einmal kommen.
  • Ein Hook je Lauf bzw. Aktion und Quelle: claim.collecting und claim.paid je Einzug, claim.returned, claim.settled und claim.cancelled je Aktion der Kasse bzw. des Plugins. Mehr als 200 Forderungen verteilt der Kern auf Folge-Hooks mit part 1 … parts.
  • Wer auslöst: Einzug ankündigen, als bezahlt markieren, Rücklauf erfassen, Einzug verwerfen, Einreichung zurücknehmen, ausgleichen und stornieren macht die Kasse; settleCash() und cancel() des Plugins lösen dieselben Hooks aus. Bei der Stripe-Lastschrift kommen claim.collecting (mit method: stripe) vom automatischen Lauf, claim.paid je Lastschrift, sobald Stripe den Eingang meldet (typisch sechs Bankarbeitstage nach dem Einzugstag), und claim.returned je Fehlschlag bzw. Rücklastschrift, die Stripe meldet. claim.reopened kommt, wenn Forderungen aus einem Einzug wieder offen werden:
    • Lauf verworfen (angekündigt oder Datei heruntergeladen) oder eine schon eingereichte Datei zurückgenommen, weil die Bank sie abgelehnt hat (run_cancelled); bei der Stripe-Lastschrift auch, wenn Stripe einen Einzug wegen eines Fehlers auf seiner Seite nicht ausführt (run_cancelled),
    • Mandat beendet oder Bankverbindung nach einer Rückgabe gesperrt (mandate_revoked) – nur Einzüge in noch nicht heruntergeladenen Läufen bzw. bei der Stripe-Lastschrift noch nicht bei Stripe eingereichte,
    • Konto gelöscht (account_deleted) – ebenso.
  • Rücklastschriftgebühr: feeClaimId in claim.returned ist eine Forderung der Quelle core – das Plugin sieht sie nicht über get(), kann sie aber anzeigen („zzgl. Gebühr“).
  • Einträge in claims liest man mit ClaimRef::fromArray():