[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * @see       https://github.com/laminas/laminas-diactoros for the canonical source repository
   5   * @copyright https://github.com/laminas/laminas-diactoros/blob/master/COPYRIGHT.md
   6   * @license   https://github.com/laminas/laminas-diactoros/blob/master/LICENSE.md New BSD License
   7   */
   8  
   9  declare(strict_types=1);
  10  
  11  namespace Laminas\Diactoros;
  12  
  13  use Psr\Http\Message\RequestInterface;
  14  use Psr\Http\Message\StreamInterface;
  15  use Psr\Http\Message\UriInterface;
  16  
  17  use function array_keys;
  18  use function get_class;
  19  use function gettype;
  20  use function is_object;
  21  use function is_string;
  22  use function preg_match;
  23  use function sprintf;
  24  use function strtolower;
  25  
  26  /**
  27   * Trait with common request behaviors.
  28   *
  29   * Server and client-side requests differ slightly in how the Host header is
  30   * handled; on client-side, it should be calculated on-the-fly from the
  31   * composed URI (if present), while on server-side, it will be calculated from
  32   * the environment. As such, this trait exists to provide the common code
  33   * between both client-side and server-side requests, and each can then
  34   * use the headers functionality required by their implementations.
  35   */
  36  trait RequestTrait
  37  {
  38      use MessageTrait;
  39  
  40      /**
  41       * @var string
  42       */
  43      private $method = 'GET';
  44  
  45      /**
  46       * The request-target, if it has been provided or calculated.
  47       *
  48       * @var null|string
  49       */
  50      private $requestTarget;
  51  
  52      /**
  53       * @var UriInterface
  54       */
  55      private $uri;
  56  
  57      /**
  58       * Initialize request state.
  59       *
  60       * Used by constructors.
  61       *
  62       * @param null|string|UriInterface $uri URI for the request, if any.
  63       * @param null|string $method HTTP method for the request, if any.
  64       * @param string|resource|StreamInterface $body Message body, if any.
  65       * @param array $headers Headers for the message, if any.
  66       * @throws Exception\InvalidArgumentException for any invalid value.
  67       */
  68      private function initialize(
  69          $uri = null,
  70          string $method = null,
  71          $body = 'php://memory',
  72          array $headers = []
  73      ) : void {
  74          if ($method !== null) {
  75              $this->setMethod($method);
  76          }
  77  
  78          $this->uri    = $this->createUri($uri);
  79          $this->stream = $this->getStream($body, 'wb+');
  80  
  81          $this->setHeaders($headers);
  82  
  83          // per PSR-7: attempt to set the Host header from a provided URI if no
  84          // Host header is provided
  85          if (! $this->hasHeader('Host') && $this->uri->getHost()) {
  86              $this->headerNames['host'] = 'Host';
  87              $this->headers['Host'] = [$this->getHostFromUri()];
  88          }
  89      }
  90  
  91      /**
  92       * Create and return a URI instance.
  93       *
  94       * If `$uri` is a already a `UriInterface` instance, returns it.
  95       *
  96       * If `$uri` is a string, passes it to the `Uri` constructor to return an
  97       * instance.
  98       *
  99       * If `$uri is null, creates and returns an empty `Uri` instance.
 100       *
 101       * Otherwise, it raises an exception.
 102       *
 103       * @param null|string|UriInterface $uri
 104       * @throws Exception\InvalidArgumentException
 105       */
 106      private function createUri($uri) : UriInterface
 107      {
 108          if ($uri instanceof UriInterface) {
 109              return $uri;
 110          }
 111          if (is_string($uri)) {
 112              return new Uri($uri);
 113          }
 114          if ($uri === null) {
 115              return new Uri();
 116          }
 117          throw new Exception\InvalidArgumentException(
 118              'Invalid URI provided; must be null, a string, or a Psr\Http\Message\UriInterface instance'
 119          );
 120      }
 121  
 122      /**
 123       * Retrieves the message's request target.
 124       *
 125       * Retrieves the message's request-target either as it will appear (for
 126       * clients), as it appeared at request (for servers), or as it was
 127       * specified for the instance (see withRequestTarget()).
 128       *
 129       * In most cases, this will be the origin-form of the composed URI,
 130       * unless a value was provided to the concrete implementation (see
 131       * withRequestTarget() below).
 132       *
 133       * If no URI is available, and no request-target has been specifically
 134       * provided, this method MUST return the string "/".
 135       */
 136      public function getRequestTarget() : string
 137      {
 138          if (null !== $this->requestTarget) {
 139              return $this->requestTarget;
 140          }
 141  
 142          $target = $this->uri->getPath();
 143          if ($this->uri->getQuery()) {
 144              $target .= '?' . $this->uri->getQuery();
 145          }
 146  
 147          if (empty($target)) {
 148              $target = '/';
 149          }
 150  
 151          return $target;
 152      }
 153  
 154      /**
 155       * Create a new instance with a specific request-target.
 156       *
 157       * If the request needs a non-origin-form request-target — e.g., for
 158       * specifying an absolute-form, authority-form, or asterisk-form —
 159       * this method may be used to create an instance with the specified
 160       * request-target, verbatim.
 161       *
 162       * This method MUST be implemented in such a way as to retain the
 163       * immutability of the message, and MUST return a new instance that has the
 164       * changed request target.
 165       *
 166       * @link http://tools.ietf.org/html/rfc7230#section-2.7 (for the various
 167       *     request-target forms allowed in request messages)
 168       * @param string $requestTarget
 169       * @throws Exception\InvalidArgumentException if the request target is invalid.
 170       */
 171      public function withRequestTarget($requestTarget) : RequestInterface
 172      {
 173          if (preg_match('#\s#', $requestTarget)) {
 174              throw new Exception\InvalidArgumentException(
 175                  'Invalid request target provided; cannot contain whitespace'
 176              );
 177          }
 178  
 179          $new = clone $this;
 180          $new->requestTarget = $requestTarget;
 181          return $new;
 182      }
 183  
 184      /**
 185       * Retrieves the HTTP method of the request.
 186       *
 187       * @return string Returns the request method.
 188       */
 189      public function getMethod() : string
 190      {
 191          return $this->method;
 192      }
 193  
 194      /**
 195       * Return an instance with the provided HTTP method.
 196       *
 197       * While HTTP method names are typically all uppercase characters, HTTP
 198       * method names are case-sensitive and thus implementations SHOULD NOT
 199       * modify the given string.
 200       *
 201       * This method MUST be implemented in such a way as to retain the
 202       * immutability of the message, and MUST return an instance that has the
 203       * changed request method.
 204       *
 205       * @param string $method Case-insensitive method.
 206       * @throws Exception\InvalidArgumentException for invalid HTTP methods.
 207       */
 208      public function withMethod($method) : RequestInterface
 209      {
 210          $new = clone $this;
 211          $new->setMethod($method);
 212          return $new;
 213      }
 214  
 215      /**
 216       * Retrieves the URI instance.
 217       *
 218       * This method MUST return a UriInterface instance.
 219       *
 220       * @link http://tools.ietf.org/html/rfc3986#section-4.3
 221       * @return UriInterface Returns a UriInterface instance
 222       *     representing the URI of the request, if any.
 223       */
 224      public function getUri() : UriInterface
 225      {
 226          return $this->uri;
 227      }
 228  
 229      /**
 230       * Returns an instance with the provided URI.
 231       *
 232       * This method will update the Host header of the returned request by
 233       * default if the URI contains a host component. If the URI does not
 234       * contain a host component, any pre-existing Host header will be carried
 235       * over to the returned request.
 236       *
 237       * You can opt-in to preserving the original state of the Host header by
 238       * setting `$preserveHost` to `true`. When `$preserveHost` is set to
 239       * `true`, the returned request will not update the Host header of the
 240       * returned message -- even if the message contains no Host header. This
 241       * means that a call to `getHeader('Host')` on the original request MUST
 242       * equal the return value of a call to `getHeader('Host')` on the returned
 243       * request.
 244       *
 245       * This method MUST be implemented in such a way as to retain the
 246       * immutability of the message, and MUST return an instance that has the
 247       * new UriInterface instance.
 248       *
 249       * @link http://tools.ietf.org/html/rfc3986#section-4.3
 250       * @param UriInterface $uri New request URI to use.
 251       * @param bool $preserveHost Preserve the original state of the Host header.
 252       */
 253      public function withUri(UriInterface $uri, $preserveHost = false) : RequestInterface
 254      {
 255          $new = clone $this;
 256          $new->uri = $uri;
 257  
 258          if ($preserveHost && $this->hasHeader('Host')) {
 259              return $new;
 260          }
 261  
 262          if (! $uri->getHost()) {
 263              return $new;
 264          }
 265  
 266          $host = $uri->getHost();
 267          if ($uri->getPort()) {
 268              $host .= ':' . $uri->getPort();
 269          }
 270  
 271          $new->headerNames['host'] = 'Host';
 272  
 273          // Remove an existing host header if present, regardless of current
 274          // de-normalization of the header name.
 275          // @see https://github.com/zendframework/zend-diactoros/issues/91
 276          foreach (array_keys($new->headers) as $header) {
 277              if (strtolower($header) === 'host') {
 278                  unset($new->headers[$header]);
 279              }
 280          }
 281  
 282          $new->headers['Host'] = [$host];
 283  
 284          return $new;
 285      }
 286  
 287      /**
 288       * Set and validate the HTTP method
 289       *
 290       * @param string $method
 291       * @throws Exception\InvalidArgumentException on invalid HTTP method.
 292       */
 293      private function setMethod($method) : void
 294      {
 295          if (! is_string($method)) {
 296              throw new Exception\InvalidArgumentException(sprintf(
 297                  'Unsupported HTTP method; must be a string, received %s',
 298                  is_object($method) ? get_class($method) : gettype($method)
 299              ));
 300          }
 301  
 302          if (! preg_match('/^[!#$%&\'*+.^_`\|~0-9a-z-]+$/i', $method)) {
 303              throw new Exception\InvalidArgumentException(sprintf(
 304                  'Unsupported HTTP method "%s" provided',
 305                  $method
 306              ));
 307          }
 308          $this->method = $method;
 309      }
 310  
 311      /**
 312       * Retrieve the host from the URI instance
 313       */
 314      private function getHostFromUri() : string
 315      {
 316          $host  = $this->uri->getHost();
 317          $host .= $this->uri->getPort() ? ':' . $this->uri->getPort() : '';
 318          return $host;
 319      }
 320  }