move_uploaded_file()
debt(d5/e1/b3/t7)
Closest to 'specialist tool catches it' (d5). The detection_hints list semgrep and psalm as tools, and the code_pattern describes rename() or copy() used instead of move_uploaded_file() — this is catchable by SAST tools like semgrep but not by a default linter or compiler, placing it squarely at d5.
Closest to 'one-line patch or single-call swap' (e1). The quick_fix explicitly states: replace rename() or copy() with move_uploaded_file(). That is a direct single-call substitution, making this e1.
Closest to 'localised tax' (b3). The applies_to context is web-only PHP file upload handling — this pattern is isolated to upload endpoints. It doesn't shape the whole codebase, just the upload handling component. Additional mistakes (MIME validation, webroot placement) add some localised tax but remain contained.
Closest to 'serious trap (contradicts how a similar concept works elsewhere)' (t7). The misconception field states developers believe copy() and move_uploaded_file() are interchangeable — a highly plausible mistake since copy() and rename() perform the same filesystem operation in virtually all other contexts. The critical HTTP POST validation check is invisible and unique to move_uploaded_file(), making this a serious trap that contradicts normal file-manipulation expectations.
Also Known As
TL;DR
Explanation
move_uploaded_file() verifies that the file is a legitimate HTTP upload (using is_uploaded_file() internally) before moving it, preventing path manipulation attacks that attempt to move arbitrary files. It must be combined with strict validation of the file type (via mime_content_type() or finfo), a sanitised filename (never trust $_FILES['name']), a destination outside the web root or with execute permissions disabled, and a size limit check. Relying on client-supplied Content-Type or file extension alone is insufficient.
Common Misconception
Why It Matters
Common Mistakes
- Using rename() or copy() instead of move_uploaded_file() — they do not verify the file came from an upload.
- Not validating the file type and size before calling move_uploaded_file().
- Moving files to a web-accessible directory without disabling script execution in that directory.
- Using the original filename from $_FILES['name'] — sanitise it; attacker controls this value.
Code Examples
// Moving to a predictable path with user-supplied filename
copy($_FILES['upload']['tmp_name'], '/uploads/' . $_FILES['upload']['name']);// Validate, generate a safe filename, use move_uploaded_file
$upload = $_FILES['avatar'];
// 1. Check it's actually an uploaded file
if (!is_uploaded_file($upload['tmp_name'])) { abort(400); }
// 2. Validate MIME type via finfo (not the browser-supplied type)
$finfo = new \finfo(FILEINFO_MIME_TYPE);
$mime = $finfo->file($upload['tmp_name']);
if (!in_array($mime, ['image/jpeg', 'image/png', 'image/webp'], true)) { abort(415); }
// 3. Generate a random filename — never trust the original
$ext = ['image/jpeg'=>'jpg','image/png'=>'png','image/webp'=>'webp'][$mime];
$filename = bin2hex(random_bytes(16)) . '.' . $ext;
// 4. Move — only move_uploaded_file is safe for uploaded files
move_uploaded_file($upload['tmp_name'], '/var/uploads/' . $filename);