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
- 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 oderNotFound– nie fremde Inhalte. - Gelöschte Communities verhalten sich wie fremde. Gesperrte liefern Daten (für Jobs und Aufräumen);
communities()->enabledFor()undJobContext::communities()lassen sie aus – Abgleichs- und Löschjobs laufen deshalb über die Communities der eigenen Tabellen (siehe Abgleich und Löschfristen). - 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). - Viewer erzeugt nur der Kern – über
Request::viewer(),ExtensionQuery::viewer()odermembers()->viewerFor()(für Jobs, Hooks und Aufgaben). - GET ändert nichts. Schreibende Methoden werfen in GET-Handlern und Ausgabe-Rückrufen eine
LogicException(siehe PHP-Schnittstelle). - E-Mail-Adressen gibt kein Dienst heraus – Ausnahmen für Plugins mit
privacy.memberEmails(protokolliert): ab Plugin-API 1.3 der Abgleichmembers()->verifiedEmail()/matchEmails(), ab 1.4 die Anzeigemembers()->loginEmails()für Owner und Admins; ab 1.8 darf ein solches Plugin Adressen ohne Konto übermailer()->sendToAddress()anschreiben; das volle Geburtsdatum nurmembers()->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 (sonstNotFound).
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. pathbeginnt mit/c/<slug derselben Community>/, höchstens 500 Zeichen, ohne Schema oder//– sonstInvalidArgumentException.- 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: trueschickt zusätzlich eine E-Mail, wenn eine neue Glocke entsteht und der Empfänger „E-Mails von Erweiterungen“ nicht abbestellt hat.collapse: truelegt 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
falseund 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
collapseund entfernt die alte vorher mitforget($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 Filterptrans:Der Kern setztrecipientName,communityName,communityUrlundunsubscribeUrlsowie Absender, Sprache und Signatur der Community. Der BetreffsubjectKeyist ein Übersetzungsschlüssel mitparams. -
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: truenur 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 überinvites()->send()haben ein eigenes Kontingent); darüberfalse.
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: trueim Manifest, sonstLogicException. - Gleiche Vorlagen, Anhänge und dasselbe Kontingent wie
send();recipientNamein der Vorlage ist der übergebenename(reiner Text, höchstens 100 Zeichen). Sprachelocaledeoderen, sonstde. Ungültige Adressen (höchstens 180 Zeichen) ergebenfalse. - Gewöhnliche Mails bekommen einen Abmeldelink und
List-Unsubscribeje Adresse, Community und Plugin. Wer sich abmeldet, bekommt von diesem Plugin in dieser Community nur noch Mails mitmandatory: true(ohne Abmeldelink);sendToAddress()gibt dannfalsezurü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älligkeitdueOn(Y-m-d), Währung nurEUR; 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) unddetailPath(eine Seite des Plugins mit den Einzelposten).- Idempotenz: Die
referenceist 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()wirftConflict); wer neu melden will, nimmt eine neue Referenz, z. B. mit dem Zusatz:v2. - Formfehler (
ClaimInput::violations()) brechen den ganzen Aufruf ab (ValidationFailed, beisubmitManymit Pfaden wie3.amountCents); fachliche Ausschlüsse – Mitglied unbekannt, Konto gelöscht, Referenz vergeben, Korrektur passt nicht – meldetsubmitManyje 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 – sonstInvalidArgumentException. BeisettleCash()ist der Akteur Pflicht; wer kein lesendes Mitglied ist, bekommtForbidden. - Datumsangaben (
dueOn, Leistungszeitraum,ClaimQuery-Filter,settledOn) sind echte KalendertageJJJJ-MM-TT–2026-02-30ergibtValidationFailed. - Ü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\InMemoryDebitsverhä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 (sonstInvalidArgumentException); in GET-Handlern und Ausgabe-Rückrufen werfenbook()/release()eineLogicException. - 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 abDutyInfo::$startYear; für frühere Jahre istDutyStanding::$expectednull(wie bei einer nicht geltenden Dienst-Art –appliessagt, ob die Art für die Person gilt),missing()0 undisBehind()false, Einträge und Buchungen zählen trotzdem. Dienst-Arten vor ihrem Startjahr erscheinen instanding()nur mit Einträgen oder Buchungen im Jahr; wer ein Soll berechnet, nutztexpectedstattexpectedPerYear. 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 Hookduty.completedkennen nur sie; Dienste, die noch warten, stehen inDutyStanding::$pending(sie halten wie geplante aus dem Rückstand:isBehind()= erledigt plus wartend plus geplant unter dem Soll;missing()zählt sie nicht) und inpendingCount(). 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, bispendingCount($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'): stringrendert eine Vorlage austemplates/pdf/des Plugins (Name ohnepdf/, z. B.'liste.html.twig') zu PDF-Bytes. PapierA3,A4,A5,A6,letter,legal. Bilder und Schriften nur alsdata:-URI oder austemplates/pdf/; Seitenzahlen per CSScounter(page), z. B. in einer festen Fußzeile (eine Gesamtzahl „von N“ übercounter(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-ElementRichTextBody),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)(mitAPP_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) undlocalPath($target)(nur lokale Rücksprungziele).limiter('offers', 10, '1 hour')->consume($key)wirftTooManyRequestsmitretryAfter,tryConsume()liefertbool. 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.