Lernseite · Extbase: Persistenz und Validierung
Daten speichern und Eingaben prüfen mit Extbase
Ein Besucher meldet sich zu einer Konferenz an. Wie kommen seine Daten in die Tabelle, und wie stellt Extbase sicher, dass sie stimmen? Diese Seite erklärt beides: Speichern und Laden von Objekten und das Prüfen von Eingaben. Controller, Views und Plugins behandelt der Kurs „Extbase: MVC, Plugins und Views“.
Wie Extbase Daten speichert
Extbase enthält ein ORM, ein Object-Relational Mapping. Es übersetzt zwischen PHP-Objekten und Tabellenzeilen. Du arbeitest mit Objekten und Repositorys statt mit SQL. Das Repository ist deine Schnittstelle. Der PersistenceManager sammelt Änderungen und schreibt sie gesammelt. Die Identity Map merkt sich geladene Objekte: Derselbe Datensatz ergibt im selben Request dasselbe Objekt.
Unser Beispiel ist die Extension my_extension mit dem Vendor MyVendor. Sie hat ein Modell Conference mit Titel, Startdatum, Stadt und Sprechern. Sprecher und Teilnehmer liegen gemeinsam in einer Personentabelle.
Das Modell und seine Tabelle
Ein Modell liegt in Classes/Domain/Model und erweitert AbstractEntity. Jede Instanz entspricht einem Datensatz. Die Basisklasse bringt uid und pid mit, samt getUid(), getPid() und setPid(). Vor dem ersten Speichern liefert getUid() den Wert null. Alle anderen Felder legst du selbst an, auch Systemfelder wie crdate oder sorting.
class Conference extends AbstractEntity
{
#[Validate(validator: 'NotEmpty')]
protected string $title = '';
protected ?\DateTime $startDate = null;
protected string $city = '';
}Eigenschaften sind protected, nicht private. Extbase befüllt sie über eine Methode der Elternklasse. Private Eigenschaften der Kindklasse kann diese nicht schreiben. Sie behalten still ihren Standardwert.
Namen nach Konvention: Für den Tabellennamen fällt der Vendor weg. Die übrigen Teile des Klassennamens werden klein geschrieben und mit Unterstrichen verbunden. So wird aus Conference die Tabelle tx_myextension_domain_model_conference. Ein Klassenname wie PostComment wird dabei nicht getrennt, er ergibt postcomment. Eigenschaften dagegen wandelt Extbase von camelCase in snake_case: conferenceDate wird zur Spalte conference_date. Im Fluid-Template nutzt du weiter den Namen der Eigenschaft.
Ohne TCA geht nichts. Extbase liest Spalten und Relationen aus dem TCA der Tabelle. Hat eine Spalte keine TCA-Definition, bleibt die Eigenschaft leer, auch wenn die Spalte existiert. Die Spalten selbst leitet TYPO3 aus dem TCA ab. Die Datei ext_tables.sql brauchst du nur für Sonderfälle wie eigene Indizes.
Abweichungen stehen in Classes.php unter Configuration/Extbase/Persistence. Dort ordnest du ein Modell einer fremden Tabelle wie fe_users zu oder eine Eigenschaft einer anders benannten Spalte. Für Modelle nach Konvention ist die Datei nicht nötig. Seit TYPO3 14 zeigt das Modul Configuration der Extension lowlevel die gesammelte Zuordnung aller Extensions.
Typen: Speichert eine Spalte einen Zeitpunkt als Ganzzahl, etwa mit dem TCA-Typ datetime, nimmst du ein nullbares DateTime. Extbase rechnet selbst um.
Entity oder Wertobjekt? Eine Entity hat eine eigene Identität, ihre UID. Die Konferenz 42 bleibt dieselbe, auch mit neuem Titel. Ein Wertobjekt ist allein durch seine Werte bestimmt, etwa ein Geldbetrag. Man ändert es nicht, man ersetzt es. Seit TYPO3 14 schreibst du Wertobjekte als einfache PHP-Klassen, denn AbstractValueObject ist nur noch intern.
Relationen und Lazy Loading
Für eine Relation auf ein Objekt nimmst du eine typisierte Eigenschaft, etwa ein nullbares Location. Für mehrere Objekte nimmst du eine ObjectStorage aus Extbase. Mit der ähnlichen Klasse SplObjectStorage von PHP kann Extbase keine Relationen laden oder speichern.
Die ObjectStorage hat attach() zum Hinzufügen, detach() zum Entfernen und contains() zum Prüfen. Methoden namens add oder remove hat sie nicht.
/** @var ObjectStorage<Speaker> */
protected ObjectStorage $speakers;
public function __construct()
{
$this->initializeObject();
}
public function initializeObject(): void
{
$this->speakers = new ObjectStorage();
}
public function addSpeaker(Speaker $speaker): void
{
$this->speakers->attach($speaker);
}
public function removeSpeaker(Speaker $speaker): void
{
$this->speakers->detach($speaker);
}Lazy Loading: Das Attribut Lazy lädt eine Relation erst beim ersten Zugriff. Bei einer ObjectStorage setzt Extbase eine LazyObjectStorage als Platzhalter ein. Gespeichert wird weiter normal. Bei einer Relation auf ein einzelnes Objekt muss der Typ zusätzlich LazyLoadingProxy erlauben.
#[Lazy]
protected Location|LazyLoadingProxy|null $location = null;Zwei weitere Attribute wirken auf Eigenschaften. Cascade kennt nur den Wert remove: Es löscht abhängige Objekte mit, wenn du das Elternobjekt über Extbase entfernst. Beim Löschen im Backend greift es nicht, denn der DataHandler kennt es nicht. Transient schließt eine Eigenschaft ganz aus. Extbase liest und schreibt sie nie, das passt für berechnete Werte.
Speichern mit dem PersistenceManager
Der PersistenceManager schreibt neue, geänderte und entfernte Objekte mit persistAll() in die Datenbank. Der Extbase-Bootstrap ruft das automatisch nach jedem Durchlauf eines Plugins oder Backend-Moduls auf. Das gilt auch bei einem Redirect.
Änderungen erkennt Extbase selbst. Änderst du ein geladenes Objekt mit einem Setter, schreibt persistAll() genau die geänderten Spalten. Ein update() ist nicht nötig. Das heißt Dirty Tracking.
Löschen: Hat die Tabelle ein Lösch-Feld unter ctrl.delete, setzt remove() nur das Feld deleted auf eins, wie das Backend. Ohne dieses Feld verschwindet die Zeile wirklich.
Selbst speichern musst du, wenn du sofort die neue UID brauchst. Ebenso in Konsolenbefehlen oder Scheduler-Tasks, wo kein Extbase-Bootstrap läuft. Dafür holst du das PersistenceManagerInterface per Dependency Injection.
Zur API des Interfaces gehören auch isNewObject(), getIdentifierByObject() und clearState(). Ob ein Objekt neu ist, fragst du mit isNewObject(), nicht mit der internen Methode des Objekts. clearState() vergisst alle geladenen Objekte und spart Speicher bei großen Importen.
Neu in TYPO3 14: Der Referenzindex wird beim Speichern immer aktualisiert, die Option updateReferenceIndex entfällt. Die Identity Map beachtet die Sprache: Mit anderen Spracheinstellungen geladen, ist ein Objekt eine eigene Instanz. Der Feature-Schalter extbase.enableHistoryTracking schreibt Änderungen in sys_history. Er ist standardmäßig aus. Je Tabelle schaltest du ihn im TCA mit ctrl.extbase.enableHistoryTracking und false wieder ab.
Das Standard-Repository
Zu Conference gehört die Klasse ConferenceRepository in Classes/Domain/Repository. Sie erweitert Repository und bleibt oft leer. Sie ist der einzige Weg zur Datenbank für dieses Modell.
Mitgeliefert sind zum Lesen findAll(), findByUid(), findByIdentifier(), findBy(), findOneBy(), count() und countAll(). Zum Schreiben gibt es add(), update(), remove() und removeAll(), aber kein save oder delete.
Die magischen Methoden sind weg. Methoden wie findByTitle oder countByOnline waren seit TYPO3 12.3 veraltet und sind seit TYPO3 14 entfernt. Heute übergibst du die Kriterien als Array. findBy() nimmt dazu Sortierung, Limit und Offset. count() nimmt dieselben Kriterien, countAll() zählt alles.
$this->conferenceRepository->findBy(
['city' => 'Berlin'],
['startDate' => QueryInterface::ORDER_ASCENDING],
10,
);
$this->conferenceRepository->findOneBy(['slug' => $slug]);
$this->conferenceRepository->count(['online' => true]);Sortierung: Ohne Angabe entsteht kein ORDER BY, die Reihenfolge bestimmt die Datenbank. Den Wert default_sortby aus dem TCA wendet Extbase nicht an. Eine Standardsortierung setzt du mit der Eigenschaft defaultOrderings im Repository oder zur Laufzeit mit setDefaultOrderings(). Schlüssel sind Namen von Eigenschaften, also startDate. Die Richtung kommt aus den Konstanten ORDER_ASCENDING und ORDER_DESCENDING des QueryInterface.
Repository holen: Der Controller bekommt es per Constructor Injection, als Konstruktorparameter mit protected readonly. Ist der Konstruktor belegt, nimmst du eine Methode wie injectConferenceRepository(). Den ObjectManager gibt es seit TYPO3 12 nicht mehr. Auch GeneralUtility::makeInstance() ist falsch. Damit gehen Einstellungen der gemeinsam genutzten Instanz verloren, etwa Query-Settings. Und die Abhängigkeiten des Repositorys werden nicht richtig verdrahtet.
Eigene Abfragen
Eigene Abfragen sind Methoden im Repository, deren Name mit find oder count beginnt. Jede startet mit createQuery(). Darauf setzt du mit matching() eine Bedingung und führst die Query mit execute() aus.
public function findUpcomingInCity(string $city): QueryResultInterface
{
$query = $this->createQuery();
$query->matching(
$query->logicalAnd(
$query->equals('city', $city),
$query->greaterThanOrEqual('startDate', new \DateTime('today')),
)
);
$query->setOrderings(['startDate' => QueryInterface::ORDER_ASCENDING]);
$query->setLimit(10);
return $query->execute();
}Genau eine Bedingung: matching() erwartet genau einen Constraint. Mehrere verknüpfst du mit logicalAnd(), logicalOr() oder logicalNot(). Übergibst du zwei Argumente, wirkt nur das erste. Ein zweiter Aufruf von matching() ersetzt den ersten, und ein Array nimmt die Methode nicht an. Für „online oder in Berlin“ brauchst du logicalOr().
equals()vergleicht mit genau einem Wert, ohne Platzhalter.like()sucht nur dann einen Teil des Textes, wenn vor und hinter dem Suchbegriff ein Prozentzeichen steht.in()prüft, ob der Wert in einer Liste steht, etwa eine UID in einer Liste von UIDs.contains()prüft, ob eine Relation ein bestimmtes Objekt enthält.
Alle Argumente sind Namen von Eigenschaften, keine Spalten. Über Relationen gehst du mit einem Punkt: speakers.name findet Konferenzen mit einem Sprecher dieses Namens. Die Joins baut Extbase selbst.
Limit und Ergebnis: setLimit() begrenzt die Zahl, setOffset() den Startpunkt. Ein Limit von null wirft eine Exception. execute() liefert ein QueryResult mit Objekten, mit dem Argument true rohe Zeilen. getFirst() liefert das erste Objekt oder null, toArray() fertige Objekte. count() auf der Query zählt, ohne Objekte zu laden.
Seit TYPO3 14 sortieren orderBy() und addOrderBy() auch mit den Ausdrücken concat(), trim() und coalesce(). Zum Blättern erzeugst du einen QueryResultPaginator aus Ergebnis, aktueller Seite und Einträgen je Seite. Eine SimplePagination liefert die Seitenzahlen fürs Template. Die alten Fluid-Widgets gibt es seit TYPO3 11 nicht mehr.
Extbase oder Doctrine? Extbase-Queries nutzen Eigenschaften, liefern Objekte und fügen Storage-Seiten, Sichtbarkeit und Sprache selbst hinzu. Der QueryBuilder von Doctrine nutzt Spalten und liefert Arrays. Für Summen, Gruppierungen oder Massenänderungen nimmst du ihn. Mehr dazu im Kurs „Datenbankzugriff und DataHandler“.
Storage-Seiten, Sichtbarkeit und Sprache
Jede Repository-Abfrage im Frontend schränkt ohne weitere Konfiguration automatisch ein. Sie sucht nur auf den Storage-Seiten. Sie beachtet die Enable-Fields versteckt, Startzeit, Endzeit und Benutzergruppe. Sie schließt gelöschte Datensätze aus und beachtet die aktuelle Sprache. Nach dem Besitzer filtert sie nicht.
Die storagePid setzt du im TypoScript unter plugin.tx_myextension mit persistence.storagePid. Das Feld Ausgangspunkt im Plugin überschreibt diesen Wert. Unterordner bezieht persistence.recursive mit ein. Nur findByUid() und findByIdentifier() ignorieren die storagePid. Neue Datensätze landen auf der ersten Storage-Seite. Für einen anderen Ordner setzt du unter persistence.classes für die Modellklasse den Wert newRecordStoragePid.
Query-Settings holst du mit getQuerySettings() von der Query:
setRespectStoragePage()mit false schaltet die Storage-Seiten ab.setIgnoreEnableFields()mit true ignoriert die Enable-Fields. MitsetEnableFieldsToBeIgnored()und dem Namen disabled entfällt nur hidden. Ohne diese Liste fallen auch Start- und Endzeit weg.setIncludeDeleted()undsetLanguageAspect()steuern gelöschte Datensätze und Sprache.
Für eine Methode oder für alle? Settings an einer einzelnen Query gelten nur für diese. So liefert nur findFeatured() Konferenzen aus allen Ordnern. Für alle Methoden erzeugst du die Settings in einer öffentlichen Methode initializeObject() des Repositorys und setzt sie mit setDefaultQuerySettings(). Oder du überschreibst createQuery().
Seit TYPO3 14.3 folgt Extbase dem fallbackType der Site-Sprache. Bei strict, dem Standard, fehlen Datensätze ohne Übersetzung.
Single Table Inheritance
Bei der Single Table Inheritance teilen sich mehrere Klassen einer Vererbung eine Tabelle. Eine Typspalte sagt, welche Klasse eine Zeile ist. Bei uns erweitern Speaker und Attendee die Klasse Person und liegen alle in einer Personentabelle.
- Im TCA legst du die Typspalte unter
ctrl.typefest. Extbase liest sie von dort. - In
Classes.phpträgst du beim Elternmodell unter subclasses die Unterklassen ein. - Jede Unterklasse bekommt in
Classes.phpdenselben tableName und einen eigenen recordType.
return [
Person::class => [
'subclasses' => [Speaker::class, Attendee::class],
],
Speaker::class => [
'tableName' => 'tx_myextension_domain_model_person',
'recordType' => 'speaker',
],
// Attendee::class genauso mit 'recordType' => 'attendee'
];Die frühere Konfiguration per TypoScript gibt es nicht mehr. Das Repository von Person schränkt auf den eigenen recordType und die der Unterklassen ein. Andere Typen liefert es nicht. Beim Laden schaut Extbase je Zeile in die Typspalte: Eine Zeile vom Typ speaker wird ein Speaker-Objekt. Das Repository einer Unterklasse filtert nur auf deren Typ.
Validierung in Extbase
Bevor eine Action läuft, prüft Extbase ihre Argumente.
Die Validierung läuft bei jeder Action mit typisierten Argumenten, nicht nur bei Formularen. Was nicht als Validator am Modell oder Parameter steht, prüft niemand.
Nur noch Attribute: Seit TYPO3 14 ignoriert Extbase alte Annotationen im Kommentar still. Es findet dann gar keine Prüfung statt. Die Attribute liegen im Namensraum Attribute von Extbase. Der alte Namensraum Annotation ist veraltet und fällt mit TYPO3 15 weg. Den Validator nennst du als Text oder Klassennamen, Optionen übergibst du mit benannten Parametern. Ein Array als einziges Argument und der Parameter param sind veraltet.
#[Validate(validator: 'NotEmpty')]
#[Validate(validator: 'StringLength', options: ['minimum' => 3, 'maximum' => 50])]
protected string $title = '';
public function createAction(
#[Validate(validator: ConferenceDateValidator::class)]
Conference $conference,
): ResponseInterfaceEingebaute Validatoren nennst du mit Kurznamen wie NotEmpty, StringLength oder EmailAddress. Ein Attribut Required gibt es nicht. Fast alle Validatoren lassen leere Werte durch. Ein leeres Feld mit nur EmailAddress ist also gültig. Für Pflicht und Format kombinierst du NotEmpty mit dem Format-Validator.
Symfony-Constraints gehen seit TYPO3 14 auch, etwa der Constraint Iban an einer Eigenschaft. Das Paket symfony/validator bringt Extbase schon mit. Meldungen, die mit LLL beginnen, werden übersetzt, und Symfony-Platzhalter wandelt Extbase um. Die Constraints File und Image gehen noch nicht.
Fehler anzeigen: Der ViewHelper f:form.validationResults liefert die Fehler eines Feldes. Sein Attribut for nennt den Pfad, etwa conference.title.
Eingeschleuste Felder: Das Formular von Fluid schreibt ein verstecktes Feld __trustedProperties. Es listet alle Felder auf und ist mit einem HMAC signiert. Extbase ordnet beim Absenden nur diese Felder zu. So kann niemand ein Feld wie featured einschleusen.
Formulare, Fehler und Zugriff
Wenn die Validierung scheitert, ruft Extbase errorAction() auf. Sie fügt eine Fehlermeldung hinzu und gibt per Forward im selben Request an die Action zurück, die das Formular zeigte. Eingaben und Fehler stehen dort bereit, der Status ist 400. Die Meldung „An error occurred while trying to call“ kommt aus getErrorFlashMessage(). Gibt diese Methode false zurück, entfällt sie.
Das Muster new und create: Die newAction zeigt das Formular, die createAction speichert. Scheitert create, führt die errorAction zurück zu new. Damit new das ungültige Objekt samt Eingaben annimmt, trägt ihr Parameter das Attribut IgnoreValidation. Ohne es würde auch new scheitern. Seit TYPO3 14 steht es direkt am Parameter, die Variante mit argumentName über der Methode ist veraltet.
public function newAction(#[IgnoreValidation] ?Conference $conference = null): ResponseInterface
public function createAction(Conference $conference): ResponseInterfaceZugriff: Seit TYPO3 14 prüft das Attribut Authorize an einer Action-Methode den Login, Gruppen oder eine Callback-Methode. Bei requireGroups genügt eine der Gruppen. Mehrere Authorize-Attribute an einer Action müssen alle erfüllt sein. Eine Callback-Methode im Controller muss public sein. Ob ein Datensatz dem Benutzer gehört, prüfst du selbst per Callback. Abgelehnt wird mit Status 403 über den ErrorController.
Rate Limit: RateLimit begrenzt Anfragen je IP-Adresse, standardmäßig fünf in 15 Minuten. Darüber antwortet Extbase mit Status 429. Zuverlässig wirkt das nur bei ungecachten Actions, sonst antwortet der Seitencache vor dem Controller.
Eigene Validatoren und Validierung in TYPO3
Ein eigener Validator liegt in Classes/Validation/Validator, etwa als SeatCountValidator. Er erweitert üblicherweise AbstractValidator und braucht keine Registrierung. Du setzt nur isValid() um. Die Methode gibt nichts zurück. Fehler meldest du mit addError(), mit Text und eindeutigem Code, meist einem Zeitstempel. Für ein Feld gibt es addErrorForProperty(). Rückgabewerte oder Exceptions wertet Extbase nicht aus. Deklariere die Klasse nicht final, damit man sie erweitern kann.
class SeatCountValidator extends AbstractValidator
{
protected $supportedOptions = [
'minimum' => [10, 'Minimum number of seats', 'integer'],
];
protected function isValid(mixed $value): void
{
if ($value < $this->options['minimum']) {
$this->addError('Zu wenige Plätze', 1729500000);
}
}
}Optionen stehen also in supportedOptions, die fertigen Werte in options. Eingebunden wird der Validator mit dem vollen Klassennamen. Ein Kurzname wie SeatCount sucht nur bei den Core-Validatoren und wirft eine NoSuchValidatorException. Implementiert ein Validator direkt das ValidatorInterface, braucht er seit TYPO3 14 auch setRequest() und getRequest().
Wohin damit? Ein Validator an einer Eigenschaft sieht nur deren Wert. Regeln über mehrere Felder gehören an den Action-Parameter. Beispiel: Beginnt eine Konferenz in weniger als vier Wochen, ist ein Sprecher Pflicht. Der Validator braucht Datum und Sprecher, also das ganze Objekt.
Validierung in ganz TYPO3 passiert an drei unabhängigen Stellen:
- Im TCA mit required oder eval für Backend-Formulare und DataHandler. Ein Pflichtfeld im Backend machst du mit required gleich true in der Spalte. NOT NULL in der Datenbank verhindert kein leeres Textfeld.
- In Extbase über Validatoren an Modellen und Action-Parametern.
- Im Form Framework über die Validatoren der Formularelemente.
Prüfungen im Browser, etwa das HTML-Attribut required, sind nur Komfort. Man kann sie umgehen und Anfragen ohne Formular senden. Darum prüft immer auch der Server.
Das Wichtigste in Kürze
- Schreiben passiert erst bei
persistAll(), das Extbase nach jedem Plugin-Durchlauf aufruft. - Geänderte Objekte speichert Extbase ohne
update(). Die neue UID gibt es erst nach dem Speichern. - Eigenschaften sind protected und brauchen eine TCA-Spalte.
- Abweichende Namen und Single Table Inheritance stehen in
Classes.php. - Statt magischer Finder nimmst du
findBy(),findOneBy()undcount()mit einem Array. - Eine leere Liste liegt meist an der storagePid.
matching()nimmt genau einen Constraint.- Es zählen nur PHP-Attribute mit benannten Parametern.
- Eigene Validatoren erweitern
AbstractValidatorund werden mit vollem Klassennamen eingebunden. - TCA und Extbase validieren getrennt, und der Server prüft immer.
Begriffe
- Dirty Tracking
- Extbase erkennt geänderte Eigenschaften selbst und schreibt nur diese.
- Enable-Fields
- Sichtbarkeitsfelder wie versteckt, Startzeit, Endzeit und Benutzergruppe.
- Identity Map
- Verzeichnis geladener Objekte, derselbe Datensatz ergibt dasselbe Objekt.
- ObjectStorage
- Sammlung von Objekten für Relationen auf mehrere Objekte.
- ORM
- Object-Relational Mapping, die Übersetzung zwischen Objekten und Tabellenzeilen.
- Property Mapping
- Umwandeln der Request-Daten in PHP-Typen und Objekte.
- Single Table Inheritance
- Mehrere Klassen in einer Tabelle, unterschieden durch eine Typspalte.
- storagePid
- Seite oder Seiten, auf denen ein Repository nach Datensätzen sucht.