Extbase Reference¶

Caching of actions and records¶

Furthermore, Extbase is clearing the TYPO3 cache automatically for update processes. This is called Automatic cache clearing. This functionality is activated by default. If a domain object is inserted, changed or deleted, then the cache of the corresponding page in which the object is located is cleared. Additionally the setting of TSConfig TCEMAIN.clearCacheCmd is evaluated for this page.

Figure B-2 is an example that is explained below:

Figure B-2: For the sysfolder in which the data was stored, the setting TCEMAIN.clearCacheCmd defines that the cache of the page Blog should be emptied.

The frontend plugin is on the page Blog with the 11. As a storage folder for all the Blogs and Posts the SysFolder BLOGS is configured. If an entry is changed, the cache of the SysFolder BLOGS is emptied and also the TSConfig configuration TCEMAIN.clearCacheCmd for the SysFolder is evaluated. This contains a comma-separated list of Page IDs, for which the cache should be emptied. In this case, when updating a record in the SysFolder BLOGS (e.g. Blogs, Posts, Comments), the cache of the page Blog, with ID 11, is cleared automatically, so the changes are immediately visible.

Even if the user enters incorrect data in a form (and this form will be displayed again), the cache of the current page is deleted to force a new representation of the form.

The automatic cache clearing is enabled by default, you can use the TypoScript configuration persistence.enableAutomaticCacheClearing to disable it.

features¶

Activate features for Extbase or a specific plugin.

features.skipDefaultArguments

Skip default arguments in URLs. If a link to the default controller or action is created, the parameters are omitted. Default is false.

features.ignoreAllEnableFieldsInBe

Ignore the enable fields in backend. Default is false.

features.requireCHashArgumentForActionArguments

Do not force a cHash for arguments used in actions. If this is turned on, all requests with arguments but no, or an invalid cHash, are handled as pageNotFoundOnCHashError. Default is true.

features.consistentTranslationOverlayHandling

Use the same translation handling in extbase as in TypoScript. Used via config.tx_extbase.features.consistentTranslationOverlayHandling. The feature switch will be removed in TYPO3 v10 and the behaviour will become the only way translations are handled.

persistence¶

Settings relevant to the persistence layer of Extbase.

persistence.classes

This settings are used with individual classes. That includes in particular the mapping of classes and property names to tables and field names.

persistence.classes.Vendor\MyExt\Domain\Model\Foo.mapping.columns

Configure fields which differ from the regular naming conventions. Use the form field_name.mapOnProperty = propertyName.

persistence.classes.Vendor\MyExt\Domain\Model\Foo.mapping.recordType

Specify a string literal, which - if set - should be stored in the type field of the table.

persistence.classes.Vendor\MyExt\Domain\Model\Foo.mapping.tableName

Set a table name which differs from the regular naming conventions.

persistence.classes.Vendor\MyExt\Domain\Model\Foo.newRecordStoragePid

Page-ID in which new records of the given class should be saved.

persistence.classes.Vendor\MyExt\Domain\Model\Foo.subclasses

List all subclasses of the class given in the form Identifier = ClassName.

persistence.enableAutomaticCacheClearing

Enables the automatic cache clearing when changing data sets (see also the section “Caching of actions and records” above in this chapter). Default is true.

persistence.storagePid

List of Page-IDs, from which all records are read (see the section “Procedure to fetch objects” in Chapter 6).

settings¶

Here reside are all the domain-specific extension settings. These settings are available in the controllers as the array variable $this->settings and in any Fluid template with {settings}.

view¶

View and template settings.

view.layoutRootPaths

This can be used to specify the root paths for all fluid layouts in this extension. If nothing is specified, the path extensionName/Resources/Private/Layouts is used. All layouts that are necessary for this extension should reside in this folder.

view.partialRootPaths

This can be used to specify the root paths for all fluid partials in this extension. If nothing is specified, the path extensionName/Resources/Private/Partials is used. All partials that are necessary for this extension should reside in this folder.

view.pluginNamespace

This can be used to specify an alternative namespace for the plugin. Use this to shorten the Extbase default plugin namespace or to access arguments from other extensions by setting this option to their namespace. .. todo: This is not understandable without an example.

view.templateRootPaths

This can be used to specify the root paths for all fluid templates in this extension. If nothing is specified, the path extensionName/Resources/Private/Templates is used. All layouts that are necessary for this extension should reside in this folder.

All root paths are defined as array which enables you to define multiple root paths that will be used by Extbase to find the desired template files.

The feature is best described by an example. Imagine you installed the extension news, which provides several plugins for rendering news in the frontend.

The default template directory of that extension is the following:

EXT:news/Resources/Private/Templates/

Let’s assume you want to change the output of the plugins because you need to use different css classes for example. You can simply create your own extension and add the following TypoScript setup:

plugin.tx_news {
    view {
        templateRootPaths.10 = EXT:example_extension/Resources/Private/Templates/
    }
}

As all typoscript will be merged, the following configuration will be compiled:

