breadcrumb-the-shire/docs/howto-benutzerdefinierte-felder.md

Benutzerdefinierte Felder (V1) Kurzreferenz

Letzte Aktualisierung: 2026-03-06

Ziel

Tenant-spezifische Zusatzfelder für User:

• Definitionen und Optionen werden pro Tenant gepflegt.
• Werte werden pro User gespeichert.
• Address-Book-Filter nutzen dynamische Query-Parameter.

Berechtigungen

• custom_fields.manage
  • Definitionen/Optionen im Tenant-Tab pflegen.
• custom_fields.edit_values
  • Werte im User-Tab pflegen.

Tabellen

• tenant_custom_field_definitions
  • Felddefinition pro Tenant (Label, Typ, aktiv, filterbar, field_key intern).
• tenant_custom_field_options
  • Optionen für select/multiselect je Definition.
• user_custom_field_values
  • Gespeicherter Wert pro user_id + definition_id (unique).
• user_custom_field_value_options
  • N:M-Optionen für Multiselect-Werte.

Typen und Verhalten

• text, textarea
  • Eingabe am User möglich.
  • Nicht als Address-Book-Filter zugelassen.
• select, multiselect, boolean, date
  • Eingabe am User möglich.
  • Optional als Address-Book-Filter (wenn is_filterable=1).

Wichtige Regeln

• field_key
  • Wird serverseitig aus Label erzeugt und tenant-weit eindeutig gehalten.
  • Kein manuelles UI-Feld.
• User-Werte sind in V1 optional (keine Pflichtvalidierung).
• Bei Tenant-Wechsel am User werden Werte außerhalb der aktuellen User-Tenants bereinigt.

Query-Parameter im Address Book

• cf_<definition_uuid>
  • scalar/select/boolean
• cfm_<definition_uuid>
  • multiselect (CSV mit Option-IDs)
• cfd_<definition_uuid>_from
• cfd_<definition_uuid>_to
  • date-range

Unbekannte/manipulierte Parameter werden ignoriert.

Relevante Pfade

• Tenant-Tab Formular:
  • /pages/admin/tenants/_form.phtml
• Tenant Actions:
  • /pages/admin/tenants/custom-field-create($id).php
  • /pages/admin/tenants/custom-field-update($id).php
  • /pages/admin/tenants/custom-field-delete($id).php
• User-Werte:
  • /lib/Service/CustomField/UserCustomFieldValueService.php
  • /lib/Repository/CustomField/*
• Address-Book-Filter:
  • /pages/address-book/index().php
  • /pages/address-book/index(default).phtml

Troubleshooting (kurz)

• Multiselect speichert nichts:
  • Feldname ohne doppeltes [] prüfen.
• Optionen sind leer:
  • Label-Key für MultiSelect auf label/description prüfen.
• Filterbar ist deaktiviert:
  • Typ ist nicht in select|multiselect|boolean|date.