ftp_size()

La funzione PHP ftp_size()

ftp_size() è una funzione PHP integrata che interroga un server FTP per ottenere la dimensione, in byte, di un singolo file remoto. La si utilizza quando è necessario sapere quanto è grande un file senza scaricarlo — ad esempio per mostrare una barra di avanzamento, verificare se un file è cambiato dall'ultima sincronizzazione, saltare i file vuoti o accertarsi che un upload sia stato completato con la dimensione attesa.

Questa pagina illustra la firma della funzione, un esempio funzionante completo, l'insidia che colpisce quasi tutti (la modalità passiva) e come gestire i valori di ritorno speciali.

Sintassi

ftp_size(FTP\Connection $ftp, string $filename): int

Valore restituito: la dimensione del file in byte come intero in caso di successo, oppure -1 in caso di errore.

Importante: ftp_size() restituisce l'intero -1 in caso di fallimento — non restituisce false. Questo comportamento è diverso da quello della maggior parte delle altre funzioni FTP, quindi confronta sempre il risultato con -1, non con false.

Prima di PHP 8.1 l'argomento $ftp era una resource; da PHP 8.1 in poi è un object FTP\Connection. Il codice non cambia — cambia solo il tipo sottostante.

Utilizzo di base

Per chiamare ftp_size() devi prima aprire una connessione con ftp_connect() e autenticarti con ftp_login():

<?php

// Open a connection to the FTP server
$conn = ftp_connect('ftp.example.com');

// Log in with your credentials
ftp_login($conn, 'username', 'password');

// Turn on passive mode (see the note below — this is almost always required)
ftp_pasv($conn, true);

// Ask the server how big the file is
$size = ftp_size($conn, '/public_html/index.php');

if ($size !== -1) {
    echo "The file is {$size} bytes.";
} else {
    echo "Could not determine the file size.";
}

// Always close the connection when you are done
ftp_close($conn);

Modalità passiva: l'insidia più comune

Se ftp_size() continua a restituire -1 anche se il file esiste chiaramente, la causa è solitamente la modalità attiva vs. passiva, non un errore di battitura nel percorso. Dietro un firewall o un NAT (come la maggior parte dei server odierni), il server FTP non riesce ad aprire un canale dati verso il tuo client, quindi il comando SIZE sottostante si blocca.

Chiama ftp_pasv() dopo aver effettuato il login per passare alla modalità passiva, dove è il client a iniziare ogni connessione:

<?php
ftp_login($conn, 'username', 'password');
ftp_pasv($conn, true); // do this before ftp_size(), ftp_get(), ftp_nlist(), etc.

La modalità di trasferimento influisce sul risultato

La dimensione che un server FTP riporta può dipendere dalla modalità di trasferimento corrente. In modalità ASCII alcuni server traducono i terminatori di riga, quindi la dimensione riportata potrebbe non corrispondere al numero di byte ottenuto in modalità binaria. Per dimensioni accurate byte per byte, assicurati di essere in modalità binaria (FTP_BINARY), che è la modalità predefinita per le query di dimensione sulla maggior parte dei server e quella che quasi sempre si vuole usare per i file non testuali.

Gestione robusta degli errori

Poiché ftp_size() segnala il fallimento con -1, un wrapper affidabile verifica proprio quel valore specifico e avvisa quando la dimensione è sconosciuta:

<?php

function remoteFileSize($conn, string $path): ?int
{
    $size = ftp_size($conn, $path);

    if ($size === -1) {
        // The file is missing, the path is wrong, or the SIZE command failed.
        return null;
    }

    return $size;
}

$size = remoteFileSize($conn, '/public_html/index.php');

echo $size === null
    ? "File not found or size unavailable.\n"
    : "Size: {$size} bytes\n";

Usare null per il caso di fallimento evita che -1 si propaghi nei calcoli successivi (dove corromperebbe silenziosamente i totali).

Ottenere le dimensioni di molti file

ftp_size() opera su un percorso alla volta. Per riportare le dimensioni di un'intera directory, combinala con ftp_nlist(), che restituisce un array di nomi di file:

<?php

$files = ftp_nlist($conn, '/public_html');

if ($files !== false) {
    foreach ($files as $file) {
        $size = ftp_size($conn, $file);
        $label = $size === -1 ? 'directory or unreadable' : "{$size} bytes";
        echo "{$file}: {$label}\n";
    }
}

Nota che ftp_size() restituisce -1 per le directory, il che è un modo comodo per distinguere file e cartelle in un elenco.

Funzioni correlate

• ftp_connect() — apre la connessione da passare a ftp_size().
• ftp_login() — autentica prima di qualsiasi query sulla dimensione.
• ftp_pasv() — abilita la modalità passiva in modo che ftp_size() funzioni correttamente.
• ftp_nlist() — elenca una directory per ottenere le dimensioni di molti file in un ciclo.
• ftp_get() — scarica un file una volta che ne conosci la dimensione.
• ftp_close() — chiude la connessione al termine.
• Panoramica FTP di PHP — tutte le funzioni FTP in un unico posto.

Conclusione

ftp_size() è il modo più rapido per conoscere la dimensione in byte di un file remoto senza trasferirlo. Ricorda le due regole che la rendono affidabile: abilita la modalità passiva con ftp_pasv() dopo il login, e verifica il risultato confrontandolo con -1 (non con false) per rilevare errori e directory.

Pratica