Der PluginContext, den der Konstruktor der Einstiegsklasse bekommt, ist der einzige Weg zu Daten und Diensten von QuickTribe. Die Schnittstellen der Dienste liegen unter App\Plugin\Api\Service, die Modelle unter App\Plugin\Api\Model.

Regeln für alle Dienste

  1. Community zuerst. Jede Methode, die Daten einer Community liest oder ändert, nimmt die Community-ID als ersten Parameter und prüft die Zugehörigkeit jeder übergebenen ID selbst. Eine fremde ID ergibt null, eine leere Liste oder NotFound – nie fremde Inhalte.
  2. Gelöschte Communities verhalten sich wie fremde. Gesperrte liefern Daten (für Jobs und Aufräumen); communities()->enabledFor() und JobContext::communities() lassen sie aus – Abgleichs- und Löschjobs laufen deshalb über die Communities der eigenen Tabellen (siehe Abgleich und Löschfristen).
  3. Sichtbarkeit wie im Kern. Wo ein Viewer übergeben wird, liefert der Dienst höchstens, was diese Person in QuickTribe sehen darf. Rechte des Plugins erweitern das nie (einzige Ausnahme: members()->snapshotName(), protokolliert).
  4. Viewer erzeugt nur der Kern – über Request::viewer(), ExtensionQuery::viewer() oder members()->viewerFor() (für Jobs, Hooks und Aufgaben).
  5. GET ändert nichts. Schreibende Methoden werfen in GET-Handlern und Ausgabe-Rückrufen eine LogicException (siehe PHP-Schnittstelle).
  6. E-Mail-Adressen gibt kein Dienst heraus – Ausnahmen für Plugins mit privacy.memberEmails (protokolliert): ab Plugin-API 1.3 der Abgleich members()->verifiedEmail()/matchEmails(), ab 1.4 die Anzeige members()->loginEmails() für Owner und Admins; ab 1.8 darf ein solches Plugin Adressen ohne Konto über mailer()->sendToAddress() anschreiben; das volle Geburtsdatum nur members()->birthDates() an Owner und Admins (wie das Alter).

PluginContext

Plugin-API 1.2 bringt keine neuen Dienste, nur einen neuen Aufruf (members()->birthDates(), unten): Beiträge, Kurse, Lektionen, E-Mail-Serien, Landingpages und Formulare liest ein Plugin nicht direkt. IDs kommen aus den Hooks, eigene Angaben je Objekt gibt das Plugin über Erweiterungen aus (nur für Objekte, die der Betrachter sehen darf), und die Filter-Hooks bekommen alles, was sie brauchen, als Anfrage.

Communities

Mitglieder

MemberInfo enthält membershipId, userId, communityId, displayName, avatarUrl, role (Role::Member|Moderator|Admin|Owner), status (pending, active, muted, banned, left), joinedAt, profilePath, accountDeleted, badges, nameColor und canRead().

Einladungen

invites()->create($communityId, $actorUserId, int $maxUses = 1, ?\DateTimeImmutable $expiresAt = null, ?string $planId = null): InviteInfo legt einen Einladungslink an – mit denselben Rechten (Admin aufwärts) und demselben Protokoll wie in der Oberfläche; revoke($communityId, $inviteId, $actorUserId) zieht ihn zurück. InviteInfo liefert die absolute url. Plugins zeigen den Link an und geben ihn von Hand weiter – oder verschicken ihn ab Plugin-API 1.3 mit send(). Wer über den Link beitritt, erscheint im Hook member.joined mit inviteId. invites()->send($communityId, $actorUserId, string $email, ?string $recipientName = null, ?\DateTimeImmutable $expiresAt = null, string $locale = 'de'): ?InviteInfo (ab Plugin-API 1.3) legt einen Einladungslink für genau einen Beitritt an (Beitritt ohne Freigabe, Ablauf Standard 30 Tage, höchstens 365) und schickt ihn per E-Mail an die Adresse – auch an Personen ohne Konto. Der Text stammt immer vom Kern („… lädt dich ein, der Community … beizutreten“, de oder en); Plugins können ihn nicht ändern, damit sich die Funktion nicht zum Versand beliebiger Inhalte eignet. recipientName erscheint nur als Anrede. Rechte wie create() (Admin aufwärts). Grenzen: höchstens 3 Einladungen je Adresse und Community in 24 Stunden (darüber null; gezählt wird erst der Versand) und das Einladungs-Kontingent des Plugins (Standard 50 je Stunde und Community, getrennt von mailer()->send()) – ist es erschöpft, wirft send() TooManyRequests mit retryAfter(); das Plugin reiht den Rest ein und versucht es später (z. B. in einem Job). Wird ein Link nicht mehr gebraucht (neue Einladung, Datensatz gelöscht), zieht das Plugin ihn mit revoke() zurück. Protokoll invite.mailed mit gekürzter Adresse.

