move_uploaded_file()

Cos'è la funzione move_uploaded_file()?

La funzione move_uploaded_file() è una funzione PHP integrata che sposta un file caricato tramite un modulo HTML in una posizione permanente sul server. Quando un browser carica un file, PHP lo memorizza prima in una directory temporanea con un nome casuale. Quel file temporaneo viene eliminato automaticamente al termine dello script, quindi è necessario spostarlo in un posto permanente se si vuole conservarlo — è esattamente a questo che serve move_uploaded_file().

Ciò che rende questa funzione speciale è il suo controllo di sicurezza integrato. Sposta un file solo se PHP conferma che è stato genuinamente caricato tramite una richiesta HTTP POST. Questo impedisce a un attaccante di ingannare lo script facendogli spostare un file sensibile del server (come /etc/passwd) fornendone il percorso. Per questo motivo si dovrebbe sempre usare move_uploaded_file() invece di copy() o rename() per gestire i caricamenti.

Questa pagina tratta la sintassi, i parametri, il valore restituito, un esempio funzionante completo, i codici di errore di caricamento da verificare e i problemi di sicurezza a cui prestare attenzione.

Sintassi

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

Valore restituito

move_uploaded_file() restituisce true se il file è stato spostato correttamente. Restituisce false se $from non è un file caricato valido (ad esempio, se il percorso è stato contraffatto) oppure se lo spostamento stesso fallisce — tipicamente per una directory di destinazione mancante o permessi di scrittura insufficienti. Nel caso di file contraffatto, PHP emette anche un avviso e nessuno spostamento viene eseguito.

Come usare la funzione move_uploaded_file()?

Utilizzare la funzione move_uploaded_file() è semplice. Ecco i passaggi da seguire:

1. Verificare che il caricamento del file sia riuscito controllando $_FILES['file']['error'].
2. Specificare il percorso di destinazione per il file.
3. Chiamare la funzione move_uploaded_file(), passando il nome file temporaneo e il percorso di destinazione.

Ecco un esempio di codice che mostra come usare la funzione move_uploaded_file():

Come usare la funzione 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.";
}

In questo esempio, verifichiamo prima che il caricamento sia riuscito usando $_FILES['file']['error']. Specifichiamo quindi il percorso di destinazione per il file e usiamo basename() per estrarre in modo sicuro il nome del file ed evitare vulnerabilità di path traversal. Infine, usiamo la funzione move_uploaded_file() per spostare il file caricato nella nuova posizione. Se il file viene spostato correttamente, stampiamo un messaggio di successo. In caso di errore durante lo spostamento, stampiamo un messaggio di errore.

Il modulo HTML corrispondente deve usare method="post" e enctype="multipart/form-data", altrimenti $_FILES sarà vuoto:

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

L'attributo name dell'input file (file in questo caso) è la chiave che si legge da $_FILES.

Codici di errore di caricamento

Il valore $_FILES['file']['error'] indica se e perché un caricamento è fallito. Verificarlo sempre prima di spostare il file. I codici più comuni sono:

Due impostazioni del server causano frequentemente errori silenziosi: upload_max_filesize e post_max_size. Se il file caricato è più grande di uno dei due limiti, $_FILES potrebbe arrivare vuoto o con un codice di errore, indipendentemente dalla correttezza del codice PHP.

Note sulla sicurezza

• Non fidarsi mai del nome file originale. Usare basename() su $_FILES['file']['name'], o meglio, generare un nome sicuro personalizzato, per evitare path traversal come ../../config.php.
• Validare il tipo di file in base al suo contenuto effettivo (ad esempio con finfo / mime_content_type), non solo in base all'estensione — il client può mentire sia sull'estensione che sul campo type.
• Conservare i file caricati al di fuori della web root quando possibile, in modo che gli utenti non possano eseguire direttamente gli script caricati.
• Per un doppio controllo esplicito che un percorso sia un file genuinamente caricato, vedere is_uploaded_file() — anche se move_uploaded_file() esegue già questa verifica internamente.

Conclusione

La funzione move_uploaded_file() è il modo corretto e sicuro per spostare un file caricato tramite HTTP POST dalla directory temporanea di PHP in una posizione permanente. Restituisce true in caso di successo e false in caso di fallimento, e si rifiuta di spostare qualsiasi file che non sia stato genuinamente caricato. Verificare sempre prima il codice di errore di caricamento, sanificare il nome del file di destinazione e validare il file prima di considerarlo attendibile.

Per il flusso di lavoro più ampio relativo alla gestione dei caricamenti, vedere PHP File Upload e il resto di PHP File Handling.

Pratica