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.
Example:
<?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
}
}
Have a look into the API for the available methods of the URI builder.
Attention
As the URI builder holds state, you have to call reset()
before
creating a URL.
Usage in another context¶
The class \TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder
can be injected
via constructor in a class:
<?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()),
);
}
}
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.
Note
In the above example, the PSR-7 request object is
retrieved from the global variable TYPO3_REQUEST
. This is not
recommended and is only a fallback. See the section
Getting the PSR-7 request object to learn how to retrieve the request
PSR-7 object depending on the context.
Attention
When using the URI builder to build frontend URLs, the current content object is required. It is initialized from the handed in local request object. In case extensions set the request object without the request attribute currentContentObject, an automatic fallback is applied in TYPO3 v12, triggering a PHP deprecation warning. The fallback has been removed in TYPO3 v13.
API¶
- class \TYPO3\CMS\Extbase\Mvc\Web\Routing\ UriBuilder¶
-
URI Builder for extbase requests.
- setRequest ( TYPO3\\CMS\\Extbase\\Mvc\\RequestInterface $request) ¶
-
Sets the current request
- param TYPO3\\CMS\\Extbase\\Mvc\\RequestInterface $request
-
the request
- returntype
-
TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder
- Returns:
-
static the current UriBuilder to allow method chaining
- 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 array $arguments
-
the arguments
- returntype
-
TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder
- Returns:
-
static the current UriBuilder to allow method chaining
- setSection ( string $section) ¶
-
If specified, adds a given HTML anchor to the URI (#...)
- param string $section
-
the section
- returntype
-
TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder
- Returns:
-
static the current UriBuilder to allow method chaining
- setFormat ( string $format) ¶
-
Specifies the format of the target (e.g. "html" or "xml")
- param string $format
-
the format
- returntype
-
TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder
- Returns:
-
static the current UriBuilder to allow method chaining
- setCreateAbsoluteUri ( bool $createAbsoluteUri) ¶
-
If set, the URI is prepended with the current base URI. Defaults to FALSE.
- param bool $createAbsoluteUri
-
the createAbsoluteUri
- returntype
-
TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder
- Returns:
-
static the current UriBuilder to allow method chaining
- setAbsoluteUriScheme ( string $absoluteUriScheme) ¶
-
Sets the scheme that should be used for absolute URIs in FE mode
- param string $absoluteUriScheme
-
the scheme to be used for absolute URIs
- returntype
-
TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder
- Returns:
-
static the current UriBuilder to allow method chaining
- setLanguage ( string $language) ¶
-
Enforces a URI / link to a page to a specific language (or use "current")
- param string $language
-
the language
- returntype
-
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 string|int|bool $addQueryString
-
is set to "1", "true", "0", "false" or "untrusted"
- returntype
-
TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder
- Returns:
-
static the current UriBuilder to allow method chaining
- setArgumentsToBeExcludedFromQueryString ( array $argumentsToBeExcludedFromQueryString) ¶
-
A list of arguments to be excluded from the query parameters Only active if addQueryString is set
- param array $argumentsToBeExcludedFromQueryString
-
the argumentsToBeExcludedFromQueryString
- returntype
-
TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder
- Returns:
-
static the current UriBuilder to allow method chaining
- setArgumentPrefix ( string $argumentPrefix) ¶
-
Specifies the prefix to be used for all arguments.
- param string $argumentPrefix
-
the argumentPrefix
- returntype
-
TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder
- Returns:
-
static the current UriBuilder to allow method chaining
- setLinkAccessRestrictedPages ( bool $linkAccessRestrictedPages) ¶
-
If set, URIs for pages without access permissions will be created
- param bool $linkAccessRestrictedPages
-
the linkAccessRestrictedPages
- returntype
-
TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder
- Returns:
-
static the current UriBuilder to allow method chaining
- setTargetPageUid ( int $targetPageUid) ¶
-
Uid of the target page
- param int $targetPageUid
-
the targetPageUid
- returntype
-
TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder
- Returns:
-
static the current UriBuilder to allow method chaining
- setTargetPageType ( int $targetPageType) ¶
-
Sets the page type of the target URI. Defaults to 0
- param int $targetPageType
-
the targetPageType
- returntype
-
TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder
- Returns:
-
static the current UriBuilder to allow method chaining
- setNoCache ( bool $noCache) ¶
-
by default FALSE; if TRUE, &no_cache=1 will be appended to the URI
- param bool $noCache
-
the noCache
- returntype
-
TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder
- Returns:
-
static the current UriBuilder to allow method chaining
- reset ( ) ¶
-
Resets all UriBuilder options to their default value
- returntype
-
TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder
- Returns:
-
static the current UriBuilder to allow method chaining
- 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 string $actionName
-
Name of the action to be called, default: NULL
- param array $controllerArguments
-
Additional query parameters. Will be "namespaced" and merged with $this->arguments., default: NULL
- param string $controllerName
-
Name of the target controller. If not set, current ControllerName is used., default: NULL
- param string $extensionName
-
Name of the target extension, without underscores. If not set, current ExtensionName is used., default: NULL
- param string $pluginName
-
Name of the target plugin. If not set, current PluginName is used., default: NULL
- returntype
-
string
- Returns:
-
string the rendered URI
- build ( ) ¶
-
Builds the URI Depending on the current context this calls buildBackendUri() or buildFrontendUri()
- returntype
-
string
- Returns:
-
string The URI