Breaking: #98370 - Extbase Request cleanup and hardening

See forge#98370

Description

Extbase \TYPO3\CMS\Extbase\Mvc\Request has been turned into a decorator of the PSR-7 ServerRequestInterface with Core v11: Extbase-based extensions work with the PSR-7 Core Request, Extbase specific Request state is attached as an attribute to the PSR-7 Request.

Most of these Extbase-specific attribute properties are now available in Core v12 by activating the according decorator methods in \TYPO3\CMS\Extbase\Mvc\RequestInterface, which is implemented by \TYPO3\CMS\Extbase\Mvc\Request. The RequestInterface now also properly extends PSR-7 ServerRequestInterface and is type-hinted within the Extbase framework.

PSR-7 interfaces rely on object immutability: A created Request object is never changed, instead a new object is created and returned when changed. The old fashioned Extbase Request violated this with various setXY() methods. These have been removed, and this is the part that is considered breaking for consuming extensions.

Impact

Extbase-based extensions using static code analyzers like phpstan in CI should benefit from improved scanner results and can further harden their codebase.

Affected installations

Extensions that actively manipulate the given Extbase Request using setter methods will trigger fatal PHP "method does not exist" errors.

Instances with extensions actively creating a Request must hand over a \Psr\Http\Message\ServerRequestInterface as constructor argument, it must have the attribute extbase set, which must be an instance of \TYPO3\CMS\Extbase\Mvc\ExtbaseRequestParameters.

Migration

It is relatively seldom that Extbase extensions need to actively manipulate the Extbase Request since most of that is handled by the Extbase Framework internally for consuming extensions.

Extensions that use the setXY() methods for whatever reasons have to change them to their withXY() counterparts, though: Nearly all "withers" are now declared as part of RequestInterface and already exist in v11, "setters" can be migrated quite easily.

From an Extbase Framework API point of view, extension should only rely on RequestInterface methods: The second level ExtbaseRequestParameters attribute is considered @internal and extensions shouldn't work with it directly. There are just a couple of methods used by Extbase Framework based on direct ExtbaseRequestParameters manipulation, most of them are related to the action argument validation and action forwarding behavior of Extbase, which Extbase extensions in general shouldn't need to deal with themselves.

When changing from "setters" to "withers", the important key change is that calling a withXY() method does not manipulate the existing request, but returns a new instance instead. In practice, if the previous Request object has been set to some other client object beforehand, and if a new Request is created using a withXY() method, those client objects may need to be updated with the new object. A typical use case is $this->view in a controller class, which may now need $this->view->setRequest($myNewRequest) to receive the new Request to work on, and it's most likely also a good idea to update $this->request = $myNewRequest as well.