Handling File Uploads

A profile form lets a user pick an avatar. The code reads $_FILES['avatar']['error'], and on the first real submission it dies with Warning: Undefined array key "avatar". Nothing is wrong with the PHP — the <form> tag is missing enctype="multipart/form-data". Without that attribute the browser sends the file field as an ordinary text field (usually an empty string), $_FILES stays empty, and the upload never happens. That attribute is the door; everything below assumes it is open.

With it, the browser sends one request body containing named parts, and PHP does the heavy lifting: it writes the raw bytes of each file to a temporary location (upload_tmp_dir, falling back to the system temp directory) and records what it knows in $_FILES. The shape surprises people who expect one flat array. Under each field name sit five parallel arrays:

// <input type="file" name="avatar">
$_FILES['avatar']['name'];      // client-supplied filename: "../../etc/passwd" is legal input
$_FILES['avatar']['type'];      // MIME the browser claims — attacker-controlled, not evidence
$_FILES['avatar']['tmp_name'];  // server path, e.g. /tmp/phpXYz123 — valid only this request
$_FILES['avatar']['error'];     // UPLOAD_ERR_* code, integer
$_FILES['avatar']['size'];      // bytes as reported by PHP

// <input type="file" name="photos[]" multiple>
$_FILES['photos']['name'][0];   // now arrays of arrays: index by position

$_FILES['avatar']['error'] is the field to read first, and it has a fixed vocabulary worth memorizing — interviewers ask for these:

Note the trap in codes 1 and 2: they are INI-level rejections, so the file never reaches your code. A user who ignores your in-page "max 2 MB" hint gets an ugly server error unless you translate the code into your own message.

The limits themselves form a hierarchy that confuses even experienced developers:

per file:   upload_max_filesize   (default 2M)
per request: post_max_size        (default 8M) — must be >= upload_max_filesize
handling:   memory_limit          — only matters if you load the file into memory

When the whole request body exceeds post_max_size, PHP discards both $_POST and $_FILES — the error code is not even set, because the field arrays were never populated. The giveaway is a $_POST that is empty while CONTENT_LENGTH is huge. The web server often gets there first: nginx answers 413 Request Entity Too Large from client_max_body_size before PHP runs at all. Knowing which layer rejected the request is the difference between a fixable message and a ghost bug.

Finally, $_FILES['...']['tmp_name'] lives only for the duration of the request. PHP deletes it at shutdown, so any code path that validates but forgets to store the file silently discards the user's data — the next chapter covers what to do with it.

The temporary file is proven legitimate by PHP; everything else about it — name, type, content — is a claim by the client. The job between $_FILES and durable storage is turning claims into verified facts:

$f = $_FILES['avatar'] ?? null;
if ($f === null || $f['error'] !== UPLOAD_ERR_OK) {
    $msg = match ($f['error'] ?? UPLOAD_ERR_NO_FILE) {
        UPLOAD_ERR_INI_SIZE, UPLOAD_ERR_FORM_SIZE => 'File exceeds the 2 MB limit.',
        UPLOAD_ERR_NO_FILE                        => 'Please choose a file.',
        default                                    => 'Upload failed, try again.',
    };
    throw new InvalidArgumentException($msg);
}

if ($f['size'] > 2 * 1024 * 1024) {                 // app limit, independent of INI
    throw new InvalidArgumentException('File exceeds the 2 MB limit.');
}

$allowed = [
    'image/jpeg' => 'jpg',
    'image/png'  => 'png',
    'image/webp' => 'webp',
];
$mime = (new finfo(FILEINFO_MIME_TYPE))->file($f['tmp_name']);
if (!isset($allowed[$mime])) {
    throw new InvalidArgumentException('Only JPEG, PNG, or WebP images are accepted.');
}

$name = bin2hex(random_bytes(16)) . '.' . $allowed[$mime];   // extension from the sniff, not the client
$dest = '/var/www/storage/avatars/' . $name;

if (!move_uploaded_file($f['tmp_name'], $dest)) {
    throw new RuntimeException('Could not store the upload.');
}
chmod($dest, 0644);

Every line answers a specific attack:

• $f['name'] is never used. It can contain ../../, NUL-era tricks, or shell.php. The stored name is random bytes plus an extension you derived yourself — which also means no collisions, no overwriting another user's file, and no guessing other people's URLs.
• $f['type'] is never checked for security. It is a header the client chose. finfo reads the file's leading bytes on the server; a .exe renamed cat.png fails the sniff. For images, getimagesize() adds a structural check that the header really parses as an image.
• Whitelist, never blacklist. in_array($ext, ['jpg','png']) beats !in_array($ext, ['php','phtml']) every time — the blacklist misses the next dangerous extension and your server's handler list may execute files you have never heard of.

