Model
Introduction
All classes of the domain model should inherit from the class
\TYPO3\
.
An entity is an object fundamentally defined not by its attributes, but by a thread of continuity and identity, for example, a person or a blog post.
Objects stored in the database are usually entities as they can be identified
by the uid
and are persisted, therefore have continuity.
In the TYPO3 backend models are displayed as Database records.
Example:
class Comment extends AbstractEntity
{
protected string $author = '';
protected string $content = '';
public function getAuthor(): string
{
return $this->author;
}
public function setAuthor(string $author): void
{
$this->author = $author;
}
public function getContent(): string
{
return $this->content;
}
public function setContent(string $content): void
{
$this->content = $content;
}
}
Connecting the model to the database
It is possible to define models that are not persisted to the database. However in the most common use cases you want to save your model to the database and load it from there. See Persistence.
Properties
The properties of a model can be defined either as public class properties:
final class Tag extends AbstractValueObject
{
public string $name = '';
public int $priority = 0;
}
Or public getters:
class Info extends AbstractEntity
{
protected string $name = '';
protected string $bodytext = '';
public function getName(): string
{
return $this->name;
}
public function getBodytext(): string
{
return $this->bodytext;
}
public function setBodytext(string $bodytext): void
{
$this->bodytext = $bodytext;
}
}
A public getter takes precedence over a public property. Getters have the advantage that you can make the properties themselves protected and decide which ones should be mutable.
Note
Making model's properties private
does not work in Extbase models: The parent
classes need to access the models properties directly. If your model must
not be extended you can mark it as final
and thereby prevent
other developers from extending your model.
It is also possible to have getters for properties that are not persisted and get created on the fly:
class Info extends AbstractEntity
{
protected string $name = '';
protected string $bodytext = '';
public function getCombinedString(): string
{
return $this->name . ': ' . $this->bodytext;
}
}
One disadvantage of using additional getters is that properties that are only defined as getters do not get displayed in the debug output in Fluid, they do however get displayed when explicitly called:
Does not display "combinedString":
<f:debug>{post.info}</f:debug>
But it is there:
<f:debug>{post.info.combinedString}</f:debug>
Union types
New in version 12.3
Previously, whenever a union type was needed, union type declarations led Extbase not detecting any type at all, resulting in the property not being mapped. However, union types could be resolved via docblocks. Since TYPO3 v12.3 native PHP union types can be used.
Union types can be used in properties of an entity, for example:
<?php
declare(strict_types=1);
namespace MyVendor\MyExtension\Domain\Model\MyEntity;
use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;
use TYPO3\CMS\Extbase\Persistence\Generic\LazyLoadingProxy;
class Entity extends AbstractEntity
{
private ChildEntity|LazyLoadingProxy $property;
}
This is especially useful for lazy-loaded relations where the property type is
Child
.
There is something important to understand about how Extbase detects union types when it comes to property mapping, that means when a database row is mapped onto an object. In this case, Extbase needs to know the desired target type - no union, no intersection, just one type. In order to achieve this, Extbase uses the first declared type as a so-called primary type.
<?php
declare(strict_types=1);
namespace MyVendor\MyExtension\Domain\Model\MyEntity;
use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;
class Entity extends AbstractEntity
{
private string|int $property;
}
In this case, string
is the primary type. int
would result
in int
as primary type.
There is one important thing to note and one exception to this rule. First of
all, null
is not considered a type. null
results in the
primary type string
which is nullable.
null
also results in the primary type string
. In fact,
null
means that all other types are nullable. null
boils down to ?string
or ?int
.
Secondly, Lazy
is never detected as a primary type because it
is just a proxy and not the actual target type, once loaded.
<?php
declare(strict_types=1);
namespace MyVendor\MyExtension\Domain\Model\MyEntity;
use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;
use TYPO3\CMS\Extbase\Persistence\Generic\LazyLoadingProxy;
class Entity extends AbstractEntity
{
private LazyLoadingProxy|ChildEntity $property;
}
Extbase supports this and detects Child
as the primary type,
although Lazy
is the first item in the list. However, it is
recommended to place the actual type first, for consistency reasons:
Child
.
A final word on \TYPO3\
:
it is a subclass of \TYPO3\
,
therefore the following code works and has always worked:
<?php
declare(strict_types=1);
namespace MyVendor\MyExtension\Domain\Model\MyEntity;
use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;
use TYPO3\CMS\Extbase\Persistence\ObjectStorage;
class Entity extends AbstractEntity
{
/**
* @var ObjectStorage<ChildEntity>
* @TYPO3\CMS\Extbase\Annotation\ORM\Lazy
*/
private ObjectStorage $property;
}
Relations
Extbase supports different types of hierarchical relationships between domain objects. All relationships can be defined unidirectional or multidimensional in the model.
On the side of the relationship that can only have one counterpart, you must decide whether it is possible to have no relationship (allow null) or not.
Nullable relations
There are two ways to allow null
for a property in PHP:
-
Mark the type declaration as nullable by prefixing the type name with a question mark:
protected ?Person $secondAuthor = null;
Copied! -
Use a union type:
protected Person|null $secondAuthor = null;
Copied!
Both declarations have the same meaning.
1:1-relationship
A blog post can have, in our case, exactly one additional info attached to it. The info always belongs to exactly one blog post. If the blog post gets deleted, the info does get related.
class Post extends AbstractEntity
{
/**
* 1:1 optional relation
*/
protected ?Info $additionalInfo;
public function getAdditionalInfo(): ?Info
{
return $this->additionalInfo;
}
public function setAdditionalInfo(?Info $additionalInfo): void
{
$this->additionalInfo = $additionalInfo;
}
}
1:n-relationship
A blog can have multiple posts in it. If a blog is deleted all of its posts should be deleted. However a blog might get displayed without displaying the posts therefore we load the posts of a blog lazily:
use TYPO3\CMS\Extbase\Persistence\ObjectStorage;
class Blog extends AbstractEntity
{
/**
* The posts of this blog
* @var ObjectStorage<Post>
*/
public $posts;
/**
* Adds a post to this blog
*/
public function addPost(Post $post)
{
$this->posts->attach($post);
}
/**
* Remove a post from this blog
*/
public function removePost(Post $postToRemove)
{
$this->posts->detach($postToRemove);
}
/**
* Returns all posts in this blog
*
* @return ObjectStorage
*/
public function getPosts(): ObjectStorage
{
return $this->posts;
}
/**
* @param ObjectStorage<Post> $posts
*/
public function setPosts(ObjectStorage $posts): void
{
$this->posts = $posts;
}
}
Note
Note the subtle differences here. The methods set
and
get
refer simultaneously to all blog posts.
They expect and hence provide an Object
object.
The methods add
and remove
refer to a single
post object that is added to the list or removed from.
Attention
It is possible to get an array of objects from an Object
by calling $this->posts->to
. However doing so and looping
the resulting array might cause performance problems.
Each post belongs to exactly one blog, of course a blog does not get deleted when one of its posts gets deleted.
class Post extends AbstractEntity
{
protected Blog $blog;
}
A post can also have multiple comments and each comment belongs to exactly one blog. However we never display a comment without its post therefore we do not need to store information about the post in the comment's model: The relationship is unidirectional.
use TYPO3\CMS\Extbase\Persistence\ObjectStorage;
class Post extends AbstractEntity
{
/**
* @var ObjectStorage<Comment>
*/
public ObjectStorage $comments;
}
The model of the comment has no property to get the blog post in this case.
n:1-relationships
n:1-relationships are the same like 1:n-relationsships but from the perspective of the object:
Each post has exactly one main author but an author can write several blog posts or none at all. He can also be a second author and no main author.
class Post extends AbstractEntity
{
/**
* @var Person
*/
protected Person $author;
protected Person|null $secondAuthor;
}
Once more the model of the author does not have a property containing the authors posts. If you would want to get all posts of an author you would have to make a query in the PostRepository taking one or both relationships (first author, second author) into account.
m:n-relationship
A blog post can have multiple categories, each category can belong to multiple blog posts.
class Post extends AbstractEntity
{
/**
* @var Person
*/
protected ?Person $author = null;
protected ?Person $secondAuthor = null;
}
Hydrating objects
Hydrating (the term originates from doctrine/orm), or in Extbase terms thawing,
is the act of creating an object from a given database row. The responsible
class involved is the \TYPO3\
.
During the process of hydrating, the Data
creates objects to map
the raw database data onto.
Before diving into the framework internals, let us take a look at models from the user's perspective.
Creating objects with constructor arguments
Imagine you have a table tx_
and a
corresponding model or entity (entity is used as a synonym here)
\My
.
Now, also imagine there is a domain rule which states, that all blogs must have
a title. This rule can easily be followed by letting the blog class have a
constructor with a required argument string $title
.
<?php
declare(strict_types=1);
namespace MyVendor\MyExtension\Domain\Model;
use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;
use TYPO3\CMS\Extbase\Persistence\ObjectStorage;
class Blog extends AbstractEntity
{
protected ObjectStorage $posts;
public function __construct(protected string $title)
{
$this->posts = new ObjectStorage();
}
}
This example also shows how the posts
property is initialized. It is done in
the constructor because PHP does not allow setting a default value that is of
type object.
Hydrating objects with constructor arguments
Whenever the user creates new blog objects in extension code, the aforementioned
domain rule is followed. It is also possible to work on the posts
Object
without further initialization. new Blog
is
all one need to create a blog object with a valid state.
What happens in the Data
however, is a totally different thing.
When hydrating an object, the Data
cannot follow any domain rules.
Its only job is to map the raw database values onto a Blog
instance. The
Data
could of course detect constructor arguments and try to guess
which argument corresponds to what property, but only if there is an easy
mapping, that means, if the constructor takes the argument string $title
and updates the property title
with it.
To avoid possible errors due to guessing, the Data
simply ignores
the constructor at all. It does so with the help of the library
doctrine/instantiator.
But there is more to all this.
Initializing objects
Have a look at the $posts
property in the example above. If the
Data
ignores the constructor, that property is in an invalid state,
that means, uninitialized.
To address this problem and possible others, the Data
will call the
method initialize
on models, if it exists.
Here is an updated version of the model:
<?php
declare(strict_types=1);
namespace MyVendor\MyExtension\Domain\Model;
use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;
use TYPO3\CMS\Extbase\Persistence\ObjectStorage;
class Blog extends AbstractEntity
{
protected ObjectStorage $posts;
public function __construct(protected string $title)
{
$this->initializeObject();
}
public function initializeObject(): void
{
$this->posts = new ObjectStorage();
}
}
This example demonstrates how Extbase expects the user to set up their models.
If the method initialize
is used for initialization logic that
needs to be triggered on initial creation and on hydration. Please mind
that __
should call initialize
.
If there are no domain rules to follow, the recommended way to set up a model
would then still be to define a __
and
initialize
method like this:
<?php
declare(strict_types=1);
namespace MyVendor\MyExtension\Domain\Model;
use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;
use TYPO3\CMS\Extbase\Persistence\ObjectStorage;
class Blog extends AbstractEntity
{
protected ObjectStorage $posts;
public function __construct()
{
$this->initializeObject();
}
public function initializeObject(): void
{
$this->posts = new ObjectStorage();
}
}
Mutating objects
Some few more words on mutators (setter, adder, etc.). One might think that
Data
uses mutators during object hydration but it does not.
Mutators are the only way for the user (developer) to implement business rules
besides using the constructor.
The Data
uses the internal method
Abstract
to update object properties. This
looks a bit dirty and is a way around all business rules but that is what the
Data
needs in order to leave the mutators to the users.
Warning
While the Data
does not use any mutators, other parts of
Extbase do. Both, validation and property
mapping, either use existing mutators or gather type information from them.
Property visibility
One important thing to know is that Extbase needs entity properties to be
protected or public. As written in the former paragraph,
Abstract
is used to bypass setters.
However, Abstract
is not able to access private properties of
child classes, hence the need to have protected or public properties.
Dependency injection
Without digging too deep into dependency injection the following statements have to be made:
- Extbase expects entities to be so-called prototypes, that means classes that do have a different state per instance.
Data
does not use dependency injection for the creation of entities, that means it does not query the object container. This also means, that dependency injection is not possible in entities.Mapper
If you think that your entities need to use/access services, you need to find other ways to implement it.
Event
The PSR-14 event AfterObjectThawedEvent is available to modify values when creating domain objects.
Eager loading and lazy loading
By default, Extbase loads all child objects with the parent object (so for
example, all posts of a blog). This behavior is called eager loading.
The annotation @TYPO3\
causes Extbase to
load and build the objects only when they
are actually needed (lazy loading). This can lead to a significant
increase in performance.
On cascade remove
The annotation @TYPO3\
has
the effect that, if a blog is deleted, its posts will also be deleted
immediately. Extbase usually leaves all child objects' persistence unchanged.
Besides these two, there are a few more annotations available, which will be used in other contexts. For the complete list of all Extbase supported annotations, see the chapter Annotations.
Identifiers in localized models
Domain models have a main identifier uid
and an additional property
_localized
.
Depending on whether the
language
mode is enabled (true
or
'hide
) or disabled (false
),
the identifier contains different values.
When language
is enabled, then the uid
property contains the uid
value of the default language record,
the uid
of the translated record is kept in the _localized
.
Context | Record in language 0 | Translated record |
---|---|---|
Database | uid:2 | uid:11, l10n_parent:2 |
Domain object values with language enabled | uid:2, _localizedUid:2 | uid:2, _localizedUid:11 |
Domain object values with language disabled | uid:2, _localizedUid:2 | uid:11, _localizedUid:11 |
Hint
In case your project uses EXT:workspaces there is yet another
additional property, _versioned
. Refer to the
Workspaces documentation for details on
workspace overlays.
Extending existing models
It is possible, with some limitations, to extend existing Extbase models in another extension. See also Tutorial: Extending an Extbase model.