move_uploaded_file()

Qu'est-ce que la fonction move_uploaded_file() ?

La fonction move_uploaded_file() est une fonction PHP intégrée qui déplace un fichier téléchargé via un formulaire HTML vers un emplacement permanent sur le serveur. Lorsqu'un navigateur envoie un fichier, PHP le stocke d'abord dans un répertoire temporaire sous un nom aléatoire. Ce fichier temporaire est automatiquement supprimé à la fin du script, vous devez donc le déplacer vers un endroit permanent si vous souhaitez le conserver — c'est exactement l'utilité de move_uploaded_file().

Ce qui rend cette fonction particulière, c'est sa vérification de sécurité intégrée. Elle ne déplace un fichier que si PHP confirme qu'il a bien été téléchargé via une requête HTTP POST. Cela empêche un attaquant de tromper votre script pour qu'il déplace un fichier sensible du serveur (comme /etc/passwd) en fournissant son chemin. Pour cette raison, vous devriez toujours utiliser move_uploaded_file() plutôt que copy() ou rename() pour gérer les téléchargements.

Cette page couvre la syntaxe, les paramètres, la valeur de retour, un exemple complet et fonctionnel, les codes d'erreur de téléchargement à vérifier, ainsi que les problèmes de sécurité à surveiller.

Syntaxe

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

Valeur de retour

move_uploaded_file() retourne true si le fichier a été déplacé avec succès. Elle retourne false si $from n'est pas un fichier téléchargé valide (par exemple, si le chemin a été falsifié) ou si le déplacement lui-même échoue — généralement en raison d'un répertoire de destination manquant ou de permissions d'écriture insuffisantes. Dans le cas d'un fichier falsifié, PHP émet également un avertissement et aucun déplacement n'est effectué.

Comment utiliser la fonction move_uploaded_file() ?

L'utilisation de la fonction move_uploaded_file() est simple. Voici les étapes à suivre :

1. Vérifiez que le téléchargement du fichier a réussi en vérifiant $_FILES['file']['error'].
2. Spécifiez le chemin de destination du fichier.
3. Appelez la fonction move_uploaded_file() en lui passant le nom de fichier temporaire et le chemin de destination.

Voici un exemple de code qui illustre l'utilisation de la fonction move_uploaded_file() :

Comment utiliser la fonction 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.";
}

Dans cet exemple, nous vérifions d'abord que le téléchargement a réussi en utilisant $_FILES['file']['error']. Nous spécifions ensuite le chemin de destination du fichier et utilisons basename() pour extraire en toute sécurité le nom de fichier et éviter les vulnérabilités de traversée de chemin. Enfin, nous utilisons la fonction move_uploaded_file() pour déplacer le fichier téléchargé vers le nouvel emplacement. Si le fichier est déplacé avec succès, nous affichons un message de réussite. En cas d'erreur lors du déplacement, nous affichons un message d'erreur.

Le formulaire HTML correspondant doit utiliser method="post" et enctype="multipart/form-data", sinon $_FILES sera vide :

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

L'attribut name du champ de fichier (file ici) est la clé que vous lisez dans $_FILES.

Codes d'erreur de téléchargement

La valeur de $_FILES['file']['error'] vous indique si et pourquoi un téléchargement a échoué. Vérifiez-la toujours avant de déplacer le fichier. Les codes les plus courants sont :

Deux paramètres du serveur provoquent fréquemment des échecs silencieux : upload_max_filesize et post_max_size. Si le fichier téléchargé dépasse l'une ou l'autre limite, $_FILES peut arriver vide ou avec un code d'erreur, quel que soit la correction de votre code PHP.

Notes de sécurité

• Ne faites jamais confiance au nom de fichier original. Utilisez basename() sur $_FILES['file']['name'], ou mieux encore, générez votre propre nom sécurisé, pour éviter les traversées de chemin comme ../../config.php.
• Validez le type de fichier par son contenu réel (par exemple avec finfo / mime_content_type), et non par son extension — le client peut mentir sur l'extension comme sur le champ type.
• Stockez les fichiers téléchargés en dehors de la racine web si possible, afin que les utilisateurs ne puissent pas exécuter directement les scripts téléchargés.
• Pour une double vérification explicite qu'un chemin correspond à un fichier réellement téléchargé, consultez is_uploaded_file() — bien que move_uploaded_file() effectue déjà cette vérification en interne.

Conclusion

La fonction move_uploaded_file() est la méthode correcte et sécurisée pour déplacer un fichier téléchargé via HTTP POST depuis le répertoire temporaire de PHP vers un emplacement permanent. Elle retourne true en cas de succès et false en cas d'échec, et refuse de déplacer tout fichier qui n'a pas été réellement téléchargé. Vérifiez toujours le code d'erreur de téléchargement en premier, assainissez le nom de fichier de destination et validez le fichier avant de lui faire confiance.

Pour le flux de travail général concernant la gestion des téléchargements, consultez PHP File Upload et le reste de PHP File Handling.

Pratique