From a16d7115f7b75d6bdd8be43a4286a5295009313b Mon Sep 17 00:00:00 2001 From: Jasper Smet Date: Fri, 13 Feb 2026 20:43:39 +0100 Subject: [PATCH 1/5] improve request-response page --- docs/en/controllers/request-response.md | 119 ++++++++++++------------ 1 file changed, 60 insertions(+), 59 deletions(-) diff --git a/docs/en/controllers/request-response.md b/docs/en/controllers/request-response.md index 94bc8debce..381e034f71 100644 --- a/docs/en/controllers/request-response.md +++ b/docs/en/controllers/request-response.md @@ -67,9 +67,9 @@ well: $passedArgs = $this->request->getParam('pass'); ``` -Will all provide you access to the passed arguments. There -are several important/useful parameters that CakePHP uses internally, these -are also all found in the routing parameters: +This gives you access to passed arguments. There are several important +parameters that CakePHP uses internally, and these are also all found in the +routing parameters: - `plugin` The plugin handling the request. Will be null when there is no plugin. @@ -202,18 +202,18 @@ $error = $attachment->getError(); ``` Moving the uploaded file from its temporary location to the desired target -location, doesn't require manually accessing the temporary file, instead it can -be easily done by using the objects `moveTo()` method: +location doesn't require manually accessing the temporary file. Instead, use the +object's `moveTo()` method: ```php $attachment->moveTo($targetPath); ``` -In an HTTP environment, the `moveTo()` method will automatically validate -whether the file is an actual uploaded file, and throw an exception in case -necessary. In an CLI environment, where the concept of uploading files doesn't -exist, it will allow to move the file that you've referenced irrespective of its -origins, which makes testing file uploads possible. +In an HTTP environment, the `moveTo()` method automatically validates +whether the file is an actual uploaded file, and throws an exception when +necessary. In a CLI environment, where the concept of uploading files doesn't +exist, it allows moving the referenced file regardless of its origin, which +makes testing file uploads possible. `method` Cake\\Http\\ServerRequest::**getUploadedFile**(string $path): UploadedFileInterface|null @@ -276,7 +276,7 @@ $this->request = $this->request->withUploadedFiles($files); > request data (too), then you have to set them via `Cake\Http\ServerRequest::withData()` or > `Cake\Http\ServerRequest::withParsedBody()`. -### PUT, PATCH or DELETE Data +### Request Bodies in PUT, PATCH, and DELETE `method` Cake\\Http\\ServerRequest::**getBody**(): StreamInterface @@ -327,28 +327,32 @@ a setter for environment variables without having to modify globals $this->request->withEnv('REQUEST_METHOD', 'POST'); ``` -### XML or JSON Data +### Reading XML and JSON Payloads Applications employing [REST](../development/rest) often exchange data in non-URL-encoded post bodies. You can read input data in any format using `Cake\Http\ServerRequest::input()`. By providing a decoding function, you can receive the content in a deserialized format: -```php -// Get JSON encoded data submitted to a PUT/POST action -$jsonData = $this->request->input('json_decode'); -``` - Some deserializing methods require additional parameters when called, such as the 'as array' parameter on `json_decode`. If you want XML converted into a DOMDocument object, `Cake\Http\ServerRequest::input()` supports -passing in additional parameters as well: +passing additional parameters as well: -```php -// Get XML encoded data submitted to a PUT/POST action +::: code-group + +```php [JSON] +// Get JSON-encoded data submitted to a PUT/POST action +$jsonData = $this->request->input('json_decode'); +``` + +```php [XML] +// Get XML-encoded data submitted to a PUT/POST action $data = $this->request->input('Cake\Utility\Xml::build', ['return' => 'domdocument']); ``` +::: + ### Path Information The request object also provides useful information about the paths in your @@ -371,7 +375,7 @@ $base = $request->getAttribute('webroot'); -### Checking Request Conditions +### Checking Request Conditions with `is()` `method` Cake\\Http\\ServerRequest::**is**(array|string $type, mixed ...$args): bool @@ -535,7 +539,7 @@ Returns the HTTP method the request was made with: echo $request->getMethod(); ``` -### Restricting Which HTTP method an Action Accepts +### Restricting HTTP Methods per Action `method` Cake\\Http\\ServerRequest::**allowMethod**(array|string $methods): bool @@ -547,7 +551,7 @@ Set allowed HTTP methods. If not matched, will throw public function delete() { // Only accept POST and DELETE requests - $this->request->allowMethod(['post', 'delete']); + $this->request->allowMethod(['post', 'delete']); // [!code focus] ... } ``` @@ -611,7 +615,7 @@ After proxies are trusted `clientIp()` will use the first IP address in the `X-Forwarded-For` header providing it is the only value that isn't from a trusted proxy. -### Checking Accept Headers +### Checking Content Negotiation Headers `method` Cake\\Http\\ServerRequest::**accepts**(?string $type = null): array|bool @@ -649,7 +653,7 @@ $acceptsSpanish = $this->request->acceptLanguage('es-es'); -### Reading Cookies +### Reading Request Cookies Request cookies can be read through a number of methods: @@ -660,7 +664,7 @@ $rememberMe = $this->request->getCookie('remember_me'); // Read the value, or get the default of 0 $rememberMe = $this->request->getCookie('remember_me', 0); -// Get all cookies as an hash +// Get all cookies as a hash $cookies = $this->request->getCookieParams(); // Get a CookieCollection instance @@ -668,9 +672,9 @@ $cookies = $this->request->getCookieCollection() ``` See the `Cake\Http\Cookie\CookieCollection` documentation for how -to work with cookie collection. +to work with a cookie collection. -### Uploaded Files +### Uploaded Files Quick Reference Requests expose the uploaded file data in `getData()` or `getUploadedFiles()` as `UploadedFileInterface` objects: @@ -682,13 +686,13 @@ $files = $request->getUploadedFiles(); // Read the file data. $files[0]->getStream(); $files[0]->getSize(); -$files[0]->getClientFileName(); +$files[0]->getClientFilename(); // Move the file. $files[0]->moveTo($targetPath); ``` -### Manipulating URIs +### Working with the Request URI Requests contain a URI object, which contains methods for interacting with the requested URI: @@ -720,7 +724,7 @@ tasks such as: - Sending any header. - Sending the response body. -### Dealing with Content Types +### Setting Content Types `method` Cake\\Http\\Response::**withType**(string $contentType): static @@ -787,7 +791,7 @@ download A boolean value indicating whether headers should be set to force download. -### Sending a String as File +### Sending a String as a File You can respond with a file that does not exist on the disk, such as a pdf or an ics generated on the fly from a string: @@ -945,7 +949,7 @@ second parameter. Cache-Control's `public` directive is set as well. -### Fine Tuning HTTP Cache +### Fine-Tuning HTTP Cache One of the best and easiest ways of speeding up your application is to use HTTP cache. Under this caching model, you are only required to help clients decide if @@ -1155,7 +1159,7 @@ $this->response = $this->response->withExpiredCookie(new Cookie('remember_me')); -### Setting Cross Origin Request Headers (CORS) +### Setting Cross-Origin Request Headers (CORS) The `cors()` method returns a `CorsBuilder` instance which provides a fluent interface for defining [HTTP Access Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS) @@ -1184,19 +1188,15 @@ criteria are met: The `CorsBuilder` provides the following methods for configuring CORS: -`method` Cake\\Http\\CorsBuilder::**allowOrigin**(array|string $domains): static - -`method` Cake\\Http\\CorsBuilder::**allowMethods**(array $methods): static - -`method` Cake\\Http\\CorsBuilder::**allowHeaders**(array $headers): static - -`method` Cake\\Http\\CorsBuilder::**allowCredentials**(): static - -`method` Cake\\Http\\CorsBuilder::**exposeHeaders**(array $headers): static - -`method` Cake\\Http\\CorsBuilder::**maxAge**(string|int $age): static - -`method` Cake\\Http\\CorsBuilder::**build**(): ResponseInterface +| Method | Signature | +| --- | --- | +| `allowOrigin` | `Cake\\Http\\CorsBuilder::allowOrigin(array\|string $domains): static` | +| `allowMethods` | `Cake\\Http\\CorsBuilder::allowMethods(array $methods): static` | +| `allowHeaders` | `Cake\\Http\\CorsBuilder::allowHeaders(array $headers): static` | +| `allowCredentials` | `Cake\\Http\\CorsBuilder::allowCredentials(): static` | +| `exposeHeaders` | `Cake\\Http\\CorsBuilder::exposeHeaders(array $headers): static` | +| `maxAge` | `Cake\\Http\\CorsBuilder::maxAge(string\|int $age): static` | +| `build` | `Cake\\Http\\CorsBuilder::build(): ResponseInterface` | #### Practical CORS Examples @@ -1310,16 +1310,16 @@ public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue } ``` -### Running logic after the Response has been sent +### Running Logic After the Response Is Sent -In fastcgi based environments you can listen to the `Server.terminate` event +In FastCGI-based environments you can listen to the `Server.terminate` event to run logic **after** the response has been sent to the client. The `terminate` event will be passed a `request` and `response`. The -`request` is fetched from the applications' DI container, or from +`request` is fetched from the application's DI container, or from `Router::getRequest()` if the DI container does not have a request registered. > [!WARNING] -> In non fastcgi environments the `Server.terminate` event is fired before +> In non-FastCGI environments the `Server.terminate` event is fired before > the response is sent. ::: info Added in version 5.1.0 @@ -1328,16 +1328,17 @@ to run logic **after** the response has been sent to the client. The ## Common Mistakes with Immutable Responses Response objects offer a number of methods that treat -responses as immutable objects. Immutable objects help prevent difficult to -track accidental side-effects, and reduce mistakes caused by method calls caused -by refactoring that change ordering. While they offer a number of benefits, -immutable objects can take some getting used to. Any method that starts with +responses as immutable objects. Immutable objects help prevent difficult-to- +track accidental side effects, and reduce mistakes introduced during +refactoring. While they offer a number of benefits, immutable objects can take +some getting used to. Any method that starts with `with` operates on the response in an immutable fashion, and will **always** return a **new** instance. Forgetting to retain the modified instance is the most frequent mistake people make when working with immutable objects: ```php -$this->response->withHeader('X-CakePHP', 'yes!'); +$this->response->withHeader('X-CakePHP', 'yes!'); // [!code --] +$this->response = $this->response->withHeader('X-CakePHP', 'yes!'); // [!code ++] ``` In the above code, the response will be lacking the `X-CakePHP` header, as the @@ -1420,9 +1421,9 @@ $response = $this->response->withCookieCollection($cookies); Cookies set to responses can be encrypted using the [Encrypted Cookie Middleware](../controllers/middleware#encrypted-cookie-middleware). - + -### Reading Cookies +### Reading Cookies from a CookieCollection Once you have a `CookieCollection` instance, you can access the cookies it contains: @@ -1450,7 +1451,7 @@ collection if you modify a cookie: ```php // Get the value -$value = $cookie->getValue() +$value = $cookie->getValue(); // Access data inside a JSON value $id = $cookie->read('User.id'); From bb7e66a1e13b5e15f892067bc487c71a6adc4a5a Mon Sep 17 00:00:00 2001 From: Jasper Smet Date: Fri, 13 Feb 2026 23:04:57 +0100 Subject: [PATCH 2/5] revert Accept header title --- docs/en/controllers/request-response.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/controllers/request-response.md b/docs/en/controllers/request-response.md index 381e034f71..196b9f825c 100644 --- a/docs/en/controllers/request-response.md +++ b/docs/en/controllers/request-response.md @@ -615,7 +615,7 @@ After proxies are trusted `clientIp()` will use the first IP address in the `X-Forwarded-For` header providing it is the only value that isn't from a trusted proxy. -### Checking Content Negotiation Headers +### Checking Accept Headers `method` Cake\\Http\\ServerRequest::**accepts**(?string $type = null): array|bool From 591aee37142dda652e0e8ac9f19e186e9939afc0 Mon Sep 17 00:00:00 2001 From: Jasper Smet Date: Fri, 13 Feb 2026 23:07:28 +0100 Subject: [PATCH 3/5] remove unused anchor tags --- docs/en/controllers/request-response.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/docs/en/controllers/request-response.md b/docs/en/controllers/request-response.md index 196b9f825c..282bf6fd52 100644 --- a/docs/en/controllers/request-response.md +++ b/docs/en/controllers/request-response.md @@ -651,8 +651,6 @@ Check whether a specific language is accepted: $acceptsSpanish = $this->request->acceptLanguage('es-es'); ``` - - ### Reading Request Cookies Request cookies can be read through a number of methods: @@ -947,8 +945,6 @@ The `withCache()` method sets the `Last-Modified` value to the first argument. `Expires` header and the `max-age` directive are set based on the second parameter. Cache-Control's `public` directive is set as well. - - ### Fine-Tuning HTTP Cache One of the best and easiest ways of speeding up your application is to use HTTP @@ -1122,8 +1118,6 @@ if ($this->response->isNotModified($this->request)) { } ``` - - ### Setting Cookies Cookies can be added to response using either an array or a `Cake\Http\Cookie\Cookie` @@ -1157,8 +1151,6 @@ will make the browser remove its local cookie: $this->response = $this->response->withExpiredCookie(new Cookie('remember_me')); ``` - - ### Setting Cross-Origin Request Headers (CORS) The `cors()` method returns a `CorsBuilder` instance which provides a fluent @@ -1421,8 +1413,6 @@ $response = $this->response->withCookieCollection($cookies); Cookies set to responses can be encrypted using the [Encrypted Cookie Middleware](../controllers/middleware#encrypted-cookie-middleware). - - ### Reading Cookies from a CookieCollection Once you have a `CookieCollection` instance, you can access the cookies it From a35eac977c34d4cf90f14ea722c7c8726637aeed Mon Sep 17 00:00:00 2001 From: Jasper Smet Date: Mon, 16 Feb 2026 17:52:21 +0100 Subject: [PATCH 4/5] clarify iffy doc header --- docs/en/controllers/request-response.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/controllers/request-response.md b/docs/en/controllers/request-response.md index 282bf6fd52..a621da2dfe 100644 --- a/docs/en/controllers/request-response.md +++ b/docs/en/controllers/request-response.md @@ -276,7 +276,7 @@ $this->request = $this->request->withUploadedFiles($files); > request data (too), then you have to set them via `Cake\Http\ServerRequest::withData()` or > `Cake\Http\ServerRequest::withParsedBody()`. -### Request Bodies in PUT, PATCH, and DELETE +### PUT, PATCH, and DELETE `method` Cake\\Http\\ServerRequest::**getBody**(): StreamInterface From 1a71ae957eaa9c221f1a0a513c69c301809e6ff8 Mon Sep 17 00:00:00 2001 From: Jasper Smet Date: Mon, 16 Feb 2026 18:06:47 +0100 Subject: [PATCH 5/5] Update section header to include POST method --- docs/en/controllers/request-response.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/controllers/request-response.md b/docs/en/controllers/request-response.md index a621da2dfe..11283a6d8b 100644 --- a/docs/en/controllers/request-response.md +++ b/docs/en/controllers/request-response.md @@ -276,7 +276,7 @@ $this->request = $this->request->withUploadedFiles($files); > request data (too), then you have to set them via `Cake\Http\ServerRequest::withData()` or > `Cake\Http\ServerRequest::withParsedBody()`. -### PUT, PATCH, and DELETE +### POST, PUT, PATCH, and DELETE `method` Cake\\Http\\ServerRequest::**getBody**(): StreamInterface