Events

Ein Occurrence hat eventId, start, end, draft (Termin einer Vorschau, ab 1.3 – nur an Terminen aus events() verlässlich, nicht an selbst gebauten) und key() = <eventId>|<Y-m-d\TH:i:s\Z> – derselbe Schlüssel wie in Hook-Daten und Erweiterungen. Der Kern verschiebt keine Zusagen: Nach einer Änderung des Zeitplans (Hook event.updated mit scheduleChanged) prüft das Plugin seine Termine mit occurrenceExists(). Bei Serien vergleicht man mit recurrenceEnd (UTC), nicht mit recurrenceUntil (Kalendertag in der Zeitzone des Events). Abgesagte Termine (ab 1.9): Abgesagt wird immer ein einzelner Termin, nie die ganze Serie; Zusagen und Wartelistenplätze bleiben dabei gespeichert – isGoing(), goingKeys() und attendees() liefern sie weiter. Ein Occurrence trägt den Zustand nicht; frage ihn mit isCancelled() bzw. für Listen einmal mit cancelledKeys() ab (die Schlüssel entsprechen Occurrence::key()). Für abgesagte Termine sollte ein Plugin nichts erinnern und nichts Neues anbieten, vorhandene Daten aber behalten: Die Absage kann zurückgenommen werden (Hooks event.cancelled und event.reinstated, siehe Hooks).

Postleitzahlen und Entfernungen

geo() arbeitet mit dem eingebauten Verzeichnis der Postleitzahlen (Deutschland, Österreich, Schweiz, Polen, Frankreich, Spanien, Niederlande, Italien, Tschechien; Niederlande nur über die vier Ziffern) ohne externe Dienste: supports($country), locate($country, $postalCode): ?GeoPoint, placeName(), postalCodeError() (übersetzte Meldung oder null), viewerLocation($communityId, Viewer) (nur, wenn die Community Postleitzahl oder Anschrift abfragt), status($communityId, Viewer) (ob Entfernungen möglich sind, mit Hinweis und Link zum Konto), distanceKm(GeoPoint, GeoPoint) und displayKm() (unter 10 km eine Nachkommastelle).

Gruppen-Chats

Plugins legen eigene, verwaltete Gruppen an; alle anderen Methoden wirken nur auf Gruppen dieses Plugins in derselben Community (sonst NotFound). notify: false unterdrückt die Glocke „… hat dich hinzugefügt“ – das Plugin benachrichtigt dann selbst. Die Oberfläche zeigt bei solchen Gruppen ein Schildchen mit dem Plugin-Namen und sperrt Umbenennen, Hinzufügen und Entfernen; Verlassen bleibt möglich. Gruppen können jederzeit verschwinden (alle sind gegangen) – vorher exists() prüfen und bei Bedarf neu anlegen. Auf eine gelöschte Gruppe werfen addParticipants und systemMessage Conflict.