plugin.tx_news {
    view {
        templateRootPaths {
            0 = EXT:news/Resources/Private/Templates/
            10 = EXT:example_extension/Resources/Private/Templates/
        }
        ...
    }
}

Imagine there is a news plugin that lists news entries. In that case, the listAction method of the NewsController will be called. By convention, Extbase will look for an html file called List.html in a folder News in all of the configured template root paths.

If there is just one root path configured, that’s the one being chosen right away. Once there are more paths defined, Extbase will check them in reverse order i.e. from highest key to lowest. Following our example, Extbase will check the given path with key 10 first and if no template file is found, it will proceed with 0.

More information on root paths can be found in the TypoScript reference: templateRootPaths

mvc¶

These are useful mvc settings about error handling:

mvc.callDefaultActionIfActionCantBeResolved

Will cause the controller to show its default action e.g. if the called action is not allowed by the controller.

mvc.throwPageNotFoundExceptionIfActionCantBeResolved

Same as mvc.callDefaultActionIfActionCantBeResolved but this will raise a “page not found” error.

_LOCAL_LANG¶

Under this key you can modify localized strings for this extension. If you specify for example plugin.tx_blogexample._LOCAL_LANG.default.read_more = More>> then the standard translation for the key read_more is overwritten by the string More>>.

ActionController API¶

The action controller is usually the base class for your own controller. Below you see the most important properties of the action controller:

$actionMethodName

Name of the executed action.

$argumentMappingResults

Results of the argument mapping. Is used especially in the errorAction.

$defaultViewObjectName

Name of the default view, if no fluid-view or an action-specific view was found.

$errorMethodName

Name of the action that is performed when generating the arguments of actions fail. Default is errorAction. In general, it is not sensible to change this.

$request

Request object of type \TYPO3\CMS\Extbase\Mvc\RequestInterface.

$response

Response object of type \TYPO3\CMS\Extbase\Mvc\ResponseInterface.

$settings

Domain-specific extension settings from TypoScript (as array), see settings.

$view

The view used of type \TYPO3\CMS\Extbase\Mvc\View\ViewInterface.

$viewObjectNamePattern

If no fluid template is found for the current action, Extbase attempts to find a PHP-View-Class for the action. The naming scheme of the PHP-View-Class can be changed here. By default names are used according to the scheme @vendor@extensionView@controller@action@format. All string-parts marked with @ are replaced by the corresponding values. If no view class with this name is found, @format is removed from the pattern and again tried to find a view class with that name.

Most important API methods of action controller¶

Action()

Defines an action.

errorAction()

Standard error action. Needs to be adjusted only in very rare cases. The name of this method is defined by the property $errorMethodName.

forward($actionName, $controllerName = NULL, $extensionName = NULL, array $arguments = NULL)

Issues an immediate internal forwarding of the request to another controller.

initializeAction()

Initialization method for all actions. Can be used to e.g. register arguments.

initialize[actionName]Action()

Action-specific initialization, which is called only before the specific action. Can be used to e.g. register arguments.

initializeView(\TYPO3\CMS\Extbase\Mvc\View\ViewInterface $ view)

Initialization method to configure and initialize the passed view.

redirect($actionName, $controllerName = NULL, $extensionName = NULL, array $arguments = NULL, $pageUid = NULL, $delay = 0, $statusCode = 303)

External HTTP redirect to another controller (immediately)

redirectToURI($uri, $delay = 0, $statusCode = 303)

Redirect to full URI (immediately)

resolveView()

By overriding this method you can build and configure a completely individual view object. This method should return a complete view object. In general, however, it is sufficient to overwrite resolveViewObjectName().

resolveViewObjectName()

Resolves the name of the view object, if no suitable fluid template could be found.

throwStatus($statusCode, $statusMessage = NULL, $content = NULL)

The specified HTTP status code is sent immediately.

Actions¶

All public and protected methods that end in action (for example indexAction or showAction), are automatically registered as actions of the controller.

Many of these actions have parameters. These appear as annotations in the Doc-Comment-Block of the specified method, as shown in Example B-3:

Example B-3: Actions with parameters

<?php
declare(strict_types = 1);

namespace Ex\BlogExample\Controller;

use TYPO3\CMS\Extbase\Annotation as Extbase;
use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;

class BlogController extends ActionController
{
    /**
     * Displays a form for creating a new blog, optionally pre-filled with partial information.
     *
     * @param \Ex\BlogExample\Domain\Model\Blog $newBlog A fresh blog object which should be taken
     *        as a basis for the form if it is set.
     *
     * @return void
     *
     * @Extbase\IgnoreValidation("newBlog")
     */
    public function newAction(\Ex\BlogExample\Domain\Model\Blog $newBlog = NULL)
    {
        $this->view->assign('newBlog', $newBlog);
    }
}

It is important to specify the full type in the @param annotation as this is used for the validation of the object. Note that not only simple data types such as String, Integer or Float can be validated, but also complex object types (see also the section “Validating domain objects” in Chapter 9).

