is_uploaded_file()

La funzione is_uploaded_file() verifica se un determinato file è stato caricato tramite una richiesta HTTP POST. È uno degli strumenti di sicurezza fondamentali di PHP per il caricamento di file: consente di confermare che un percorso punti davvero a un file temporaneo creato da PHP stesso dalla richiesta corrente — e non a un percorso arbitrario che un attaccante potrebbe aver inserito nel tuo script.

Questo capitolo tratta la sintassi, un esempio funzionante, il problema di sicurezza che la funzione risolve e i trabocchetti più comuni.

Sintassi

is_uploaded_file(string $filename): bool

• $filename — il percorso da verificare. In pratica è sempre un valore preso da $_FILES['...']['tmp_name'].
• Valore di ritorno — true se $filename è un file caricato dalla richiesta corrente, false altrimenti.

La funzione restituisce true solo per il nome file temporaneo assegnato da PHP durante il caricamento. Passare un percorso costruito manualmente (ad esempio la destinazione finale dopo lo spostamento del file) restituisce false.

Esempio di base

<?php

$file = $_FILES['file']['tmp_name'];

if (is_uploaded_file($file)) {
    echo 'The file was uploaded via HTTP POST.';
} else {
    echo 'The file was NOT uploaded via HTTP POST.';
}

Qui $_FILES['file'] è la voce creata quando un campo del form denominato file viene inviato con enctype="multipart/form-data". La chiave tmp_name contiene il percorso temporaneo lato server, e is_uploaded_file() ne verifica l'autenticità rispetto alla richiesta.

Perché questa funzione esiste (sicurezza)

Senza questo controllo, un attaccante potrebbe inviare un campo del form normale (non un file) il cui valore è un percorso di sistema come /etc/passwd. Se il tuo codice si fidasse ciecamente di quella stringa e la leggesse o copiasse, esporresti file di sistema. is_uploaded_file() protegge da questo scenario restituendo true solo per i file ricevuti da PHP come upload nella richiesta corrente.

Un gestore di upload sicuro valida il file prima di fare qualsiasi cosa:

<?php

if (
    isset($_FILES['file']) &&
    $_FILES['file']['error'] === UPLOAD_ERR_OK &&
    is_uploaded_file($_FILES['file']['tmp_name'])
) {
    $destination = __DIR__ . '/uploads/' . basename($_FILES['file']['name']);

    if (move_uploaded_file($_FILES['file']['tmp_name'], $destination)) {
        echo 'File stored safely.';
    } else {
        echo 'Failed to move the uploaded file.';
    }
} else {
    echo 'No valid upload received.';
}

Nota che move_uploaded_file() esegue internamente lo stesso controllo di is_uploaded_file(), quindi è il metodo preferito per spostare un upload. Usa is_uploaded_file() direttamente solo quando devi ispezionare o leggere il file temporaneo prima di spostarlo.

is_uploaded_file() vs. move_uploaded_file()

Trabocchetti comuni

• Passa sempre tmp_name, mai il percorso finale. Dopo aver spostato un file con move_uploaded_file(), il file temporaneo non esiste più, quindi verificarlo di nuovo restituisce false.
• Il controllo è per richiesta. Un percorso che era un upload in una richiesta precedente non è valido in quella corrente.
• Non valida il contenuto. is_uploaded_file() non dice nulla sul tipo o sulla dimensione del file. Valida $_FILES['file']['size'], il tipo MIME e l'estensione separatamente prima di fidarti dei dati dell'utente.
• Controlla prima il codice di errore. Verifica $_FILES['file']['error'] === UPLOAD_ERR_OK prima di chiamare is_uploaded_file(); un upload fallito potrebbe lasciare tmp_name vuoto.

Funzioni correlate

• move_uploaded_file() — sposta in modo sicuro un file caricato nella sua destinazione.
• $_FILES e altre superglobali — come i dati dei file caricati vengono esposti allo script.
• Caricamento file PHP — il form HTML completo con il gestore PHP per accettare i file.

Riepilogo

is_uploaded_file() restituisce true solo per il file temporaneo creato da PHP da un upload HTTP POST nella richiesta corrente. Combinata con il codice di errore dell'upload e la validazione del contenuto, costituisce la base della gestione sicura dei file in PHP. Nella maggior parte dei casi si lascia che move_uploaded_file() esegua il controllo al posto tuo, ricorrendo a is_uploaded_file() direttamente solo quando è necessario leggere il file temporaneo prima di spostarlo.

Pratica