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_header option and Request::setHeaderMethodOverride(): the X-HTTP-Method-Override header can be ignored; the _method field of the forms always works.
  • v2.5.0 — StreamedResponse (body written by a callback while it is sent, flushOutput()) and BinaryFileResponse (files sent by chunks, content type, UTF-8 download names, ETag / Last-Modified and 304, single byte ranges with 206 / 416, deleteFileAfterSend()); HttpManagerInterface::stream() / file(); streamResponse() / fileResponse() controller helpers; reason phrases of 412 and 416.
  • v2.0.1 — Bugfix: JsonResponse keeps the Content-Type given in $headers; the regular expressions of trusted_hosts keep their upper-case escapes (\D, \W...), only the host names are lower-cased.
  • v2.0.0 — HttpManager is the final entry point of the module, declared with #[Component]; HttpManagerInterface replaces Contract\HttpInterface; Contract\AbstractHttp is merged into the manager; Helper/Listener is renamed Helper/Event; the internal classes are marked @internal.
  • v1.31.0 — security headers (security_headers in app.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 in 0775; getMimeType() and guessExtension() 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 when APP_URL is not set.
  • v1.0.0 — Request, Response, JsonResponse, RedirectResponse, bags, uploaded files, HTTP exceptions and JSON errors.