Uploaded Files
Overview
A browser sends an uploaded file in a multipart/form-data request. The server stores the file in a temporary location and exposes it as a PSR-7 UploadedFileInterface. Windwalker reads these objects with file(), and the #[File] attribute injects them into a method parameter.
The file layer has two parts:
AppRequest::file(), also available asAppContext::file(): returns one file, several files, or all files.Windwalker\Http\UploadedFile: the object that moves and describes the file.
Uploaded files do not come from the query string or the parsed body. Use Request & Input for the other input sources.
Minimal Setup
The form must send multipart/form-data. Plain text fields in the same form are still read with input():
<form method="post" action="/profile/avatar"
enctype="multipart/form-data">
<input type="file" name="avatar">
<button type="submit">Upload</button>
</form>Read the file in a controller:
<?php
$avatar = $app->file('avatar');file('avatar') returns the UploadedFileInterface for the avatar field, or null when the field is missing.
Showcase: Saving an Avatar
The following controller validates the upload and moves it into a storage folder. It runs end to end with the form above:
<?php
declare(strict_types=1);
namespace App\Module\Front\Profile;
use Windwalker\Core\Application\AppContext;
use Windwalker\Core\Controller\Controller;
use Windwalker\Http\Response\JsonResponse;
class ProfileController extends Controller
{
public function avatar(AppContext $app): JsonResponse
{
$file = $app->file('avatar');
if ($file === null || $file->getError() !== UPLOAD_ERR_OK) {
return new JsonResponse(['error' => 'Upload failed.'], 400);
}
if ($file->getSize() > 2 * 1024 * 1024) {
return new JsonResponse(['error' => 'File too large.'], 413);
}
$name = bin2hex(random_bytes(16)) . '.jpg';
$file->moveTo('/path/to/storage/avatars/' . $name);
return new JsonResponse(['saved' => $name]);
}
}Replace /path/to/storage/avatars/ with the storage folder of your app.
POST /profile/avatar (avatar: 1 MB JPEG) 200 {"saved":"3f9c...jpg"}
POST /profile/avatar (no file) 400 {"error":"Upload failed."}
POST /profile/avatar (5 MB file) 413 {"error":"File too large."}The example checks the upload error code before it reads the size or moves the file. A failed upload has no usable temporary file.
Reading Files
file() has three forms:
file()returns every uploaded file, keyed by field name.file('avatar')returns one file, ornull.file('avatar', 'banner')returns aCollectionkeyed by field name. A missing field maps tonull.
<?php
$all = $app->file();
[$avatar, $banner] = $app->file('avatar', 'banner')->dump();Use #[File] to inject a file into a method parameter. It follows the same rules as #[Input]:
<?php
use Psr\Http\Message\UploadedFileInterface;
use Windwalker\Core\Attributes\Request\File;
public function avatar(
AppContext $app,
#[File] ?UploadedFileInterface $avatar = null,
): JsonResponse {
//
}A non-nullable #[File] parameter with no upload throws a RuntimeException with status code 400.
Working with UploadedFile
UploadedFile implements the PSR-7 methods. These are the ones you call most often:
getError(): anUPLOAD_ERR_*constant.UPLOAD_ERR_OKmeans the upload succeeded.getSize(): the size in bytes, ornullwhen unknown.getClientFilename(): the name the browser sent.getClientMediaType(): the MIME type the browser declared.moveTo($path): moves the file to$path.
WARNING
getClientFilename() and getClientMediaType() come from the client. Do not use them as a storage path or as proof of the file type. Generate the stored name yourself, and check the content of the file when the type matters.
INFO
moveTo() can be called only once per file. A second call, or a failed move, throws a RuntimeException.