Benachrichtigungen

  • Empfänger ist ein lesendes Mitglied mit aktivem Konto und nie der Akteur selbst; sonst false.
  • path beginnt mit /c/<slug derselben Community>/, höchstens 500 Zeichen, ohne Schema oder // – sonst InvalidArgumentException.
  • Titel und Text übersetzt der Kern in die Sprache des Empfängers; reiner Text, gekürzt auf 160 bzw. 300 Zeichen.
  • Glocke und Push gehen immer zusammen. email: true schickt zusätzlich eine E-Mail, wenn eine neue Glocke entsteht und der Empfänger „E-Mails von Erweiterungen“ nicht abbestellt hat. collapse: true legt keine neue Glocke an, solange eine ungelesene Glocke dieses Plugins mit demselben Pfad existiert; dann entfällt auch die E-Mail, nur der Push geht hinaus.
  • Höchstens 60 je Stunde, Empfänger und Plugin; darüber false und ein Log-Eintrag.
  • Eine Glocke gilt automatisch als gelesen, sobald der Empfänger die Plugin-Seite des Pfads geöffnet hat und sie zu sehen ist – verglichen wird der Pfad ohne Abfrage und Anker (z. B. /c/<slug>/plugins/<id>/fahrten), gezählt werden nur Glocken, die vor dem Öffnen der Seite entstanden sind. Zeigt der Pfad auf einen Beitrag (/feed/posts/<id>) oder einen Kommentar (#comment-<id>), zählt erst, wenn dieser zu sehen war.
  • forget($communityId, $path, ?string $userId = null) entfernt Glocken des Plugins mit diesem Pfad, z. B. wenn eine Anfrage zurückgezogen wurde.
  • Zweite Mitteilung zum selben Ziel: Eine Erinnerung nach einer ersten Glocke mit demselben Pfad schickt man ohne collapse und entfernt die alte vorher mit forget($communityId, $path, $userId) – sonst geht sie bei allen unter, die die erste Glocke noch nicht gelesen haben, samt E-Mail.

E-Mails

mailer()->send($communityId, $userId, string $subjectKey, string $template, array $vars = [], array $params = [], array $attachments = [], bool $mandatory = false): bool
  • Vorlagen liegen unter templates/email/ des Plugins ('email/angebot.html.twig') und erweitern das Layout der Plattform; Texte darin übersetzt der Filter ptrans:
    Der Kern setzt recipientName, communityName, communityUrl und unsubscribeUrl sowie Absender, Sprache und Signatur der Community. Der Betreff subjectKey ist ein Übersetzungsschlüssel mit params.
  • Empfänger: Mitglied der Community mit gültiger Adresse. Gewöhnliche Mails gehen nur an lesende Mitglieder mit eingeschalteter Einstellung „E-Mails von Erweiterungen“ und bekommen einen Abmeldelink und List-Unsubscribe.
  • mandatory: true nur für Bestätigungen eigener Handlungen und rechtlich nötige Mitteilungen – erreicht dann auch nicht lesende Mitglieder und ignoriert die Einstellung.
  • Anhänge ([['name' => …, 'mimeType' => …, 'content' => …]]) zusammen höchstens 10 MB. Höchstens so viele Mails je Stunde, Plugin und Community, wie der Plattform-Admin unter Plugins einstellt (Standard 300, ab Plugin-API 1.3 einstellbar; Einladungen über invites()->send() haben ein eigenes Kontingent); darüber false.
mailer()->sendToAddress($communityId, string $email, string $name, string $locale, string $subjectKey, string $template, array $vars = [], array $params = [], array $attachments = [], bool $mandatory = false): bool (ab Plugin-API 1.8)
  • Mail an eine Adresse ohne Konto, z. B. ein Rundschreiben an Mitglieder, die nur als Akte geführt werden. Nur mit privacy.memberEmails: true im Manifest, sonst LogicException.
  • Gleiche Vorlagen, Anhänge und dasselbe Kontingent wie send(); recipientName in der Vorlage ist der übergebene name (reiner Text, höchstens 100 Zeichen). Sprache locale de oder en, sonst de. Ungültige Adressen (höchstens 180 Zeichen) ergeben false.
  • Gewöhnliche Mails bekommen einen Abmeldelink und List-Unsubscribe je Adresse, Community und Plugin. Wer sich abmeldet, bekommt von diesem Plugin in dieser Community nur noch Mails mit mandatory: true (ohne Abmeldelink); sendToAddress() gibt dann false zurück und verbraucht kein Kontingent. Die Plattform speichert dafür nur einen Prüfwert der Adresse, nie die Adresse selbst; die Abmeldeseite nennt Community und Plugin, nicht die Adresse. Groß- und Kleinschreibung der Adresse spielen keine Rolle.
  • Ob jemand ein Konto hat, prüft der Kern nicht – hat eine Person ein Konto, nimmt das Plugin send() (dort gelten die Einstellungen ihres Kontos).
mailer()->remaining($communityId): int (ab Plugin-API 1.8) nennt die noch freien Mails im laufenden Stunden-Kontingent des Plugins in der Community, ohne etwas zu buchen – auch in GET-Handlern erlaubt. Für Versand in Blöcken: im Job höchstens remaining() Mails schicken und den Rest später. mailer()->signatureStatus($communityId): ?string (ab Plugin-API 1.8) sagt, ob die E-Mail-Signatur der Community, die unter jeder Mail steht, Aufmerksamkeit braucht: missing (keine eigene Signatur), review (Angaben zum Anbieter seit dem letzten Speichern geändert) oder null. Gepflegt wird sie unter Einstellungen → Rechtstexte (/c/{slug}/settings/legal#mail-signature). Zeige den Hinweis nur Owner und Admins (viewer.isManager) – nur sie können die Signatur ändern. Nur lesend, auch in GET-Handlern erlaubt.

Forderungen und Lastschrift

Ab Plugin-API 1.1 ("pluginApi": "^1.1" im Manifest). Plugins melden Forderungen – Beiträge, Standgebühren, Munition, Verzehr –, QuickTribe zieht sie per SEPA-Lastschrift ein (SEPA-Datei der Bank oder Stripe), mahnt und gleicht aus. Bankverbindung, Mandat und Einzug gehören der Plattform; ein Plugin sieht nie IBAN, BIC, Kontoinhaber oder Bankname und nur Forderungen, die es selbst gemeldet hat.
  • ClaimInput: zahlungspflichtige Mitgliedschaft, Betrag in Cent (negativ = Gutschrift), Text (≤ 140 Zeichen), reference, Fälligkeit dueOn (Y-m-d), Währung nur EUR; optional Kategorie (z. B. „Munition“, „Beitrag“), Leistungszeitraum, Leistung für eine andere Mitgliedschaft (subjectMembershipId, z. B. Kind im Haushalt) oder eine Bezeichnung (subjectLabel, z. B. Gast), korrigierte Forderung (correctsClaimId) und detailPath (eine Seite des Plugins mit den Einzelposten).
  • Idempotenz: Die reference ist je Plugin und Community eindeutig (Groß-/Kleinschreibung egal). Dieselbe Meldung noch einmal liefert dieselbe Forderung; abweichende Beträge, Mitglieder oder Fälligkeiten unter derselben Referenz werden abgelehnt (reference_conflict). Eine gemeldete Forderung ändert sich nie – korrigiert wird durch Stornieren (solange offen) oder eine Gegenforderung mit negativem Betrag. Nach einem Storno ist die Referenz verbraucht: erneut gemeldet wird sie übersprungen (reference_cancelled, submit() wirft Conflict); wer neu melden will, nimmt eine neue Referenz, z. B. mit dem Zusatz :v2.
  • Formfehler (ClaimInput::violations()) brechen den ganzen Aufruf ab (ValidationFailed, bei submitMany mit Pfaden wie 3.amountCents); fachliche Ausschlüsse – Mitglied unbekannt, Konto gelöscht, Referenz vergeben, Korrektur passt nicht – meldet submitMany je Eintrag.
  • Melden geht nur, solange das Plugin in der Community eingeschaltet ist; lesen, stornieren und bar ausgleichen auch danach. Schreibende Methoden werfen in GET-Handlern eine LogicException.
  • Wer handelt ($actorUserId, null = das Plugin selbst): ein lesendes Mitglied der Community mit bestehendem Konto, in einem Request nur die angemeldete Person – sonst InvalidArgumentException. Bei settleCash() ist der Akteur Pflicht; wer kein lesendes Mitglied ist, bekommt Forbidden.
  • Datumsangaben (dueOn, Leistungszeitraum, ClaimQuery-Filter, settledOn) sind echte Kalendertage JJJJ-MM-TT – 2026-02-30 ergibt ValidationFailed.
  • Überfällig (Claim::$overdue) rechnet QuickTribe bei jedem Lesen gegen die aktuelle Uhr; ein Teilausgleich lässt eine Überfälligkeit stehen, erst der volle Ausgleich beendet sie.
  • Trifft ein Schreibvorgang auf eine Sperre (Deadlock), wiederholt QuickTribe ihn bis zu dreimal – außer innerhalb von db()->transactional(), dort entscheidet das Plugin.
  • Abgleich: list() liefert einen Cursor; das Plugin speichert ihn und liest später weiter – so verpasst es keine Änderung, auch wenn ein Hook nicht ankam.
  • Hooks dazu: Forderungen. Was die Kasse mit den Forderungen tut – Einzug, Rückläufer, Mahnung, Ausgleich –, beschreibt das Handbuch für die Kasse.
  • Testen: App\Tests\Support\Plugin\InMemoryDebits verhält sich wie der Dienst (derselbe Vertragstest prüft beide, mehr unter Testen):

Ergebnisse und Modelle

submitMany() liefert je Eintrag in derselben Reihenfolge ein SubmitResult mit index, outcome und – bei created/existing – der Forderung (claim). Fachlich ausgeschlossene Einträge kommen als skipped mit reason: DebitSetup (setup(), auch bei ausgeschalteter Lastschrift): enabled, method (DebitMethod::SepaFile bzw. Stripe), currency (immer EUR), timezone (in dieser Zone liest der Kern dueOn und die Leistungsdaten, Standard Europe/Berlin), prenotificationDays, schedule (manual beim Datei-Verfahren – die Kasse legt Einzüge an; bei der Stripe-Lastschrift monthly, weekly oder daily), nextCollectionOn (nur Stripe: Tag, an dem der nächste automatische Einzug angelegt wird – eingezogen wird erst nach der Ankündigungsfrist), returnFeeEnabled, returnFeeCents und treasuryPath (/c/<slug>/debit, für einen Link „Zur Kasse“ in Team-Ansichten). MandateInfo (mandates(), ohne Bankdaten): status (MandateStatus::None, Pending, Active, Revoked, Expired), method, kind (paper, online, …), reference, signedOn, lastCollectedAt und collectible (Mandat aktiv, Verfahren passt, Lastschrift an). collectible ist eine notwendige, keine hinreichende Bedingung: Eine nach einer Rückgabe gesperrte Bankverbindung oder eine zu kurze Ankündigungsfrist berücksichtigt es nicht – ob tatsächlich eingezogen wird, entscheidet die Kasse mit dem Einzug. Eine gemahnte Forderung (dunningLevel > 0, auch nach einer Zahlungsaufforderung) zieht der Kern nie von selbst ein, auch nicht bei collectible: nur, wenn die Kasse „erneut einziehen“ wählt – sonst gleicht das Mitglied per Überweisung aus. Die Mandatsreferenz darf in Team-Ansichten erscheinen. PaymentStanding (standings()): hasPaymentProblem folgt derselben Regel wie die Event-Sperre (Plan mit ruhenden Rechten oder überfällige Forderung, über alle Quellen). Welche Felder gefüllt sind, hängt vom Betrachter ab: Ohne Mitgliedschaft in dieser Community wirft standings() Forbidden. Fremde Mitgliedschafts-IDs fehlen im Ergebnis von mandates() und standings(). Claim enthält neben den Angaben der Meldung status (ClaimStatus, mit isFinal() und isOutstanding()), openCents (Vorzeichen wie der Betrag, 0 bei paid, settled, cancelled), overdue und overdueOn, dunningLevel (0–3), returnReason, die ID des letzten Einzugs und die Zeitpunkte paidAt, returnedAt, settledAt, cancelledAt (UTC).

Abgleich über den Cursor

Hooks kommen höchstens einmal. Ein Plugin, das den Stand seiner Forderungen spiegelt, liest deshalb regelmäßig – etwa in einem täglichen Job – alle Änderungen seit dem letzten Lauf:
ClaimQuery filtert zusätzlich nach membershipId, statuses (Liste von ClaimStatus), category, dueFrom und dueTo (Y-m-d, inklusive). Der Cursor ist undurchsichtig; list() liefert immer einen, auch auf der letzten Seite.

Fehler

Dienste

Ab Plugin-API 1.6 ("pluginApi": "^1.6", "quicktribe": ">=2.33"; Startjahr ab 1.7, "quicktribe": ">=2.34"; Bestätigung durch das Team ab 1.9, "quicktribe": ">=2.37"). Der Kern führt Dienst-Arten (Einstellungen → Dienste: Name, Soll je Kalenderjahr, Startjahr, optional an Pläne gebunden), markiert Events als Dienst-Event (jede Zusage zählt) oder gibt ihnen Dienst-Slots (Aufgaben mit eigener Platzzahl neben der Teilnehmerzahl) und schreibt nach dem Ende eines Termins jeden geleisteten Dienst in ein Ledger – wie bei den Punkten zählen nur Eingecheckte, sobald es am Termin Check-ins gab. Das Soll gilt für lesende Mitglieder ohne Team-Rolle, bei Plan-Bindung nur mit einem der Pläne. Plugins lesen Dienst-Arten, Stand und Einträge, lesen und buchen Slots; Soll, Ledger, Regeln, Glocken, Protokoll und die Oberfläche bleiben beim Kern.
  • Regeln beim Buchen: dieselben wie bei einer Zusage – Schreibrecht, Sperre des Events (Plan, Level, Alter), keine Vorschau, Termin nicht vorbei, Anmeldezeitraum, Zahlungssperre, verlangtes Formular, dazu die Plan-Bindung der Dienst-Art und die Platzzahl des Slots (voll → Conflict, keine Warteliste). Trägt das Team ein, gelten Formular, Anmeldezeitraum und Zahlungssperre nicht, die Slot-Grenze schon. Im Request ist der Viewer die angemeldete Person (sonst InvalidArgumentException); in GET-Handlern und Ausgabe-Rückrufen werfen book()/release() eine LogicException.
  • Sichtbarkeit: Der Schalter „Stand im Profil für alle Mitglieder sichtbar“ betrifft nur die Oberfläche – für Plugins sehen den Stand immer nur die Person selbst, das Team und Plattform-Admins. Wer den Stand anderer Mitglieder anzeigt, prüft selbst, wem er ihn zeigt.
  • Zählung: completed = Ledger-Zeilen (eine je Mitgliedschaft und Termin, Slot vor Dienst-Event), planned = künftige Zusagen zu Dienst-Events bzw. gebuchte Slots (nach dem Jahr des Terminbeginns in UTC); DutyStanding::missing() = fehlende Dienste gegenüber dem Soll, isBehind() = erledigt plus geplant unter dem Soll. Startjahr (ab 1.7): Das Soll gilt erst ab DutyInfo::$startYear; für frühere Jahre ist DutyStanding::$expected null (wie bei einer nicht geltenden Dienst-Art – applies sagt, ob die Art für die Person gilt), missing() 0 und isBehind() false, Einträge und Buchungen zählen trotzdem. Dienst-Arten vor ihrem Startjahr erscheinen in standing() nur mit Einträgen oder Buchungen im Jahr; wer ein Soll berechnet, nutzt expected statt expectedPerYear. Ein nachträglich als Dienst markiertes vergangenes Event bringt keine Einträge; das Ledger behält Einträge auch nach dem Austritt und nach einer Kontolöschung (ohne Personenbezug).
  • Bestätigung durch das Team (ab 1.9): Eine Community kann verlangen, dass geleistete Dienste vom Team bestätigt werden – immer oder je Dienst-Art (DutyInfo::$needsConfirmation); wer am Termin eingecheckt wurde, ist sofort bestätigt. Für Plugins gilt eine Regel: Nur bestätigte Dienste zählen. DutyStanding::$completed, completions() und der Hook duty.completed kennen nur sie; Dienste, die noch warten, stehen in DutyStanding::$pending (sie halten wie geplante aus dem Rückstand: isBehind() = erledigt plus wartend plus geplant unter dem Soll; missing() zählt sie nicht) und in pendingCount(). Abgelehnte Dienste sieht kein Plugin. Bestätigen und Ablehnen bleibt Sache des Kerns. Wer über ein Jahr abrechnet (etwa einen Ausgleich für fehlende Dienste), wartet, bis pendingCount($communityId, $year) 0 ist – sonst würde ein Dienst als fehlend berechnet, über den das Team noch nicht entschieden hat. Ein Plugin mit "pluginApi": "^1.6" läuft unverändert weiter und sieht wartende Dienste schlicht noch nicht als erledigt.
  • Hooks: duty.booked, duty.released, duty.completed, siehe Hooks.

Speicher

storage()->forCommunity($communityId) bzw. storage()->global() liefern einen Bereich im Upload-Speicher der Plattform (lokal oder S3), getrennt je Plugin und Community. Pfade bestehen aus höchstens 8 Segmenten (je [A-Za-z0-9][A-Za-z0-9._-], bis 100 Zeichen) und 255 Zeichen. Namen im ZIP-Archiv folgen derselben Form, dürfen zusätzlich Leerzeichen und ( ) + , enthalten, müssen ohne Groß-/Kleinschreibung eindeutig sein und dürfen nicht zugleich Datei und Ordner sein; höchstens 50 000 Einträge und 2 GiB unkomprimiert, sonst InvalidArgumentException – abgelegt wird dann nichts. Der Kern baut das Archiv in einer temporären Datei; Streams als Inhalt halten den Speicherbedarf klein. Dateien sind nie öffentlich erreichbar; ausgeliefert werden sie nur über eigene Endpunkte mit Response::stream. Verschlüsselte Dateien hängen an APP_SECRET – ändert der Betreiber es, sind sie verloren.

Dateien und Dokumente

files()->prepareDocument(UploadedFile $file, array $extensions = ['pdf', 'jpg', 'jpeg', 'png'], int $maxBytes = 10_485_760): PreparedFile prüft Endung, Inhaltstyp und Signatur der Datei; Bilder werden neu kodiert (höchstens 4000 Pixel, ohne EXIF- und GPS-Angaben), PDF bleiben unverändert. prepareImage(UploadedFile $file, int $maxPx = 2000) liefert ein WebP-Bild. Beide werfen bei Problemen ValidationFailed(['file' => …]). PreparedFile hat stream, mimeType, cleanName, extension und size – passend für storage()->…->putEncrypted().

Verschlüsselung und Signaturen

purpose folgt der Namensregel (bis 40 Zeichen). Eine Signatur belegt „diese Installation“, nicht die Person. Sie schützt vor späteren Änderungen durch Dritte ohne APP_SECRET und Datenbank; gegen den Betreiber selbst hilft nur ein externer Zeitstempel. Die signierte Nachricht sollte alle tragenden Angaben enthalten (Zweck, Community, Objekt, letzter Hash, Anzahl, Zeit, Person). Die öffentlichen Schlüssel zeigt der Plattform-Admin auf der Detailseite des Plugins.

Zeitstempel

timestamps()->isConfigured() sagt, ob der Betreiber einen Zeitstempeldienst eingerichtet hat (siehe Plugins betreiben → Zeitstempeldienst). stamp(string $sha256Hex): TimestampToken lässt einen SHA-256-Hash (64 Hex-Zeichen) von der externen Stelle nach RFC 3161 bestätigen und prüft die Antwort vollständig; das Token (base64) gehört neben das Dokument. verify(string $tokenBase64, string $sha256Hex): TimestampVerification prüft später – zum Zeitpunkt des Stempels, also auch nach Ablauf des Zertifikats der Stelle. stamp() wirft TimestampUnavailable mit reason(): not_configured, unreachable, rejected, invalid_response oder rate_limited (höchstens 30 je Stunde und Community).

PDF, Vorlagen, HTML

  • pdf()->render(string $template, array $vars = [], string $paper = 'A4', string $orientation = 'portrait'): string rendert eine Vorlage aus templates/pdf/ des Plugins (Name ohne pdf/, z. B. 'liste.html.twig') zu PDF-Bytes. Papier A3, A4, A5, A6, letter, legal. Bilder und Schriften nur als data:-URI oder aus templates/pdf/; Seitenzahlen per CSS counter(page), z. B. in einer festen Fußzeile (eine Gesamtzahl „von N“ über counter(pages) unterstützt die PDF-Erzeugung nicht – sie ergäbe 0). Synchron nur für kleinere Dokumente (Richtwert bis 50 Seiten), größere in einer Aufgabe; höchstens 30 PDF je 10 Minuten und Person. pdf()->qrDataUri($text) liefert einen QR-Code als SVG-data:-URI.
  • views()->render('email/…' oder 'pdf/…', $vars) rendert eine Vorlage zu HTML. Vorlagen kommen immer aus dem Plugin, nie aus Datenbank oder Einstellungen.
  • html()->sanitize($html) säubert Rich-Text wie die Plattform (das Ergebnis darf ins Frontend-Element RichTextBody), html()->toText($html) macht reinen Text daraus.

CSV und Excel

Bestätigung heikler Aktionen

Vor heiklen Schritten (z. B. einem verbindlichen Tagesabschluss) bestätigt die angemeldete Person ihre Identität: security()->confirmationMethod($request) sagt, was nötig ist (password, password_totp bei aktiver Zwei-Faktor-Anmeldung, fresh_login bei Konten ohne Passwort), security()->confirm($request, $password, $totpCode) prüft und wirft sonst Conflict mit der Meldung des Kerns, hasRecentLogin($request) prüft eine Anmeldung in den letzten 10 Minuten. Nur in HTTP-Handlern; Fehlversuche werden protokolliert. Bestätigungen für fremde Konten gibt es nicht.

Protokoll

audit()->log(?string $communityId, string $action, ?string $targetType = null, ?string $targetId = null, array $payload = []) schreibt plugin.<id>.<action> ins Protokoll der Community (bzw. der Plattform bei null). Die Aktion folgt der Namensregel; der ganze Name hat höchstens 64 Zeichen. targetType bis 32 Zeichen, targetId eine UUID. Die handelnde Person setzt der Kern (im Request die angemeldete Person, in Aufgaben deren Auslöser), dazu die Herkunft (Plugin und Version). Payload höchstens 8 KB, nur einfache Werte und Listen davon – keine Inhalte und keine Geheimnisse.

Übersetzung, Adressen, Limits, Cache

  • translator()->trans($key, $params = [], ?string $locale = null) übersetzt mit dem Katalog des Plugins, dann dem der Plattform, sonst bleibt der deutsche Text; locale() ist die aktuelle Sprache.
  • urls(): absolute($path) (mit APP_URL), pagePath($slug, $path), globalPagePath($path), apiPath($slug, $path), eventPath($slug, $eventId, $start = null), memberProfilePath(), conversationPath(), newMessagePath($slug, $userId), accountPath($anchor) (z. B. personal, phone, birthday) und localPath($target) (nur lokale Rücksprungziele).
  • limiter('offers', 10, '1 hour')->consume($key) wirft TooManyRequests mit retryAfter, tryConsume() liefert bool. Grenze und Intervall gelten je Name fest.
  • cache($communityId)->get|set|delete|remember($key, $ttlSeconds, …): Schlüssel bis 100 Zeichen (A–Z, a–z, 0–9, _, ., -), Lebensdauer 1 Sekunde bis 30 Tage, getrennt je Plugin und Community.

Modelle