This is a SECURITY release. All users are encouraged to upgrade immediately.

Added

This release adds features to allow filtering a ServerRequest as generated by Laminas\Diactoros\ServerRequestFactory::fromGlobals() for the purposes of initialization. Examples include:

• Adding a request identifier.
• Using X-Forwarded-* headers to modify the URL to represent the original client request.

The features are based on a new interface, Laminas\Diactorors\ServerRequestFilter\FilterServerRequestInterface, which defines a single method:

public function __invoke(
    \Psr\Http\Message\ServerRequestInterface $request
): \Psr\Http\Message\ServerRequestInterface

We provide two implementations, as follows:

• Laminas\Diactoros\ServerRequestFilter\DoNotFilter will return the provided request verbatim.
• Laminas\Diactoros\ServerRequestFilter\FilterUsingXForwardedHeaders has named constructors that allow you to define how and when X-Forwarded-* headers are used to modify the URI instance associated with the request. These methods are:
  • trustAny(): this method generates a filter instance that will trust all X-Forwarded-* headers from any source.
  • trustReservedSubnets(array $trustedHeaders = ?): this method generates a filter instance that only modifies the URL if the IP address of the requesting server is from a reserved, private subnet (localhost; classes A, B, and C subnets; and IPv6 private and local-link subnets). By default, it will trust all X-Forwarded-* headers from these sources, but you may specify a list to allow via the $trustedHeaders argument.
  • trustProxies(array $proxyCIDRList, array $trustedHeaders = ?): this method will generate a filter instance that only modifies the URL if the requesting server matches an entry in the $proxyCIDRList. These entries may be IP addresses, or any IPv4 or IPv6 CIDR subnets. By default, it will trust all X-Forwarded-* headers from these sources, but you may specify a list to allow via the $trustedHeaders argument.

ServerRequestFactory::fromGlobals() now accepts a FilterServerRequestInterface instance as the optional argument $requestFilter. If none is provided, it uses one as produced by FilterUsingXForwardedHeaders::trustReservedSubnets().

Deprecated

• The function Laminas\Diactoros\marshalUriFromSapi() is deprecated, and no longer used internally.

Changed

Laminas\Diactoros\ServerRequestFactory::fromGlobals() no longer consumes marshalUriFromSapi(), and instead inlines an alternate implementation. The new implementation does not consider X-Forwarded-* headers by default when generating the associated URI instance. Internally, if no FilterServerRequestInterface implementation is provided, it defaults to using an instance returned by FilterUsingXForwardeHeaders::trustReservedSubnets(). If you previously relied on X-Forwarded-* headers, you MAY need to update your code to use either the FilterUsingXForwardedHeaders::trustAny() or FilterUsingXForwardedHeaders::trustProxies() methods to generate a filter to use with ServerRequestFactory::fromGlobals().

Fixed

• Fixes CVE-2022-31109