diff --git a/src/Cookie.php b/src/Cookie.php index e446e58..f150d81 100644 --- a/src/Cookie.php +++ b/src/Cookie.php @@ -174,6 +174,8 @@ public function getExpires() : int } /** + * @deprecated use withExpires() + * * Sets the cookie expiry time. * * @param int $expires The unix timestamp at which the cookie expires, zero for a transient cookie. @@ -187,6 +189,14 @@ public function setExpires(int $expires) : Cookie return $this; } + public function withExpires(int $expires): Cookie + { + $that = clone $this; + $that->expires = $expires; + + return $that; + } + /** * @return string|null */ @@ -196,21 +206,27 @@ public function getPath() : ?string } /** + * @deprecated use withPath() + * * @param string|null $path * * @return static This cookie. */ public function setPath(?string $path) : Cookie { - if ($path !== null) { - $path = (string) $path; - } - $this->path = $path; return $this; } + public function withPath(?string $path): Cookie + { + $that = clone $this; + $that->path = $path; + + return $that; + } + /** * @return string|null */ @@ -220,21 +236,27 @@ public function getDomain() : ?string } /** + * @deprecated use withDomain() + * * @param string|null $domain * * @return static This cookie. */ public function setDomain(?string $domain) : Cookie { - if ($domain !== null) { - $domain = (string) $domain; - } - $this->domain = $domain; return $this; } + public function withDomain(?string $domain): Cookie + { + $that = clone $this; + $that->domain = $domain; + + return $that; + } + /** * @return bool */ @@ -252,6 +274,8 @@ public function isSecure() : bool } /** + * @deprecated use withSecure() + * * Sets whether this cookie should only be sent over a secure connection. * * @param bool $secure True to only send over a secure connection, false otherwise. @@ -265,6 +289,14 @@ public function setSecure(bool $secure) : Cookie return $this; } + public function withSecure(bool $secure): Cookie + { + $that = clone $this; + $that->secure = $secure; + + return $that; + } + /** * Returns whether to limit the scope of this cookie to HTTP requests. * @@ -276,6 +308,8 @@ public function isHttpOnly() : bool } /** + * @deprecated use withHttpOnly() + * * Sets whether to limit the scope of this cookie to HTTP requests. * * Set to true to instruct the user agent to omit the cookie when providing access to @@ -295,6 +329,14 @@ public function setHttpOnly(bool $httpOnly) : Cookie return $this; } + public function withHttpOnly(bool $httpOnly): Cookie + { + $that = clone $this; + $that->httpOnly = $httpOnly; + + return $that; + } + /** * Returns whether this cookie has expired. * diff --git a/src/Message.php b/src/Message.php index cc49703..388bde8 100644 --- a/src/Message.php +++ b/src/Message.php @@ -42,6 +42,8 @@ public function getProtocolVersion() : string } /** + * @deprecated use withProtocolVersion() + * * @param string $version * * @return static @@ -53,6 +55,17 @@ public function setProtocolVersion(string $version) : Message return $this; } + /** + * @return static + */ + public function withProtocolVersion(string $version): Message + { + $that = clone $this; + $that->protocolVersion = $version; + + return $that; + } + /** * Gets all message headers. * @@ -148,12 +161,14 @@ public function getHeaderAsArray(string $name) : array } /** + * @deprecated use withHeader() + * * Sets a header, replacing any existing values of any headers with the same case-insensitive name. * * The header value MUST be a string or an array of strings. * - * @param string $name - * @param string|array $value + * @param string $name + * @param string|string[] $value * * @return static */ @@ -166,12 +181,29 @@ public function setHeader(string $name, $value) : Message } /** + * @param string|string[] $value + * + * @return static + */ + public function withHeader(string $name, $value): Message + { + $that = clone $this; + + $name = strtolower($name); + $that->headers[$name] = is_array($value) ? array_values($value) : [$value]; + + return $that; + } + + /** + * @deprecated use withHeaders() + * * Sets headers, replacing any headers that have already been set on the message. * * The array keys MUST be a string. The array values must be either a * string or an array of strings. * - * @param array $headers + * @param array $headers * * @return static */ @@ -185,10 +217,28 @@ public function setHeaders(array $headers) : Message } /** + * @param array $headers + * + * @return static + */ + public function withHeaders(array $headers): Message + { + $that = $this; + + foreach ($headers as $name => $value) { + $that = $that->withHeader($name, $value); + } + + return $that; + } + + /** + * @deprecated use withAddedHeader() + * * Appends a header value to any existing values associated with the given header name. * - * @param string $name - * @param string|array $value + * @param string $name + * @param string|string[] $value * * @return static */ @@ -209,6 +259,21 @@ public function addHeader(string $name, $value) : Message } /** + * @param string|string[] $value + * + * @return static + */ + public function withAddedHeader(string $name, $value): Message + { + $that = clone $this; + $that->addHeader($name, $value); + + return $that; + } + + /** + * @deprecated use withAddedHeaders() + * * Merges in an associative array of headers. * * Each array key MUST be a string representing the case-insensitive name @@ -217,7 +282,7 @@ public function addHeader(string $name, $value) : Message * name, or, if a header does not already exist by the given name, then the * header is added. * - * @param array $headers + * @param array $headers * * @return static */ @@ -231,6 +296,24 @@ public function addHeaders(array $headers) : Message } /** + * @param array $headers + * + * @return static + */ + public function withAddedHeaders(array $headers): Message + { + $that = $this; + + foreach ($headers as $name => $value) { + $that = $that->withAddedHeader($name, $value); + } + + return $that; + } + + /** + * @deprecated use withoutHeader() + * * Removes a specific header by case-insensitive name. * * @param string $name @@ -245,6 +328,19 @@ public function removeHeader(string $name) : Message return $this; } + /** + * @return static + */ + public function withoutHeader(string $name) : Message + { + $that = clone $this; + + $name = strtolower($name); + unset($that->headers[$name]); + + return $that; + } + /** * @return string */ @@ -272,6 +368,8 @@ public function getBody() : ?MessageBody } /** + * @deprecated use withBody() + * * Sets the message body. * * @param MessageBody|null $body @@ -300,6 +398,18 @@ public function setBody(?MessageBody $body) : Message return $this; } + /** + * @return static + */ + public function withBody(?MessageBody $body): Message + { + $that = clone $this; + + $that->setBody($body); + + return $that; + } + /** * Returns the reported Content-Length of this Message. * diff --git a/src/Request.php b/src/Request.php index 78dfdcb..ac0c799 100644 --- a/src/Request.php +++ b/src/Request.php @@ -7,6 +7,8 @@ use Brick\Http\Exception\HttpBadRequestException; /** + * @todo make final + * * Represents an HTTP request received by the server. */ class Request extends Message @@ -313,6 +315,8 @@ public function getQuery(?string $name = null) } /** + * @deprecated use withQuery() + * * Sets the query parameters. * * @param array $query The associative array of parameters. @@ -336,6 +340,15 @@ public function setQuery(array $query) : Request return $this; } + public function withQuery(array $query): Request + { + $that = clone $this; + + $that->setQuery($query); + + return $that; + } + /** * Returns the post parameter(s). * @@ -353,6 +366,8 @@ public function getPost(?string $name = null) } /** + * @deprecated use withPost() + * * Sets the post parameter. * * This will set a request body with the URL-encoded data, @@ -380,6 +395,15 @@ public function setPost(array $post) : Request return $this; } + public function withPost(array $post): Request + { + $that = clone $this; + + $that->setPost($post); + + return $that; + } + /** * Returns the uploaded file by the given name. * @@ -433,6 +457,8 @@ public function getFiles(?string $name = null) : array } /** + * @deprecated use withFiles() + * * Sets the uploaded files. * * This will replace the message body, if any, with an empty body. @@ -459,6 +485,15 @@ public function setFiles(array $files) : Request return $this; } + public function withFiles(array $files): Request + { + $that = clone $this; + + $that->setFiles($files); + + return $that; + } + /** * @param array $files * @@ -496,6 +531,8 @@ public function getCookie(?string $name = null) } /** + * @deprecated use withAddedCookies() + * * Adds cookies to this request. * * Existing cookies with the same name will be replaced. @@ -509,7 +546,18 @@ public function addCookies(array $cookies) : Request return $this->setCookies($cookies + $this->cookies); } + public function withAddedCookies(array $cookies): Request + { + $that = clone $this; + + $that->addCookies($cookies); + + return $that; + } + /** + * @deprecated use withCookies() + * * Sets the cookies for this request. * * All existing cookies will be replaced. @@ -533,6 +581,15 @@ public function setCookies(array $cookies) : Request return $this; } + public function withCookies(array $cookies): Request + { + $that = clone $this; + + $that->setCookies($cookies); + + return $that; + } + /** * @param array $value * @param string $path @@ -574,6 +631,8 @@ public function getMethod() : string } /** + * @deprecated use withMethod() + * * Sets the request method. * * If the method case-insensitively matches a standard method, it will be converted to uppercase. @@ -589,6 +648,14 @@ public function setMethod(string $method) : Request return $this; } + public function withMethod(string $method): Request + { + $that = clone $this; + $that->method = $that->fixMethodCase($method); + + return $that; + } + /** * Returns whether this request method matches the given one. * @@ -644,6 +711,8 @@ public function getScheme() : string } /** + * @deprecated use withScheme() + * * Sets the request scheme. * * @param string $scheme The new request scheme. @@ -667,6 +736,15 @@ public function setScheme(string $scheme) : Request return $this; } + public function withScheme(string $scheme): Request + { + $that = clone $this; + + $that->setScheme($scheme); + + return $that; + } + /** * Returns the host name of this request. * @@ -715,6 +793,8 @@ public function isHost(string $host, bool $includeSubDomains = false) : bool } /** + * @deprecated use withHost() + * * Sets the host name of this request. * * This will update the Host header accordingly. @@ -730,6 +810,14 @@ public function setHost(string $host) : Request return $this->updateHostHeader(); } + public function withHost(string $host): Request + { + $that = clone $this; + $that->host = $host; + + return $that->updateHostHeader(); + } + /** * Returns the port number of this request. * @@ -741,6 +829,8 @@ public function getPort() : int } /** + * @deprecated use withPort() + * * Sets the port number of this request. * * This will update the Host header accordingly. @@ -756,6 +846,14 @@ public function setPort(int $port) : Request return $this->updateHostHeader(); } + public function withPort(int $port): Request + { + $that = clone $this; + $that->port = $port; + + return $that->updateHostHeader(); + } + /** * Updates the Host header from the values of host and port. * @@ -800,6 +898,8 @@ public function getPathParts() : array } /** + * @deprecated use withPath() + * * Sets the request path. * * Example: `/user/profile` @@ -821,6 +921,18 @@ public function setPath(string $path) : Request return $this->updateRequestUri(); } + public function withPath(string $path): Request + { + if (strpos($path, '?') !== false) { + throw new \InvalidArgumentException('The request path must not contain a query string.'); + } + + $that = clone $this; + $that->path = $path; + + return $that->updateRequestUri(); + } + /** * Returns the query string. * @@ -836,6 +948,8 @@ public function getQueryString() : string } /** + * @deprecated use withQueryString() + * * Sets the query string. * * @param string $queryString The new query string. @@ -844,12 +958,22 @@ public function getQueryString() : string */ public function setQueryString(string $queryString) : Request { - $this->queryString = (string) $queryString; + $this->queryString = $queryString; parse_str($this->queryString, $this->query); return $this->updateRequestUri(); } + public function withQueryString(string $queryString): Request + { + $that = clone $this; + + $that->queryString = $queryString; + parse_str($that->queryString, $that->query); + + return $that->updateRequestUri(); + } + /** * Updates the request URI from the values of path and query string. * @@ -877,6 +1001,8 @@ public function getRequestUri() : string } /** + * @deprecated use withRequestUri() + * * Sets the request URI. * * This will update the request path, query string, and query parameters. @@ -909,6 +1035,15 @@ public function setRequestUri(string $requestUri) : Request return $this; } + public function withRequestUri(string $requestUri): Request + { + $that = clone $this; + + $that->setRequestUri($requestUri); + + return $that; + } + /** * Returns the URL of this request. * @@ -933,6 +1068,8 @@ public function getUrlBase() : string } /** + * @deprecated use withUrl() + * * Sets the request URL. * * @param string $url The new URL. @@ -997,6 +1134,15 @@ public function setUrl(string $url) : Request return $this; } + public function withUrl(string $url): Request + { + $that = clone $this; + + $that->setUrl($url); + + return $that; + } + /** * Returns the Referer URL if it is present and valid, else null. * @@ -1028,6 +1174,8 @@ public function isSecure() : bool } /** + * @deprecated use withSecure() + * * Sets whether this request is sent over a secure connection. * * @param bool $isSecure True to mark the request as secure, false to mark it as not secure. @@ -1047,6 +1195,14 @@ public function setSecure(bool $isSecure) : Request return $this; } + public function withSecure(bool $isSecure): Request + { + $that = clone $this; + $that->setSecure($isSecure); + + return $that; + } + /** * Returns the client IP address. * @@ -1058,6 +1214,8 @@ public function getClientIp() : string } /** + * @deprecated use withClientIp() + * * Sets the client IP address. * * @param string $ip The new IP address. @@ -1071,6 +1229,14 @@ public function setClientIp(string $ip) : Request return $this; } + public function withClientIp(string $ip): Request + { + $that = clone $this; + $that->clientIp = $ip; + + return $that; + } + /** * Returns the content types accepted by the client. * diff --git a/src/Response.php b/src/Response.php index ecd4c40..8db6fa1 100644 --- a/src/Response.php +++ b/src/Response.php @@ -5,6 +5,8 @@ namespace Brick\Http; /** + * @todo make final + * * Represents an HTTP response to send back to the client. */ class Response extends Message @@ -151,6 +153,8 @@ public function getReasonPhrase() : string } /** + * @deprecated use withStatusCode() + * * Sets the status code of this response. * * @param int $statusCode The status code. @@ -180,6 +184,14 @@ public function setStatusCode(int $statusCode, ?string $reasonPhrase = null) : R return $this; } + public function withStatusCode(int $statusCode, ?string $reasonPhrase = null): Response + { + $that = clone $this; + $that->setStatusCode($statusCode); + + return $that; + } + /** * Returns the cookies currently set on this response. * @@ -191,6 +203,8 @@ public function getCookies() : array } /** + * @deprecated use withCookie() + * * Sets a cookie on this response. * * @param \Brick\Http\Cookie $cookie The cookie to set. @@ -205,7 +219,17 @@ public function setCookie(Cookie $cookie) : Response return $this; } + public function withCookie(Cookie $cookie): Response + { + $that = clone $this; + $that->setCookie($cookie); + + return $that; + } + /** + * @deprecated use withoutCookies() + * * Removes all cookies from this response. * * @return static This response. @@ -217,7 +241,17 @@ public function removeCookies() : Response return $this->removeHeader('Set-Cookie'); } + public function withoutCookies(): Response + { + $that = clone $this; + $that->cookies = []; + + return $that->withoutHeader('Set-Cookie'); + } + /** + * @deprecated use withContent() + * * @param string|resource $content * * @return static This response. @@ -233,6 +267,17 @@ public function setContent($content) : Response return $this->setBody($body); } + /** + * @param string|resource $content + */ + public function withContent($content): Response + { + $that = clone $this; + $that->setContent($content); + + return $that; + } + /** * Returns whether this response has an informational status code, 1xx. *