Documentation
File transfers
Limit uploads and stream downloads and media without buffering whole files.
Requires skyyware/stage 0.1.3 or later. PHP receives multipart uploads into
temporary files before Stage dispatches the request. UploadedFile validates
one upload; FileResponse streams a regular file as an attachment. Both leave
storage and access decisions in your application.
Run a local round trip
Create a new application:
mkdir stage-files
cd stage-files
composer require skyyware/stage
mkdir public
Create public/index.php:
<?php
declare(strict_types=1);
use Stage\Http\Application;
use Stage\Http\FileResponse;
use Stage\Http\Route;
use Stage\Http\UploadedFile;
require dirname(__DIR__) . '/vendor/autoload.php';
(new Application(
new Route('POST', '/files', function (): FileResponse {
$file = UploadedFile::fromPhp($_FILES['file'] ?? [], maxBytes: 10_000_000);
return new FileResponse($file->path, $file->name, [
'cache-control' => 'no-store',
'content-security-policy' => "default-src 'none'; sandbox",
]);
}),
))->run();
Start a local server with PHP upload limits above the application's 10 MB limit.
PHP's M settings use powers of 1024; the application's limit is decimal bytes.
php -d upload_max_filesize=10M -d post_max_size=11M \
-d output_buffering=0 -d zlib.output_compression=0 \
-S 127.0.0.1:8080 -t public public/index.php
In a second terminal, from the application directory:
printf 'hello from Stage\n' > example.txt
curl --fail --form file=@example.txt \
--dump-header headers.txt --output returned.txt http://127.0.0.1:8080/files
cmp example.txt returned.txt
curl --include --request POST http://127.0.0.1:8080/files
cmp succeeds without output. The download has an attachment disposition,
application/octet-stream, nosniff, and the file's length. The request without
a file returns 400 with {"error":400}. Stop the server with Ctrl+C.
This local example returns the temporary upload immediately and retains
nothing. PHP removes the temporary file when the request ends. To keep a file,
validate the caller and application rules, then use move_uploaded_file with
an application-generated destination outside public/. Check the move's result
before recording success. Never use the client name as a storage path.
Serve a stored file
After the application has authorized access and resolved its own storage path,
return a FileResponse from a GET handler:
return new FileResponse($authorizedPath, $displayName, [
'cache-control' => 'no-store',
'x-robots-tag' => 'noindex',
'content-security-policy' => "default-src 'none'; sandbox",
]);
Its optional headers survive file delivery. A HEAD request uses the GET route
and receives the same length without a body. GET handlers must account for
that fallback before recording download counts or other side effects. Do not
rebuild this response from $response->body; that property is empty because
the file is not buffered. The HTTP reference lists
validation, errors, and current limitations.
Serve inline media
Requires skyyware/stage 0.1.5 or later. Use FileResponse::inline when a
browser should play an allowed audio or video file and seek within it.
In a GET handler that accepts a Stage\Http\Request:
return FileResponse::inline($authorizedPath, $displayName, $validatedContentType, $request, [
'cache-control' => 'no-store',
'x-robots-tag' => 'noindex',
]);
Resolve $authorizedPath only after checking access and any share expiry.
Set $validatedContentType from your application's media allowlist after
checking the file. Stage validates the type/subtype syntax; it does not
inspect content or decide whether it is safe to display. Do not pass through
an uploaded MIME type or enable inline HTML or SVG for untrusted files.
A GET with one satisfiable byte range returns 206 and only those bytes.
An unsatisfiable range returns an empty 416 response. Malformed and multiple
ranges fall back to the full file with 200. If-Range also falls back to 200;
Stage does not evaluate validators. HEAD ignores Range and sends the full
length without a body. The HTTP reference
defines the accepted ranges and remaining limits.
Existing new FileResponse(...) calls remain attachment downloads. They keep
their octet-stream content type and do not process Range.
Set limits at each boundary
Stage's raw request limit remains 1 MiB. It does not limit PHP-parsed multipart
data. Keep enable_post_data_reading enabled and read parsed fields from
$_POST. Configure upload_max_filesize, a larger post_max_size, a writable
upload temporary directory, and server request limits and timeouts. PHP's
upload documentation
describes this lifecycle.
If the whole POST exceeds post_max_size, PHP leaves both input arrays empty.
UploadedFile::fromPhp then reports a missing file with 400. To report 413 for
that case, enforce a total request limit in the server or application adapter
before dispatch. Application validation cannot prevent PHP receiving a request
before the script runs. See PHP's
core configuration.
Stage reads downloads in 64 KiB chunks. Disable application output buffers and compression that would accumulate or transform the body. Keep stored files unchanged during delivery. Disk failure or concurrent truncation can end a response early after headers have been sent. File access rules, content checks, storage quotas, concurrent use, and retention need application-level tests.
Version and source
Examples use Stage 0.1.5. Framework guide.