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.
API¶
- class TYPO3\CMS\Extbase\Mvc\Web\Routing\UriBuilder¶
An URI Builder
- setRequest(TYPO3\\CMS\\Extbase\\Mvc\\RequestInterface $request)¶
Sets the current request
- Parameters
$request (
TYPO3\CMS\Extbase\Mvc\RequestInterface) -- the request
- Return type
- Returns
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"
- Parameters
$arguments (
array) -- the arguments
- Return type
- Returns
the current UriBuilder to allow method chaining
- setSection(string $section)¶
If specified, adds a given HTML anchor to the URI (#...)
- Parameters
$section (
string) -- the section
- Return type
- Returns
the current UriBuilder to allow method chaining
- setFormat(string $format)¶
Specifies the format of the target (e.g. "html" or "xml")
- Parameters
$format (
string) -- the format
- Return type
- Returns
the current UriBuilder to allow method chaining
- setCreateAbsoluteUri(bool $createAbsoluteUri)¶
If set, the URI is prepended with the current base URI. Defaults to FALSE.
- Parameters
$createAbsoluteUri (
bool) -- the createAbsoluteUri
- Return type
- Returns
the current UriBuilder to allow method chaining
- setAbsoluteUriScheme(string $absoluteUriScheme)¶
Sets the scheme that should be used for absolute URIs in FE mode
- Parameters
$absoluteUriScheme (
string) -- the scheme to be used for absolute URIs
- Return type
- Returns
the current UriBuilder to allow method chaining
- setLanguage(string $language)¶
Enforces a URI / link to a page to a specific language (or use "current")
- Parameters
$language (
string) -- the language
- Return type
- getLanguage()¶
- Return type
string
- 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.
- Parameters
$addQueryString (
string|int|bool) -- is set to "1", "true", "0", "false" or "untrusted"
- Return type
- Returns
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
- Parameters
$argumentsToBeExcludedFromQueryString (
array) -- the argumentsToBeExcludedFromQueryString
- Return type
- Returns
the current UriBuilder to allow method chaining
- setArgumentPrefix(string $argumentPrefix)¶
Specifies the prefix to be used for all arguments.
- Parameters
$argumentPrefix (
string) -- the argumentPrefix
- Return type
- Returns
the current UriBuilder to allow method chaining
- setLinkAccessRestrictedPages(bool $linkAccessRestrictedPages)¶
If set, URIs for pages without access permissions will be created
- Parameters
$linkAccessRestrictedPages (
bool) -- the linkAccessRestrictedPages
- Return type
- Returns
the current UriBuilder to allow method chaining
- setTargetPageUid(int $targetPageUid)¶
Uid of the target page
- Parameters
$targetPageUid (
int) -- the targetPageUid
- Return type
- Returns
the current UriBuilder to allow method chaining
- setTargetPageType(int $targetPageType)¶
Sets the page type of the target URI. Defaults to 0
- Parameters
$targetPageType (
int) -- the targetPageType
- Return type
- Returns
the current UriBuilder to allow method chaining
- setNoCache(bool $noCache)¶
by default FALSE; if TRUE, &no_cache=1 will be appended to the URI
- Parameters
$noCache (
bool) -- the noCache
- Return type
- Returns
the current UriBuilder to allow method chaining
- reset()¶
Resets all UriBuilder options to their default value
- Return type
- Returns
the current UriBuilder to allow method chaining
- uriFor(string $actionName = NULL, array $controllerArguments = NULL, string $controllerName = NULL, string $extensionName = NULL, string $pluginName = NULL)¶
Creates an URI used for linking to an Extbase action.
Works in Frontend and Backend mode of TYPO3.
- Parameters
$actionName (
string) -- Name of the action to be called, default: NULL$controllerArguments (
array) -- Additional query parameters. Will be "namespaced" and merged with $this->arguments., default: NULL$controllerName (
string) -- Name of the target controller. If not set, current ControllerName is used., default: NULL$extensionName (
string) -- Name of the target extension, without underscores. If not set, current ExtensionName is used., default: NULL$pluginName (
string) -- Name of the target plugin. If not set, current PluginName is used., default: NULL
- Return type
string- Returns
the rendered URI
- build()¶
Builds the URI Depending on the current context this calls buildBackendUri() or buildFrontendUri()
- Return type
string- Returns
The URI