ftp_put()

La funzione PHP ftp_put()

ftp_put() è una funzione PHP integrata che carica un file locale su un server FTP remoto. È la controparte per l'upload di ftp_get(), che scarica un file remoto sulla tua macchina. Questa pagina tratta la firma, le modalità di trasferimento, un flusso di lavoro completo, la gestione degli errori e le insidie più comuni in produzione.

Si utilizza ftp_put() dopo aver aperto una connessione con ftp_connect() e aver eseguito l'autenticazione con ftp_login().

Sintassi

ftp_put(
    FTP\Connection $ftp,
    string $remote_filename,
    string $local_filename,
    int $mode = FTP_BINARY
): bool

Restituisce true in caso di successo e false in caso di errore.

Nota sulla versione: Prima di PHP 8.1 il primo argomento era una resource restituita da ftp_connect(). Da PHP 8.1 è un oggetto FTP\Connection. Il codice non cambia — si passa comunque ciò che ftp_connect() restituisce — ma i controlli con is_resource() non funzionano più su di esso.

Modalità Binary vs. ASCII

Scegliere la modalità sbagliata è la causa più comune del problema "l'upload è riuscito ma il file è corrotto":

• FTP_BINARY trasferisce i byte esattamente così come sono. Usalo per tutto, per impostazione predefinita — immagini, archivi, PDF, eseguibili e persino testi in pratica.
• FTP_ASCII riscrive i terminatori di riga (\n ↔ \r\n) per adattarsi alla piattaforma di destinazione. Ha senso solo per testo semplice e distrugge silenziosamente qualsiasi file binario. In caso di dubbio, usa FTP_BINARY.

Un upload completo

Verifica sempre i valori restituiti da ogni chiamata FTP anziché dare per scontato che un passaggio sia andato a buon fine:

<?php

// 1. Open a connection (false on failure)
$ftp = ftp_connect('ftp.example.com');
if ($ftp === false) {
    exit("Could not connect to FTP server.\n");
}

// 2. Authenticate
if (!ftp_login($ftp, 'username', 'password')) {
    ftp_close($ftp);
    exit("FTP login failed.\n");
}

// 3. Behind a firewall/NAT? Passive mode is almost always required.
ftp_pasv($ftp, true);

// 4. Upload: local file -> remote path, binary mode
$ok = ftp_put($ftp, '/public_html/index.html', './build/index.html', FTP_BINARY);

echo $ok
    ? "Upload succeeded.\n"
    : "Upload failed.\n";

// 5. Always close
ftp_close($ftp);

Nota l'ordine degli argomenti: prima il percorso remoto di destinazione, poi quello locale sorgente — l'inverso di ciò che molti si aspettano. Invertirli fa sì che PHP tenti di leggere un file locale inesistente e la chiamata fallisce.

Gestione degli errori

ftp_put() restituisce false ed emette un avviso PHP in caso di errore. Trasforma questo in un risultato chiaro e gestibile invece di lasciare che un avviso indesiderato si propaghi nell'output:

<?php

$remote = '/public_html/index.html';
$local  = './build/index.html';

// Catch the "no such local file" case before touching the network.
if (!is_readable($local)) {
    exit("Local file '$local' is missing or unreadable.\n");
}

if (!ftp_put($ftp, $remote, $local, FTP_BINARY)) {
    // Common causes: wrong remote directory, no write permission,
    // disk quota exceeded, or passive mode not enabled.
    echo "Failed to upload '$local' to '$remote'.\n";
} else {
    echo "Uploaded '$local' to '$remote'.\n";
}

ftp_close($ftp);

Cause comuni di errore

• Ordine degli argomenti errato — percorso remoto e percorso locale invertiti.
• Modalità passiva non impostata — la maggior parte dei server dietro NAT richiede ftp_pasv($ftp, true) dopo il login.
• Directory remota mancante — ftp_put() non crea cartelle; usa prima ftp_mkdir().
• Permesso di scrittura assente o quota superata sul lato server.
• Modalità di trasferimento errata che corrompe un file binario (usa FTP_BINARY).

Caricamento da uno stream aperto

Se i tuoi dati sono già in un file handle aperto (o provengono da un wrapper di stream anziché da un percorso su disco), usa invece ftp_fput() — accetta una risorsa stream al posto del nome del file locale.

Conclusione

ftp_put() carica un file locale su un server FTP remoto. Ricorda le tre cose che causano la maggior parte dei problemi: passa prima il percorso remoto, mantieni FTP_BINARY a meno che tu non abbia un motivo specifico per ASCII, e controlla ogni valore restituito. Per i trasferimenti non bloccanti che non bloccano lo script, consulta ftp_nb_put().

Pratica