move_uploaded_file()

¿Qué es la función move_uploaded_file()?

La función move_uploaded_file() es una función integrada de PHP que mueve un archivo subido a través de un formulario HTML a una ubicación permanente en el servidor. Cuando un navegador sube un archivo, PHP primero lo almacena en un directorio temporal con un nombre aleatorio. Ese archivo temporal se elimina automáticamente cuando el script termina, por lo que debes moverlo a un lugar permanente si quieres conservarlo — para eso sirve exactamente move_uploaded_file().

Lo que hace especial a esta función es su verificación de seguridad integrada. Solo mueve un archivo si PHP confirma que fue genuinamente subido mediante una solicitud HTTP POST. Esto evita que un atacante engañe a tu script para que mueva un archivo sensible del servidor (como /etc/passwd) proporcionando su ruta. Por esa razón, siempre debes usar move_uploaded_file() en lugar de copy() o rename() para gestionar subidas de archivos.

Esta página cubre la sintaxis, los parámetros, el valor de retorno, un ejemplo completo y funcional, los códigos de error de subida que debes verificar y los problemas de seguridad a tener en cuenta.

Sintaxis

move_uploaded_file(string $from, string $to): bool

Valor de retorno

move_uploaded_file() devuelve true si el archivo se movió correctamente. Devuelve false si $from no es un archivo subido válido (por ejemplo, si la ruta fue falsificada) o si el movimiento en sí falla — típicamente por un directorio de destino inexistente o permisos de escritura insuficientes. En el caso de archivo falsificado, PHP también emite una advertencia y no se realiza ningún movimiento.

¿Cómo usar la función move_uploaded_file()?

Usar la función move_uploaded_file() es sencillo. Aquí están los pasos a seguir:

1. Verifica que la subida del archivo se realizó correctamente comprobando $_FILES['file']['error'].
2. Especifica la ruta de destino para el archivo.
3. Llama a la función move_uploaded_file(), pasando el nombre de archivo temporal y la ruta de destino.

Aquí hay un fragmento de código de ejemplo que demuestra cómo usar la función move_uploaded_file():

¿Cómo usar la función move_uploaded_file()?

<?php

if ($_FILES['file']['error'] === UPLOAD_ERR_OK) {
    $uploaded_file = $_FILES['file']['tmp_name'];
    $destination_path = '/path/to/new/location/' . basename($_FILES['file']['name']);
    if (move_uploaded_file($uploaded_file, $destination_path)) {
        echo "File uploaded successfully!";
    } else {
        echo "Error uploading file.";
    }
} else {
    echo "File upload failed.";
}

En este ejemplo, primero verificamos que la subida se realizó correctamente usando $_FILES['file']['error']. Luego especificamos la ruta de destino para el archivo y usamos basename() para extraer de forma segura el nombre del archivo y evitar vulnerabilidades de traversal de ruta. Finalmente, usamos la función move_uploaded_file() para mover el archivo subido a la nueva ubicación. Si el archivo se mueve correctamente, mostramos un mensaje de éxito. Si hay un error al mover el archivo, mostramos un mensaje de error.

El formulario HTML correspondiente debe usar method="post" y enctype="multipart/form-data", de lo contrario $_FILES estará vacío:

<form action="upload.php" method="post" enctype="multipart/form-data">
    <input type="file" name="file">
    <input type="submit" value="Upload">
</form>

El atributo name del campo de archivo (file aquí) es la clave que se lee de $_FILES.

Códigos de Error de Subida

El valor de $_FILES['file']['error'] indica si y por qué falló una subida. Siempre verifícalo antes de mover el archivo. Los códigos más comunes son:

Dos configuraciones del servidor frecuentemente causan fallos silenciosos: upload_max_filesize y post_max_size. Si el archivo subido es mayor que cualquiera de estos límites, $_FILES puede llegar vacío o con un código de error, sin importar qué tan correcto sea tu código PHP.

Notas de Seguridad

• Nunca confíes en el nombre de archivo original. Usa basename() en $_FILES['file']['name'], o mejor aún, genera tu propio nombre seguro, para evitar traversal de ruta como ../../config.php.
• Valida el tipo de archivo por su contenido real (por ejemplo con finfo / mime_content_type), no solo por su extensión — el cliente puede mentir tanto en la extensión como en el campo type.
• Almacena las subidas fuera del directorio raíz web cuando sea posible, para que los usuarios no puedan ejecutar directamente los scripts subidos.
• Para una verificación doble explícita de que una ruta es un archivo realmente subido, consulta is_uploaded_file() — aunque move_uploaded_file() ya realiza esta verificación internamente.

Conclusión

La función move_uploaded_file() es la forma correcta y segura de mover un archivo subido mediante HTTP POST desde el directorio temporal de PHP a una ubicación permanente. Devuelve true en caso de éxito y false en caso de fallo, y se niega a mover cualquier cosa que no haya sido genuinamente subida. Siempre verifica el código de error de subida primero, sanea el nombre de archivo de destino y valida el archivo antes de confiar en él.

Para el flujo de trabajo general sobre la gestión de subidas, consulta PHP File Upload y el resto de PHP File Handling.

Práctica