Documentation menu
On this page
Components · v2.x
Http
The Http component models the HTTP request and response: parameter bags, uploaded files, HTML, JSON, redirect, streamed and file responses, and HTTP exceptions. It has no dependency and is used by the kernel, the routing and the controllers.
Module
| Manager | NeoPHP\Component\Http\HttpManager (final) |
| Interface | NeoPHP\Component\Http\HttpManagerInterface |
| Attribute | #[Component(provider: HttpProvider::class)] |
| Requires | nothing |
| Required by | Api, Kernel, Routing |
Inject HttpManagerInterface in a service, a command or a controller:
use NeoPHP\Component\Http\HttpManagerInterface;
public function __construct(private HttpManagerInterface $http)
{
}
The kernel requires this module: it is always loaded and cannot be disabled in config/config.php.
The public API of the module is its manager and its interface, Contract\, the attributes, the exceptions, the events and the classes documented below. The classes marked @internal are used by the framework only.
Request
NeoPHP\Component\Http\Request\Request is injected in a controller action by its type.
public function search(Request $request): Response
{
$query = $request->query->getString('q');
$page = $request->query->getInt('page', 1);
return $this->render('search.html.twig', ['query' => $query, 'page' => $page]);
}
| Property | Content |
|---|---|
query |
GET parameters (ParameterBag) |
request |
POST parameters, and the JSON body for POST, PUT, PATCH, DELETE (ParameterBag); filled from the body by fromGlobals(), not by create() |
attributes |
route parameters, _route, _controller (ParameterBag) |
cookies |
cookies (ParameterBag) |
files |
uploaded files (FileBag) |
server |
$_SERVER (ParameterBag) |
headers |
headers (HeaderBag) |
| Method | Returns |
|---|---|
Request::fromGlobals() |
a request built from the PHP globals |
Request::create($uri, $method, $parameters, $server, $content) |
a request built by hand (tests, sub-requests) |
new Request($query, $request, $attributes, $cookies, $files, $server, $content) |
a request |
getMethod() |
HTTP method; a POST can send _method or X-HTTP-Method-Override with PUT, PATCH or DELETE; http_method_override_header: false ignores the header |
getRealMethod(), setMethod($method), isMethod($method) |
real method, override, comparison |
getPath(), getQueryString(), getUri() |
URL parts; getPath() is relative to the application (without the sub-directory) |
getBasePath(), getRequestPath() |
sub-directory of the application (/app, '' at the root of the domain) and full path of the URL |
getScheme(), isSecure(), getHost(), getPort(), getSchemeAndHttpHost() |
server information (X-Forwarded-Proto, -Host, -Port when the request comes from a trusted proxy) |
getClientIp() |
client IP: REMOTE_ADDR, or the client of X-Forwarded-For behind a trusted proxy; null when unknown |
isFromTrustedProxy() |
the request was sent by a trusted proxy |
getContent(), toArray() |
raw body, decoded JSON body |
get($key, $default) |
value from attributes, then query, then request |
getContentType(), isJson(), wantsJson(), isXmlHttpRequest() |
content negotiation |
Request::METHODS lists the accepted methods.
Security headers
config/framework/app.yaml adds security headers to every response (pages, error pages, API). Example with a Content-Security-Policy and HSTS (the generated file keeps them commented out / ~):
security_headers:
enabled: true
headers:
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: 'camera=(), microphone=(), geolocation=()'
Content-Security-Policy: "default-src 'self'"
hsts: 31536000
excluded_paths: ['^/_profiler', '^/_wdt']
| Option | Default | Description |
|---|---|---|
enabled |
false (true in the generated app.yaml) |
adds the headers |
headers |
the 4 headers above, without Content-Security-Policy |
merged with the defaults; ~ removes a default header |
hsts |
~ |
Strict-Transport-Security on HTTPS requests: a number of seconds (max-age=N; includeSubDomains) or the full value |
excluded_paths |
profiler and toolbar | regular expressions of paths without the headers |
A header already set by the controller is kept: $response->headers->set('X-Frame-Options', 'DENY') makes one page stricter, Content-Security-Policy can be set per page the same way. The headers are added by NeoPHP\Component\Http\Helper\Event\SecurityHeadersListener (ResponseEvent) with NeoPHP\Component\Http\Security\SecurityHeaders.
Application in a sub-directory
The application can be installed in a sub-directory of the domain (https://example.com/app/, with public/index.php reachable at /app/index.php). The sub-directory is detected from SCRIPT_NAME:
| URL | getBasePath() |
getPath() |
getRequestPath() |
|---|---|---|---|
https://example.com/posts/1 |
'' |
/posts/1 |
/posts/1 |
https://example.com/app/posts/1 |
/app |
/posts/1 |
/app/posts/1 |
https://example.com/app/index.php/posts/1 |
/app/index.php |
/posts/1 |
/app/index.php/posts/1 |
The routes, the firewalls and access_control use getPath(), so they are written without the sub-directory (/posts/{id}, ^/admin). The generated URLs (path(), url(), redirectToRoute(), asset(), the login and logout redirections, the pagination links, the profiler) contain it. For absolute URLs generated outside of a request (console), set APP_URL with the sub-directory: APP_URL=https://example.com/app.
Reverse proxies and trusted hosts
Behind Nginx, a load balancer, Cloudflare or a PaaS, PHP sees the IP of the proxy and plain http. Declare the proxies in config/framework/app.yaml, their X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host and X-Forwarded-Port headers are then used by getClientIp(), isSecure(), getHost() and getPort() (secure cookies, absolute URLs, login throttling and rate limiting per IP):
# config/framework/app.yaml
trusted_proxies: '%env(TRUSTED_PROXIES)%' # e.g. TRUSTED_PROXIES=127.0.0.1,10.0.0.0/8
trusted_hosts: '%env(TRUSTED_HOSTS)%' # e.g. TRUSTED_HOSTS=example.com,*.example.com
http_method_override_header: false # true by default, false in the new projects
| Option | Values |
|---|---|
trusted_proxies |
list or comma separated string of IPs and CIDR ranges (127.0.0.1, 10.0.0.0/8, ::1); REMOTE_ADDR trusts the machine that sends the request (only when the application cannot be reached without the proxy) |
trusted_hosts |
list or comma separated string of host names (example.com, *.example.com) or regular expressions (^(www\.)?example\.com$); any other Host is refused with a 400 error. Empty: every host is accepted |
http_method_override_header |
true: a POST can change its method with the X-HTTP-Method-Override header; false ignores this header. The _method field of the forms always works |
The headers of a request that does not come from a trusted proxy are ignored: a client cannot fake its IP or the HTTPS scheme. Without trusted_hosts, a forged Host header can end up in the absolute URLs generated during the request (password reset emails): set it in production.
The same can be done in PHP with Request::setTrustedProxies(['10.0.0.0/8']), Request::setTrustedHosts(['example.com']) and Request::setHeaderMethodOverride(false).
Bags
ParameterBag (query, request, attributes, cookies, server) is iterable and countable:
| Method | Description |
|---|---|
all(), keys() |
all values, all keys |
get($key, $default), has($key), set($key, $value), remove($key) |
access |
replace($parameters), add($parameters) |
replace or merge values |
getString($key, $default), getInt($key, $default), getBoolean($key, $default) |
typed values |
FileBag extends ParameterBag and holds UploadedFile objects (or lists of them).
HeaderBag is case-insensitive: all(), get($name, $default) (first value), getValues($name), set($name, $values, $replace), has(), remove(), HeaderBag::fromServer($server).
Uploaded files
$file = $request->files->get('avatar');
if ($file instanceof UploadedFile && $file->isValid() && in_array($file->getMimeType(), ['image/jpeg', 'image/png', 'image/webp'], true)) {
// random name + extension detected from the content: e.g. var/uploads/avatars/3f9c...e1.png
$path = $file->move($this->get('kernel.root_path') . '/var/uploads/avatars');
}
Without a name, move() generates a random name and adds the extension detected from the file content (guessExtension()), never the one sent by the client. A name containing a directory, starting with a dot or ending with an executable extension (.php, .phtml, .phar, .htaccess...) is refused with a 400 error.
Store the uploaded files outside public/ (for example var/uploads/) and serve them through a controller. If they must be public, validate their MIME type with getMimeType() first: getClientOriginalExtension() and getClientMimeType() are sent by the client and cannot be trusted.
| Method | Returns |
|---|---|
getPath() |
temporary path |
getClientOriginalName(), getClientOriginalExtension(), getClientMimeType() |
information sent by the client (not trusted) |
getMimeType(), guessExtension() |
MIME type detected from the content (fileinfo) and its extension |
getSize() |
size in bytes |
getError(), getErrorMessage(), isValid() |
upload status (UPLOAD_ERR_*) |
move($directory, $name = null) |
moves the file (random name by default) and returns its new path |
Responses
$response = new Response('<h1>Hello</h1>', 200, ['X-Custom' => 'value']);
$response->setStatusCode(201);
$response->setHeader('Cache-Control', 'no-cache');
$response->setCookie('theme', 'dark', time() + 3600);
new JsonResponse(['ok' => true]);
new RedirectResponse('/login');
Response:
| Method | Description |
|---|---|
getContent(), setContent($content) |
body |
getStatusCode(), setStatusCode($code), getReasonPhrase() |
status |
getProtocolVersion(), setProtocolVersion($version) |
protocol (1.1) |
$response->headers, setHeader($name, $values, $replace) |
headers |
setCookie($name, $value, $expires, $path, $domain, $secure, $httpOnly, $sameSite) |
adds a Set-Cookie header ($expires: timestamp or DateTimeInterface, 0 for a session cookie) |
clearCookie($name, $path, $domain) |
expires a cookie |
isInformational(), isSuccessful(), isRedirection(), isClientError(), isServerError(), isEmpty() |
status checks |
prepare($request) |
fixes the headers for the request (default Content-Type, HEAD, empty responses) |
send(), sendHeaders(), sendContent() |
sends the response |
JsonResponse($data, $status, $headers, $flags) encodes $data (getData(), setData()), with Content-Type: application/json unless $headers gives one (application/problem+json...); JsonResponse::DEFAULT_FLAGS keeps slashes and unicode unescaped. RedirectResponse($url, $status = 302, $headers) sets the Location header (getTargetUrl()).
Streamed responses
NeoPHP\Component\Http\Response\StreamedResponse writes its body while it is sent, from a callback: the client receives the first bytes immediately and the memory stays low. Use it for large exports, long reports and server-sent events.
use NeoPHP\Component\Http\Response\StreamedResponse;
return $this->streamResponse(function () use ($repository): void {
$output = fopen('php://output', 'w');
fputcsv($output, ['id', 'email']);
foreach ($repository->iterateAll() as $user) {
fputcsv($output, [$user->getId(), $user->getEmail()]);
StreamedResponse::flushOutput();
}
}, 200, [
'Content-Type' => 'text/csv; charset=UTF-8',
'Content-Disposition' => 'attachment; filename="users.csv"',
]);
Server-sent events (for one-to-one streams such as the progress of a job; for broadcasting to many visitors, use the Mercure package):
return $this->streamResponse(function () use ($job): void {
while (!$job->isFinished()) {
echo 'data: ' . json_encode(['progress' => $job->getProgress()]) . "\n\n";
StreamedResponse::flushOutput();
sleep(1);
}
}, 200, ['Content-Type' => 'text/event-stream', 'Cache-Control' => 'no-cache', 'X-Accel-Buffering' => 'no']);
| Method | Description |
|---|---|
__construct(?callable $callback = null, int $status = 200, array $headers = []) |
the callback writes the body with echo, printf() or fwrite() on php://output |
setCallback(callable $callback), getCallback(): ?Closure |
the callback |
sendContent() |
runs the callback once (never for a HEAD request or an empty status), then flushes |
isStreamed(): bool |
whether the callback already ran |
StreamedResponse::flushOutput() |
sends what was written so far to the client: call it after each chunk |
getContent() returns '' and setContent() with a non-empty string throws HttpException: the body only exists while it is sent. prepare() removes Content-Length. The WebProfiler toolbar and the dumps of the Debug package are never injected in these responses.
Behind Nginx, send X-Accel-Buffering: no (or disable proxy_buffering) so that the chunks are not buffered by the proxy; with PHP-FPM, output_buffering must be off for the chunks to leave PHP before the end. The PHP session is still locked during the callback: call $session->save() before a long stream.
File responses
NeoPHP\Component\Http\Response\BinaryFileResponse sends a file of the disk by chunks of 64 KB, without loading it in memory:
// download (Content-Disposition: attachment), UTF-8 name proposed to the user
return $this->fileResponse($invoice->getPath(), 'Facture n°42.pdf');
// displayed in the browser (images, PDF, videos)
return $this->fileResponse($path, null, BinaryFileResponse::DISPOSITION_INLINE);
// temporary export deleted once sent
return (new BinaryFileResponse($zip, 200, [], 'attachment', 'photos.zip'))->deleteFileAfterSend();
The response handles by itself:
| Feature | Behaviour |
|---|---|
| Content type | detected from the content with ext-fileinfo, else from the extension (MIME_TYPES), else application/octet-stream; a Content-Type given in $headers is kept |
| Name | Content-Disposition with an ASCII name for the old browsers and the UTF-8 name (filename*, RFC 6266); a name with a slash, a backslash or a control character is refused |
| Cache | ETag (path, size and modification time) and Last-Modified; If-None-Match / If-Modified-Since answer 304 Not Modified without reading the file |
| Ranges | Accept-Ranges: bytes; a single Range (bytes=0-499, bytes=500-, bytes=-500) answers 206 Partial Content with Content-Range (resumed downloads, seeking in a video); an unsatisfiable range answers 416; several ranges or an invalid header send the whole file; If-Range is respected |
HEAD |
headers and Content-Length only |
| Method | Description |
|---|---|
__construct(string|SplFileInfo $file, int $status = 200, array $headers = [], ?string $disposition = null, ?string $filename = null, bool $autoEtag = true, bool $autoLastModified = true) |
a missing or unreadable file throws NotFoundHttpException (404) |
setFile(...), getFile(): SplFileInfo |
the file |
setContentDisposition(string $disposition, string $filename = '', ?string $fallback = null) |
attachment or inline |
deleteFileAfterSend(bool $delete = true) |
deletes the file after it is sent (also after a HEAD request) |
BinaryFileResponse::guessMimeType(SplFileInfo $file), BinaryFileResponse::parseRange(string $header, int $size) |
helpers |
Never build the path from a request value without checking it (../): send only files the visitor may read. Files of public/ are served by the web server itself; use a file response for private files (invoices, private photos) after checking the access.
HTTP service
NeoPHP\Component\Http\HttpManagerInterface (implemented by HttpManager) can be injected in a service:
| Method | Returns |
|---|---|
createRequestFromGlobals() |
the current Request |
createResponse($content, $status, $headers) |
a Response |
json($data, $status, $headers) |
a JsonResponse |
redirect($url, $status, $headers) |
a RedirectResponse |
stream($callback, $status, $headers) |
a StreamedResponse |
file($file, $filename = null, $disposition = 'attachment', $headers = []) |
a BinaryFileResponse |
send($response, $request) |
prepares and sends the response |
Controller helpers
The trait HttpController of AbstractController provides:
return $this->json(['id' => $post->getId()], 201);
return $this->json($post, 200, [], ['groups' => ['read']]);
return $this->redirect('/posts');
return $this->streamResponse(fn () => print('chunk'), 200, ['Content-Type' => 'text/plain']);
return $this->fileResponse($path, 'report.pdf');
throw $this->createNotFoundException('Post {id} not found.', ['id' => $id]);
throw $this->createAccessDeniedException();
json($data, $status = 200, $headers = [], $context = []): when $data contains objects, or when a $context is given, the data is normalized with the Serializer (#[Groups], #[SerializedName], #[Ignore], dates, enums, entities...) before the JsonResponse is built. Arrays of scalars are encoded as before. See the Serializer documentation for the context options.
The trait declares abstract protected function get(string $id): mixed; and abstract protected function has(string $id): bool; (both provided by ContainerController).
streamResponse($callback, $status = 200, $headers = []) and fileResponse($file, $filename = null, $disposition = 'attachment', $headers = []) create the responses of Streamed responses and File responses. They are not named stream() and file() so that they never collide with actions of the same name.
To redirect to a route, use redirectToRoute() (see the Routing documentation).
HTTP exceptions
All extend NeoPHP\Component\Exception\Exception\FrameworkException (see the Exception documentation):
| Exception | Status | Constructor |
|---|---|---|
TooManyRequestsHttpException |
429 | ($retryAfter = null, $message = 'Too Many Requests', $headers = [], $context = [], $previous = null): sets the Retry-After header, getRetryAfter(): ?int |
HttpException |
any | ($statusCode = 500, $message = '', $headers = [], $context = [], $previous = null) |
BadRequestHttpException |
400 | ($message = 'Bad Request', $context = [], $previous = null) |
AccessDeniedHttpException |
403 | ($message = 'Forbidden', $context = [], $previous = null) |
NotFoundHttpException |
404 | ($message = 'Not Found', $context = [], $previous = null) |
throw new HttpException(503, 'Maintenance in progress.', ['Retry-After' => '3600']);
Errors are rendered as HTML, or as JSON when the request sends Accept: application/json. With the Api component, API errors can be rendered as RFC 7807 problem details (application/problem+json, see the Api documentation).
Changelog
- v2.12.0 —
http_method_override_headeroption andRequest::setHeaderMethodOverride(): theX-HTTP-Method-Overrideheader can be ignored; the_methodfield of the forms always works. - v2.5.0 —
StreamedResponse(body written by a callback while it is sent,flushOutput()) andBinaryFileResponse(files sent by chunks, content type, UTF-8 download names,ETag/Last-Modifiedand304, single byte ranges with206/416,deleteFileAfterSend());HttpManagerInterface::stream()/file();streamResponse()/fileResponse()controller helpers; reason phrases of412and416. - v2.0.1 — Bugfix:
JsonResponsekeeps theContent-Typegiven in$headers; the regular expressions oftrusted_hostskeep their upper-case escapes (\D,\W...), only the host names are lower-cased. - v2.0.0 —
HttpManageris thefinalentry point of the module, declared with#[Component];HttpManagerInterfacereplacesContract\HttpInterface;Contract\AbstractHttpis merged into the manager;Helper/Listeneris renamedHelper/Event; the internal classes are marked@internal. - v1.31.0 — security headers (
security_headersinapp.yaml,SecurityHeaders); application in a sub-directory:getBasePath(),getRequestPath();getPath()no longer contains the sub-directory. - v1.30.0 — trusted proxies (
trusted_proxies:X-Forwarded-For,-Proto,-Host,-Port) and trusted hosts (trusted_hosts),isFromTrustedProxy(),Request::ipMatches(). - v1.29.1 (bugfix) —
UploadedFile::move()generates a random name by default, refuses executable extensions and path separators, creates directories in0775;getMimeType()andguessExtension()detect the type from the content. - v1.24.0 —
TooManyRequestsHttpException(429,Retry-After). - v1.23.0 —
json()accepts a serializer context and normalizes objects with the Serializer - v1.17.x (bugfix) — absolute URLs fall back on
getSchemeAndHttpHost()of the request whenAPP_URLis not set. - v1.0.0 —
Request,Response,JsonResponse,RedirectResponse, bags, uploaded files, HTTP exceptions and JSON errors.