URI builder (Extbase)

The URI builder offers a convenient way to create links in an Extbase context.

Usage in an Extbase controller

The URI builder is available as a property in a controller class which extends the ActionController class. The request context is automatically available to the UriBuilder.

Example:

EXT:my_extension/Classes/Controller/MyController.php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller\MyController;

use Psr\Http\Message\ResponseInterface;
use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;

final class MyController extends ActionController
{
    public function myAction(): ResponseInterface
    {
        $url = $this->uriBuilder
            ->reset()
            ->setTargetPageUid(42)
            ->uriFor(
                'anotherAction',
                [
                    'myRecord' => 21,
                ],
                'MyController',
                'myextension',
                'myplugin',
            );

        // do something with $url
    }
}
Copied!

Have a look into the API for the available methods of the URI builder.

Usage in another context

The class \TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder can be injected via constructor in a class:

EXT:my_extension/Classes/MyClass.php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\MyClass;

use Psr\Http\Message\ServerRequestInterface;
use TYPO3\CMS\Extbase\Mvc\ExtbaseRequestParameters;
use TYPO3\CMS\Extbase\Mvc\Request;
use TYPO3\CMS\Extbase\Mvc\RequestInterface;
use TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder;

final class MyClass
{
    public function __construct(
        private readonly UriBuilder $uriBuilder,
    ) {}

    public function doSomething()
    {
        $this->uriBuilder->setRequest($this->getExtbaseRequest());

        $url = $this->uriBuilder
            ->reset()
            ->setTargetPageUid(42)
            ->uriFor(
                'myAction',
                [
                    'myRecord' => 21,
                ],
                'MyController',
                'myextension',
                'myplugin',
            );

        // do something with $url
    }

    private function getExtbaseRequest(): RequestInterface
    {
        /** @var ServerRequestInterface $request */
        $request = $GLOBALS['TYPO3_REQUEST'];

        // We have to provide an Extbase request object
        return new Request(
            $request->withAttribute('extbase', new ExtbaseRequestParameters()),
        );
    }
}
Copied!

Changed in version 12.2

The Extbase request object should be set via the setRequest() method before using the URI builder. If not done, a deprecation notice will be raised. In TYPO3 v13 setting the request object before first usage will be mandatory.

Example in Extbase ViewHelper

EXT:my_extension/Classes/ViewHelper/MyLinkViewHelper.php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller\MyController;

use Psr\Http\Message\ServerRequestInterface;
use TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder;
use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper;

final class MyLinkViewHelper extends AbstractViewHelper
{
    public function __construct(private UriBuilder $uriBuilder) {}

    public function render(): string
    {
        if ($this->renderingContext->hasAttribute(ServerRequestInterface::class)) {
            // TYPO3 v13+ compatibility
            $request = $this->renderingContext->getAttribute(ServerRequestInterface::class);
        } else {
            throw new \RuntimeException(
                'The rendering context of this ViewHelper is missing a valid request object, probably because it is used outside of Extbase context.',
                1730537505,
            );
        }

        // Request context is needed before $this->uriBuilder is first used for returning links.
        // Note: this will not be reset on calling $this->uriBuilder->reset()!
        $this->uriBuilder->setRequest($request);

        $url = $this->uriBuilder
            ->reset()
            ->setTargetPageUid(2751)
            ->uriFor(
                'anotherAction',
                [
                    'myRecord' => 21,
                ],
                'MyController',
                'myextension',
                'myplugin',
            );

        // do something with $url, for example:
        return 'Link: ' . $url . '</a>';
    }
}
Copied!

API

class UriBuilder
Fully qualified name
\TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder

URI Builder for extbase requests.

setRequest ( \TYPO3\CMS\Extbase\Mvc\RequestInterface $request)

Sets the current request

param $request

the request

Return description

The current UriBuilder to allow method chaining

Returns
static
setArguments ( array $arguments)

Additional query parameters.

If you want to "prefix" arguments, you can pass in multidimensional arrays: array('prefix1' => array('foo' => 'bar')) gets "&prefix1[foo]=bar"

