PHP move_uploaded_file() Function: Usage and Examples

move_uploaded_file() Function is one of the PHP operations used in filesystem and stream workflows. Moves a verified HTTP-upload temporary file to a destination. The examples below show what it does and how to handle its result.

What Is move_uploaded_file() Function?

Moves a verified HTTP-upload temporary file to a destination.

Its syntax is:

move_uploaded_file(string $from, string $to)

The parameters are:

• string $from — Source filename or archive entry name, depending on the operation.
• string $to — Destination filename or archive entry name, depending on the operation.

Return value: The declared return type is bool. It only accepts genuine uploaded files and will not work with ordinary test files.

Requirements: Requires a real HTTP POST multipart/form-data upload; a CLI-created file is not a PHP-uploaded temporary file.

Important: It only accepts genuine uploaded files and will not work with ordinary test files.

Example 1: Basic Usage

The basic example focuses on the behavior of move_uploaded_file() Function: moves a verified HTTP-upload temporary file to a destination. Inputs are defined locally or shown as application-controlled paths.

<?php

if (isset($_FILES["attachment"]) && $_FILES["attachment"]["error"] === UPLOAD_ERR_OK) {
    $targetPath = __DIR__ . "/private-uploads/" . bin2hex(random_bytes(16)) . ".bin";
    if (!move_uploaded_file($_FILES["attachment"]["tmp_name"], $targetPath)) { throw new RuntimeException("Upload move failed"); }
}

The displayed value, file content or return status depends on the input and surrounding environment. Results involving local paths, identifiers or generated files are not fixed values.

Example 2: A Different Use Case

This second example illustrates another input or execution condition for move_uploaded_file() Function. Notice the different checks, arguments, or output handling.

<?php

$upload = $_FILES["avatar"] ?? null;
if ($upload !== null && $upload["error"] === UPLOAD_ERR_OK && is_uploaded_file($upload["tmp_name"])) {
    $destination = __DIR__ . "/private-uploads/" . bin2hex(random_bytes(16)) . ".bin";
    var_dump(move_uploaded_file($upload["tmp_name"], $destination));
}

This variation matters because it only accepts genuine uploaded files and will not work with ordinary test files.

Practical Example: Using the Operation in an Application

The following example demonstrates how move_uploaded_file() Function fits into a more complete file or archive workflow, including inputs and appropriate checks.

<?php

$upload = $_FILES["document"] ?? null;
if ($upload === null || $upload["error"] !== UPLOAD_ERR_OK || !is_uploaded_file($upload["tmp_name"])) { throw new RuntimeException("Invalid upload"); }
$targetPath = __DIR__ . "/private-storage/" . bin2hex(random_bytes(16)) . ".bin";
if (!move_uploaded_file($upload["tmp_name"], $targetPath)) { throw new RuntimeException("Save failed"); }

The operation shown is an illustrative script. Adapt the filenames, required permissions, and error handling to your own controlled application environment before running it.

Important Behavior and Edge Cases

• Function behavior: Moves a verified HTTP-upload temporary file to a destination.
• Limitation: It only accepts genuine uploaded files and will not work with ordinary test files.
• Availability: Requires a real HTTP POST multipart/form-data upload; a CLI-created file is not a PHP-uploaded temporary file.

Comparison With Related Functions

Use move_uploaded_file() Function for the specific behavior described above. The related operation, rename(), serves a different purpose; do not substitute it unless that different behavior is intended.

Common Beginner Mistakes

Key Takeaways

• Moves a verified HTTP-upload temporary file to a destination.
• It only accepts genuine uploaded files and will not work with ordinary test files.
• Related operation: rename() — Moves or renames ordinary filesystem paths; move_uploaded_file() specifically validates uploaded-file origins.

move_uploaded_file() Function is useful when its specific behavior matches your application requirement. Keep paths controlled, check failures, and handle environment-dependent operations deliberately.