How a PHP File Upload Actually Works

A PHP upload moves through several separate stages. The browser first builds a multipart POST request. The web server and PHP compare the request with configured size and upload limits. PHP writes an accepted upload to a temporary location and creates an entry in $_FILES. Your application then validates the upload, creates a safe destination filename, moves the temporary file and saves a portable value in the database.

A visible “upload failed” message does not identify which stage failed. The form may never have sent a multipart request. PHP may have rejected the request before your script received it. The temporary file may exist while the destination directory does not. The move may succeed while the database insert fails. The database may contain the correct filename while the HTML uses a server path that a browser cannot open.

What PHP Stores in $_FILES

A single file input named profile_image normally produces an array with the original client filename, temporary server filename, upload error code, reported size and browser-supplied type.

$_FILES["profile_image"]["name"]
$_FILES["profile_image"]["tmp_name"]
$_FILES["profile_image"]["error"]
$_FILES["profile_image"]["size"]
$_FILES["profile_image"]["type"]

Your code should inspect error before using tmp_name. An error code other than UPLOAD_ERR_OK means the application should stop and handle that specific condition.

Why $_FILES Can Be Completely Empty

A missing file key and a completely empty $_FILES array are not always the same failure. A missing key can come from a form name mismatch. A completely empty request may mean the browser did not send multipart data or PHP rejected the entire request before normal form processing.

Check these conditions in order:

1. The form uses method="post".
2. The form includes enctype="multipart/form-data".
3. The file input has a valid name attribute.
4. The input is not disabled.
5. The PHP key exactly matches the input name.
6. file_uploads is enabled.
7. The entire request does not exceed post_max_size.

Filesystem Path Versus Browser URL

PHP and the browser use two different address systems. PHP moves the file using a server filesystem path. HTML displays the file using a public URL.

Filesystem destination used by PHP

C:\xampp\htdocs\student-project\uploads\photo.jpg

/var/www/html/student-project/uploads/photo.jpg

Public URL used by the browser

http://localhost/student-project/uploads/photo.jpg

https://example.com/uploads/photo.jpg

A Windows path placed directly in an image src attribute will not become a normal website URL. A portable application commonly stores photo.jpg or uploads/photo.jpg in the database, then builds the server path and public URL separately.

$filesystemPath = __DIR__ . "/uploads/" . $filename;
$publicUrl = "uploads/" . rawurlencode($filename);

Why move_uploaded_file() Returns False

The function expects a temporary source that PHP recognizes as a file uploaded through HTTP POST. It also needs a valid destination path that the server can write.

Before moving, confirm:

• The upload error code equals UPLOAD_ERR_OK.
• tmp_name is not empty.
• is_uploaded_file($tmpName) returns true.
• The destination directory exists.
• The destination directory is writable.
• The generated filename contains no path traversal.
• The destination path uses the correct project directory.
• The destination does not unintentionally overwrite another file.

Do Not Validate Uploads Using Only the Extension

A filename ending in .jpg does not prove that its contents are a JPEG image. The original name and browser-reported type come from the client and can be misleading.

For general files, Fileinfo can inspect the temporary file and return a detected MIME type. For images, combine a MIME allowlist with an image inspection function such as getimagesize(). Then map the detected MIME type to an extension selected by the server.

$allowed = [
    "image/jpeg" => "jpg",
    "image/png"  => "png",
    "image/webp" => "webp"
];

$finfo = new finfo(FILEINFO_MIME_TYPE);
$mime = $finfo->file($tmpName);

if (!isset($allowed[$mime])) {
    exit("Unsupported image type.");
}

$imageInfo = getimagesize($tmpName);

if ($imageInfo === false) {
    exit("The uploaded file is not a readable image.");
}

Validation should reflect the project’s real needs. A profile-image feature should not accept arbitrary executable or archive files merely because the upload folder exists.

Use Server-Generated Filenames

Original filenames can contain spaces, unusual Unicode characters, repeated names or path-like content. Saving every image under a fixed name also causes each new upload to overwrite the previous one.

A collision-resistant filename can be generated like this:

$filename = bin2hex(random_bytes(16)) . "." . $extension;

Store the original filename separately only when the application needs to show it to the user. Do not use the original name as proof of type or as the permanent storage path.

Coordinate the File Move and Database Save

The filesystem and MySQL do not automatically share one transaction. This creates two possible inconsistencies:

• The database contains a filename but the file move failed.
• The file exists but the database insert or update failed.

A safer sequence is:

1. Validate the request and upload error.
2. Inspect file contents and size.
3. Generate a safe destination filename.
4. Move the file successfully.
5. Save the confirmed filename inside a database transaction.
6. If the database operation fails, remove the newly moved file.

When replacing an existing image, keep the old file until the new file has moved and the database update has committed. Delete the previous file only after the record points to the new file.

Multiple-File Uploads

A multiple-file input should use both the attribute and array-style name:

PHP then stores arrays under each file property. Your code must loop through the matching indexes of name, tmp_name, error and size.

The PHP max_file_uploads setting may also limit how many files one request accepts. Application limits should be lower when the project does not need large batches.

Upload Works in XAMPP but Fails on Hosting

A local Windows project and a hosted Linux server may behave differently even when the same PHP file is uploaded.

• Hosting upload and POST limits may be lower.
• The destination folder may not be writable by the web-server user.
• Linux filenames are usually case-sensitive.
• The document root and filesystem layout may be different.
• open_basedir may restrict accessible directories.
• Fileinfo or image extensions may differ.
• Temporary storage may be full or unavailable.
• A hosting security rule may reject specific types or request sizes.

Use __DIR__ to anchor server paths to the current PHP file rather than assuming the process always runs from the same working directory.

Safe Upload Debugging Order

1. Confirm the request uses POST and multipart encoding.
2. Compare the input name with the exact $_FILES key.
3. Inspect whether $_FILES is empty or contains an error code.
4. Compare the file size with both upload and POST limits.
5. Check tmp_name and is_uploaded_file().
6. Validate size and detected file contents.
7. Confirm the destination directory exists and is writable.
8. Generate a safe server-side filename.
9. Move the file and check the return value.
10. Save a portable database value only after the move succeeds.
11. Build the HTML URL separately from the filesystem path.
12. Test cleanup when the database operation fails.

Common Upload Fixes That Create Bigger Problems

Continue Your CodeZips Project Workflow

Technical References

• PHP Manual: Handling File Uploads
• PHP Manual: POST Method Uploads
• PHP Manual: Upload Error Messages
• PHP Manual: move_uploaded_file()
• PHP Manual: is_uploaded_file()
• PHP Manual: Uploading Multiple Files
• PHP Manual: finfo_file()
• PHP Manual: getimagesize()