param $arguments

the arguments

Return description

The current UriBuilder to allow method chaining

Returns
static
setSection ( string $section)

If specified, adds a given HTML anchor to the URI (#...)

param $section

the section

Return description

The current UriBuilder to allow method chaining

Returns
static
setFormat ( string $format)

Specifies the format of the target (e.g. "html" or "xml")

param $format

the format

Return description

The current UriBuilder to allow method chaining

Returns
static
setCreateAbsoluteUri ( bool $createAbsoluteUri)

If set, the URI is prepended with the current base URI. Defaults to FALSE.

param $createAbsoluteUri

the createAbsoluteUri

Return description

The current UriBuilder to allow method chaining

Returns
static
setAbsoluteUriScheme ( string $absoluteUriScheme)

Sets the scheme that should be used for absolute URIs in FE mode

param $absoluteUriScheme

the scheme to be used for absolute URIs

Return description

The current UriBuilder to allow method chaining

Returns
static
setLanguage ( ?string $language)

Enforces a URI / link to a page to a specific language (or use "current")

param $language

the language

Returns
\TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder
setAddQueryString ( string|int|bool $addQueryString)

If set, the current query parameters will be merged with $this->arguments in backend context.

In frontend context, setting this property will only include mapped query arguments from the Page Routing. To include any - possible "unsafe" - GET parameters, the property has to be set to "untrusted". Defaults to FALSE.

param $addQueryString

is set to "1", "true", "0", "false" or "untrusted"

Return description

The current UriBuilder to allow method chaining

Returns
static
setArgumentsToBeExcludedFromQueryString ( array $argumentsToBeExcludedFromQueryString)

A list of arguments to be excluded from the query parameters Only active if addQueryString is set

param $argumentsToBeExcludedFromQueryString

the argumentsToBeExcludedFromQueryString

Return description

The current UriBuilder to allow method chaining

Returns
static
setArgumentPrefix ( string $argumentPrefix)

Specifies the prefix to be used for all arguments.

param $argumentPrefix

the argumentPrefix

Return description

The current UriBuilder to allow method chaining

Returns
static
setLinkAccessRestrictedPages ( bool $linkAccessRestrictedPages)

If set, URIs for pages without access permissions will be created

param $linkAccessRestrictedPages

the linkAccessRestrictedPages

Return description

The current UriBuilder to allow method chaining

Returns
static
setTargetPageUid ( int $targetPageUid)

Uid of the target page

param $targetPageUid

the targetPageUid

Return description

The current UriBuilder to allow method chaining

Returns
static
setTargetPageType ( int $targetPageType)

Sets the page type of the target URI. Defaults to 0

param $targetPageType

the targetPageType

Return description

The current UriBuilder to allow method chaining

Returns
static
setNoCache ( bool $noCache)

by default FALSE; if TRUE, &no_cache=1 will be appended to the URI

param $noCache

the noCache

Return description

The current UriBuilder to allow method chaining

Returns
static
reset ( )

Resets all UriBuilder options to their default value

Return description

The current UriBuilder to allow method chaining

Returns
static
uriFor ( ?string $actionName = NULL, ?array $controllerArguments = NULL, ?string $controllerName = NULL, ?string $extensionName = NULL, ?string $pluginName = NULL)

Creates a URI used for linking to an Extbase action.

Works in Frontend and Backend mode of TYPO3.

param $actionName

Name of the action to be called, default: NULL

param $controllerArguments

Additional query parameters. Will be "namespaced" and merged with $this->arguments., default: NULL

param $controllerName

Name of the target controller. If not set, current ControllerName is used., default: NULL

param $extensionName

Name of the target extension, without underscores. If not set, current ExtensionName is used., default: NULL

param $pluginName

Name of the target plugin. If not set, current PluginName is used., default: NULL

Return description

The rendered URI

Returns
string
build ( )

Builds the URI Depending on the current context this calls buildBackendUri() or buildFrontendUri()

Return description

The URI

Returns
string