Skip to content

Improve request-response page #8228

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
markstory merged 5 commits into from
Feb 21, 2026
Merged

Improve request-response page #8228

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a16d711
improve request-response page
josbeir Feb 13, 2026
bb7e66a
revert Accept header title
josbeir Feb 13, 2026
591aee3
remove unused anchor tags
josbeir Feb 13, 2026
a35eac9
clarify iffy doc header
josbeir Feb 16, 2026
1a71ae9
Update section header to include POST method
josbeir Feb 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
125 changes: 58 additions & 67 deletions docs/en/controllers/request-response.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
Comment thread
josbeir marked this conversation as resolved.
Outdated

`method` Cake\\Http\\ServerRequest::**getBody**(): StreamInterface

Expand Down Expand Up @@ -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
Expand All @@ -371,7 +375,7 @@ $base = $request->getAttribute('webroot');

<a id="check-the-request"></a>

### Checking Request Conditions
### Checking Request Conditions with `is()`

`method` Cake\\Http\\ServerRequest::**is**(array|string $type, mixed ...$args): bool

Expand Down Expand Up @@ -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

Expand All @@ -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]
...
}
```
Expand Down Expand Up @@ -647,9 +651,7 @@ Check whether a specific language is accepted:
$acceptsSpanish = $this->request->acceptLanguage('es-es');
```

<a id="request-cookies"></a>

### Reading Cookies
### Reading Request Cookies

Request cookies can be read through a number of methods:

Expand All @@ -660,17 +662,17 @@ $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
$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:
Expand All @@ -682,13 +684,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:
Expand Down Expand Up @@ -720,7 +722,7 @@ tasks such as:
- Sending any header.
- Sending the response body.

### Dealing with Content Types
### Setting Content Types
Copy link
Copy Markdown
Member

@dereuromark dereuromark Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If u are changing the header you might have to add manual a with id for anchor links from other places

Copy link
Copy Markdown
Contributor Author

@josbeir josbeir Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

link checker detects these, no errors reported 😎

Copy link
Copy Markdown
Member

@dereuromark dereuromark Feb 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It only checks within sources. Not core code or other external anchor links

Copy link
Copy Markdown
Contributor Author

@josbeir josbeir Feb 16, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmm.. i (or we) could include a --source-manifest property on the link checker that could be used to parse a file of scanned docblock links (other script) from the current source we include in the repo. That way we are sure no breaking cross referencing happens during CI.

Or another idea? Would be a good addition to keep the docs clean over time (cfr the gazillion PR's followed after the new docs introduction 😃 )

Copy link
Copy Markdown
Contributor

@LordSimal LordSimal Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well it can be a separate CI workflow which just runs like once every 1-2 weeks and reports in its own github action way broken links after the fact.

Doing it on a per PR basis can lead to false reports if e.g. headings/links get adjusted in other PR's (on other repos) which are not yet merged.


`method` Cake\\Http\\Response::**withType**(string $contentType): static

Expand Down Expand Up @@ -787,7 +789,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:
Expand Down Expand Up @@ -943,9 +945,7 @@ 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.

<a id="cake-response-caching"></a>

### 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
Expand Down Expand Up @@ -1118,8 +1118,6 @@ if ($this->response->isNotModified($this->request)) {
}
```

<a id="response-cookies"></a>

### Setting Cookies

Cookies can be added to response using either an array or a `Cake\Http\Cookie\Cookie`
Expand Down Expand Up @@ -1153,9 +1151,7 @@ will make the browser remove its local cookie:
$this->response = $this->response->withExpiredCookie(new Cookie('remember_me'));
```

<a id="cors-headers"></a>

### 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)
Expand Down Expand Up @@ -1184,19 +1180,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

Expand Down Expand Up @@ -1310,16 +1302,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
Expand All @@ -1328,16 +1320,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
Expand Down Expand Up @@ -1420,9 +1413,7 @@ $response = $this->response->withCookieCollection($cookies);
Cookies set to responses can be encrypted using the
[Encrypted Cookie Middleware](../controllers/middleware#encrypted-cookie-middleware).

<a id="request-cookies"></a>

### Reading Cookies
### Reading Cookies from a CookieCollection

Once you have a `CookieCollection` instance, you can access the cookies it
contains:
Expand Down Expand Up @@ -1450,7 +1441,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');
Expand Down