In addition, on actions showing the forms used to create domain objects, the validation of domain objects must be explicitly disabled - therefore the annotation @TYPO3\CMS\Extbase\Annotation\IgnoreValidation is necessary.

Default values can, as usual in PHP, just be indicated in the method signature. In the above case, the default value of the parameter $newBlog is set to NULL. If an action returns NULL or nothing, then automatically $this->view->render() is called, and thus the view is rendered.

Define initialization code¶

Sometimes it is necessary to execute code before calling an action. For example, if complex arguments must be registered or required classes must be instantiated.

There is a generic initialization method called initializeAction(), which is called after the registration of arguments, but before calling the appropriate action method itself. After the generic initializeAction(), if it exists, a method named initialize[ActionName]() is called. Here you can perform action specific initializations (e.g. initializeShowAction()).

Catching validation errors with errorAction¶

If an argument validation error has occurred, the method errorAction() is called. There, in $this->argumentsMappingResults you have a list of occurred warnings and errors of the argument mappings available. This default errorAction refers back to the referrer, if the referrer was sent with it.

Domain model¶

All classes of the domain model must inherit from one of the following two classes:

\TYPO3\CMS\Extbase\DomainObject\AbstractEntity

Is used if the object is an entity, i.e. possesses an identity.

\TYPO3\CMS\Extbase\DomainObject\AbstractValueObject

Is used if the object is a ValueObject, i.e. if its identity is defined by all of its properties. ValueObjects are immutable.

Repositories¶

All repositories inherit from \TYPO3\CMS\Extbase\Persistence\Repository. A repository is always responsible for precisely one type of domain object. The naming of the repositories is important: If the domain object is, for example, Blog (with full name \\Ex\\BlogExample\\Domain\\Model\\Blog), then the corresponding repository is named BlogRepository (with full name \\Ex\\BlogExample\\Domain\\Repository\\BlogRepository).

/**
 * Find blogs, which have the given category.
 *
 * @param \Ex\BlogExample\Domain\Model\Category $category
 *
 * @return \TYPO3\CMS\Extbase\Persistence\Generic\QueryResult
 */
public function findWithCategory(\Ex\BlogExample\Domain\Model\Category $category)
{
    $query = $this->createQuery();
    $query->matching($query->contains('categories', $category));
    return $query->execute();
}

Validation API¶

Extbase provides a generic validation system which is used in many places in Extbase. Extbase provides validators for common data types, but you can also write your own validators. Each Validator implements the \TYPO3\CMS\Extbase\Validation\Validator\ValidatorInterface that defines the following methods:

validate($value)

Checks whether the object that was passed to the validator is valid. If not, a \TYPO3\CMS\Extbase\Validation\Error object should be returned.

getOptions()

Enables you to define validator options. These options apply to any further call of the method validate().

You can call Validators in your own code with the method createValidator($validatorName, $validatorOptions) in \TYPO3\CMS\Extbase\Validation\ValidatorResolver. Though in general, this is not necessary. Validators are often used in conjunction with domain objects and controller actions.

Validation of model properties¶

You can define simple validation rules in the domain model by annotation. For this, you use the annotation @TYPO3\CMS\Extbase\Annotation\Validate with properties of the object. A brief example:

Example B-4: validation in the domain object

namespace Ex\BlogExample\Domain\Model;

/**
 * A single blog which has multiple posts and can be read by users.
 */
class Blog extends \TYPO3\CMS\Extbase\DomainObject\AbstractEntity
{
    /**
     * The blog's title.
     *
     * @var string
     * @TYPO3\CMS\Extbase\Annotation\Validate("Text")
     * @TYPO3\CMS\Extbase\Annotation\Validate("StringLength", options={"minimum": 1, "maximum": 80})
     */
    protected $title;

    // the class continues here
}

In this code section, the validators for the $title attribute of the Blog object is defined. $title must be a text (ie, no HTML is allowed), and also the length of the string is checked with the StringLength-Validator (it must be between 1 and 80 characters). Several validators for a property can be separated by commas. Parameter of the validators are set in parentheses. You can omit the quotes for validator options if they are superfluous as in the example above. If complex validation rules are necessary (for example, multiple fields to be checked for equality), you must implement your own validator.

Validation of controller arguments¶

Each controller argument is validated by the following rules:

• If the argument has a simple type (string, integer, etc.), this type is checked.
• If the argument is a domain object, the annotations @TYPO3\CMS\Extbase\Annotation\Validate in the domain object is taken into account and - if set - the appropriate validator in the folder Domain/Validator for the existing domain object is run.
• If there is set an annotation @TYPO3\CMS\Extbase\Annotation\IgnoreValidation for the argument, no validation is done.
• Additional validation rules can be specified via further @TYPO3\CMS\Extbase\Annotation\Validate annotations in the methods PHPDoc block.

If the arguments of an action can not be validated, then the errorAction is executed, which will usually jump back to the last screen. It is important that validation is not performed in certain cases. Further information for the usage of the annotation @TYPO3\CMS\Extbase\Annotation\IgnoreValidation see “Case study: Edit an existing object” in Chapter 9.