PSR-7 HTTP Message implementation
ServerRequestFactory::createServerRequest()
method
creates a php://temp
stream instead of a php::input
stream, in compliance
with the PSR-17 specification.#326 adds PSR-17 HTTP Message Factory implementations, including:
Zend\Diactoros\RequestFactory
Zend\Diactoros\ResponseFactory
Zend\Diactoros\ServerRequestFactory
Zend\Diactoros\StreamFactory
Zend\Diactoros\UploadedFileFactory
Zend\Diactoros\UriFactory
These factories may be used to produce the associated instances; we encourage users to rely on the PSR-17 factory interfaces to allow exchanging PSR-7 implementations within their applications.
#328 adds a package-level exception interface, Zend\Diactoros\Exception\ExceptionInterface
,
and several implementations for specific exceptions raised within the package.
These include:
Zend\Diactoros\Exception\DeserializationException
(extends UnexpectedValueException
)Zend\Diactoros\Exception\InvalidArgumentException
(extends InvalidArgumentException
)Zend\Diactoros\Exception\InvalidStreamPointerPositionException
(extends RuntimeException
)Zend\Diactoros\Exception\SerializationException
(extends UnexpectedValueException
)Zend\Diactoros\Exception\UnreadableStreamException
(extends RuntimeException
)Zend\Diactoros\Exception\UnrecognizedProtocolVersionException
(extends UnexpectedValueException
)Zend\Diactoros\Exception\UnrewindableStreamException
(extends RuntimeException
)Zend\Diactoros\Exception\UnseekableStreamException
(extends RuntimeException
)Zend\Diactoros\Exception\UntellableStreamException
(extends RuntimeException
)Zend\Diactoros\Exception\UnwritableStreamException
(extends RuntimeException
)Zend\Diactoros\Exception\UploadedFileAlreadyMovedException
(extends RuntimeException
)Zend\Diactoros\Exception\UploadedFileErrorException
(extends RuntimeException
)#329 adds return type hints and scalar parameter type hints wherever possible. The changes were done to help improve code quality, in part by reducing manual type checking. If you are extending any classes, you may need to update your signatures; check the signatures of the class(es) you are extending for changes.
#162 modifies Serializer\Request
such that it now no longer raises an UnexpectedValueException
via its toString()
method
when an unexpected HTTP method is encountered; this can be done safely, as the value can never
be invalid due to other changes in the same patch.
#162 modifies RequestTrait
such that it now invalidates non-string method arguments to either
the constructor or withMethod()
, raising an InvalidArgumentException
for any that do not validate.
#308 removes the following methods from the ServerRequestFactory
class:
normalizeServer()
(use Zend\Diactoros\normalizeServer()
instead)marshalHeaders()
(use Zend\Diactoros\marshalHeadersFromSapi()
instead)marshalUriFromServer()
(use Zend\Diactoros\marshalUriFromSapi()
instead)marshalRequestUri()
(use Uri::getPath()
from the Uri
instance returned by marshalUriFromSapi()
instead)marshalHostAndPortFromHeaders()
(use Uri::getHost()
and Uri::getPort()
from the Uri
instances returned by marshalUriFromSapi()
instead)stripQueryString()
(use explode("?", $path, 2)[0]
instead)normalizeFiles()
(use Zend\Diactoros\normalizeUploadedFiles()
instead)#295 removes Zend\Diactoros\Server
. You can use the RequestHandlerRunner
class from
zendframework/zend-httphandlerrunner to provide these capabilities instead.
#295 removes Zend\Diactoros\Response\EmitterInterface
and the various emitter implementations.
These can now be found in the package zendframework/zend-httphandlerrunner, which also provides
a PSR-7-implementation agnostic way of using them.
#325 changes the behavior of ServerRequest::withParsedBody()
. Per
PSR-7, it now no longer allows values other than null
, arrays, or objects.
#325 changes the behavior of each of Request
, ServerRequest
, and
Response
in relation to the validation of header values. Previously, we
allowed empty arrays to be provided via withHeader()
; however, this was
contrary to the PSR-7 specification. Empty arrays are no longer allowed.
ServerRequestFactory
, which made it
impossible to fetch a specific header by name.This release modifies how ServerRequestFactory
marshals the request URI. In
prior releases, we would attempt to inspect the X-Rewrite-Url
and
X-Original-Url
headers, using their values, if present. These headers are
issued by the ISAPI_Rewrite module for IIS (developed by HeliconTech).
However, we have no way of guaranteeing that the module is what issued the
headers, making it an unreliable source for discovering the URI. As such, we
have removed this feature in this release of Diactoros.
If you are developing a middleware application, you can mimic the functionality via middleware as follows:
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;
use Zend\Diactoros\Uri;
public function process(ServerRequestInterface $request, RequestHandlerInterface $handler) : ResponseInterface
{
$requestUri = null;
$httpXRewriteUrl = $request->getHeaderLine('X-Rewrite-Url');
if ($httpXRewriteUrl !== null) {
$requestUri = $httpXRewriteUrl;
}
$httpXOriginalUrl = $request->getHeaderLine('X-Original-Url');
if ($httpXOriginalUrl !== null) {
$requestUri = $httpXOriginalUrl;
}
if ($requestUri !== null) {
$request = $request->withUri(new Uri($requestUri));
}
return $handler->handle($request);
}
If you use middleware such as the above, make sure you also instruct your web server to strip any incoming headers of the same name so that you can guarantee they are issued by the ISAPI_Rewrite module.
#321 updates the logic in Uri::withPort()
to ensure that it checks that the
value provided is either an integer or a string integer, as only those values
may be cast to integer without data loss.
#320 adds checking within Response
to ensure that the provided reason
phrase is a string; an InvalidArgumentException
is now raised if it is not. This change
ensures the class adheres strictly to the PSR-7 specification.
#319 provides a fix to Zend\Diactoros\Response
that ensures that the status
code returned is always an integer (and never a string containing an
integer), thus ensuring it strictly adheres to the PSR-7 specification.
#318 fixes the logic for discovering whether an HTTPS scheme is in play to be case insensitive when comparing header and SAPI values, ensuring no false negative lookups occur.
#314 modifies error handling around opening a file resource within
Zend\Diactoros\Stream::setStream()
to no longer use the second argument to
set_error_handler()
, and instead check the error type in the handler itself;
this fixes an issue when the handler is nested inside another error handler,
which currently has buggy behavior within the PHP engine.
normalizeUploadedFiles()
utility function handles nested trees of
uploaded files, ensuring it detects them properly.Zend\Diactoros
namespace, each of
which may be used to derive artifacts from SAPI supergloabls for the purposes
of generating a ServerRequest
instance:
normalizeServer(array $server, callable $apacheRequestHeaderCallback = null) : array
(main purpose is to aggregate the Authorization
header in the SAPI params
when under Apache)marshalProtocolVersionFromSapi(array $server) : string
marshalMethodFromSapi(array $server) : string
marshalUriFromSapi(array $server, array $headers) : Uri
marshalHeadersFromSapi(array $server) : array
parseCookieHeader(string $header) : array
createUploadedFile(array $spec) : UploadedFile
(creates the instance from
a normal $_FILES
entry)normalizeUploadedFiles(array $files) : UploadedFileInterface[]
(traverses
a potentially nested array of uploaded file instances and/or $_FILES
entries, including those aggregated under mod_php, php-fpm, and php-cgi in
order to create a flat array of UploadedFileInterface
instances to use in a
request)#307 deprecates ServerRequestFactory::normalizeServer()
; the method is
no longer used internally, and users should instead use Zend\Diactoros\normalizeServer()
,
to which it proxies.
#307 deprecates ServerRequestFactory::marshalHeaders()
; the method is
no longer used internally, and users should instead use Zend\Diactoros\marshalHeadersFromSapi()
,
to which it proxies.
#307 deprecates ServerRequestFactory::marshalUriFromServer()
; the method
is no longer used internally. Users should use marshalUriFromSapi()
instead.
#307 deprecates ServerRequestFactory::marshalRequestUri()
. the method is no longer
used internally, and currently proxies to marshalUriFromSapi()
, pulling the
discovered path from the Uri
instance returned by that function. Users
should use marshalUriFromSapi()
instead.
#307 deprecates ServerRequestFactory::marshalHostAndPortFromHeaders()
; the method
is no longer used internally, and currently proxies to marshalUriFromSapi()
,
pulling the discovered host and port from the Uri
instance returned by that
function. Users should use marshalUriFromSapi()
instead.
#307 deprecates ServerRequestFactory::getHeader()
; the method is no longer
used internally. Users should copy and paste the functionality into their own
applications if needed, or rely on headers from a fully-populated Uri
instance instead.
#307 deprecates ServerRequestFactory::stripQueryString()
; the method is no longer
used internally, and users can mimic the functionality via the expression
$path = explode('?', $path, 2)[0];
.
#307 deprecates ServerRequestFactory::normalizeFiles()
; the functionality
is no longer used internally, and users can use normalizeUploadedFiles()
as
a replacement.
#303 deprecates Zend\Diactoros\Response\EmitterInterface
and its various implementations. These are now provided via the
zendframework/zend-httphandlerrunner package as 1:1 substitutions.
#303 deprecates the Zend\Diactoros\Server
class. Users are directed to the RequestHandlerRunner
class from the
zendframework/zend-httphandlerrunner package as an alternative.