move_uploaded_file() deserves its own explanation, because it is not copy() with a different name. It performs two operations: it verifies through the SAPI that the source really is the file PHP received for this POST (the same check is_uploaded_file() does), then it moves it — copying across filesystems when temp and destination are on different mounts, where a plain rename() would fail. A local path you pass to copy() skips the provenance check entirely; if any code path can be steered to copy an arbitrary server file into your storage, you have built a file-disclosure bug. Use the upload API for uploads.

For multi-file fields, loop over the parallel arrays by index, and remember MAX_FILE_SIZE — a hidden field some frameworks emit — is a client-side hint only: a browser may ignore it entirely, so $f['size'] is still checked server-side. The same applies to your app-level limit: INI directives protect the server, your explicit check is what enforces the promise the UI made to the user. Log the code and size of every rejected upload; a spike in code-1 rejections after a marketing campaign means your advertised limit is smaller than what people are trying to send. Also note that max_file_uploads (default 20) caps how many file parts one request may carry — beyond it, extra files are silently absent rather than errored.

Validation failures need no cleanup: PHP removes the temporary file at request end. On success the temporary file is gone by definition — it was moved. What you must never do is leave the destination name under the client's control, which is exactly what the next topic attacks.

A startup stored uploads at public/uploads/ with the client's filename intact. An attacker sent avatar.php.jpg against a server whose Apache config mapped handlers by extension pattern, then requested /uploads/avatar.php.jpg — and PHP executed the image. The validation was fine; the assumption that stored files are inert was wrong. Treat every upload as code that someone will eventually try to run.

The strongest control is architectural: store files outside the document root (/var/www/storage/avatars, reachable only through a script that validates the id and streams it with readfile() plus Content-Type you chose). Nothing under the web root can execute what the web server cannot see.

When the files must be web-accessible — a media CDN path, a legacy layout — deny execution at the server:

# nginx: never run anything from the upload tree
location ^~ /uploads/ {
    location ~ \.php$ { deny all; }
    add_header X-Content-Type-Options nosniff always;
}

# Apache: only if AllowOverride permits it
<Directory "/var/www/public/uploads">
    php_admin_flag engine off
    Options -ExecCGI -Indexes
</Directory>

Note php_admin_flag in a server/directory block: it cannot be overridden by a dropped .htaccess, so an attacker cannot undo it. Relying on .htaccess alone fails on nginx (no .htaccess at all) and on any vhost with AllowOverride None.

Defense in depth after storage:

• Serve with X-Content-Type-Options: nosniff so a browser cannot upgrade text/plain into an executable interpretation, and force Content-Disposition: attachment for anything that is not the image type you expect.
• Serve through a script, not a static URL when downloads matter: the handler looks up an id in your database, checks authorization, then streams — a stolen path is useless without the row behind it.
• Keep the extension derived from the sniffed MIME type, not from the client name. shell.php smuggled inside photo.jpg keeps .jpg and no handler will touch it.

Size limits must agree at every layer, or the error surfaces at the wrong one:

upload_max_filesize = 10M
post_max_size       = 12M      ; strictly larger: it also carries the form fields
max_file_uploads    = 20

nginx adds client_max_body_size 12m; and PHP's max_input_time must cover the transfer — a slow 10 MB upload over a bad connection is a timeout, not a size error, and returns UPLOAD_ERR_PARTIAL (code 3).

Two last habits. First, check $f['size'] in your own code even though INI limits exist: INI limits are per server, your promise to the user is per app, and a mismatch means users on one environment get errors the docs never mention. Second, move the file before you process it — move_uploaded_file() is constant-memory, while imagecreatefromjpeg() on a 30 MB file is not, so you can stream or re-encode from the destination with fopen() instead of holding it in RAM. Two more habits: delete on downstream failure — when the move succeeds but the database insert then fails, unlink($dest) before returning, or every rejected submission leaves an orphan nobody will clean up — and test through the real client: curl -F 'avatar=@cat.png' https://app.test/profile reproduces the multipart path with no browser involved, while php -i | grep upload_ shows the limits your production SAPI actually loads, since CLI, php-fpm, and the Apache module can each be reading a different php.ini.

With files landing in a predictable directory under your chosen names, the remaining question is what happens when the path itself is attacker input — the subject of Safe Path Handling. For the mechanics of reading files back, revisit Reading and Writing Files.