Capire la funzione PHP ftp_cdup()

Quando si automatizzano i trasferimenti di file via FTP, è spesso necessario spostarsi nell'albero delle directory remote prima di caricare, scaricare o elencare i file. L'estensione FTP integrata in PHP fornisce un piccolo insieme di funzioni di navigazione, e ftp_cdup() è quella che si sposta su di un livello — l'equivalente FTP di cd .. nella riga di comando.

Questo capitolo illustra cosa fa ftp_cdup(), la sua sintassi e il valore restituito, un esempio funzionante completo e le insidie da conoscere prima di usarla in produzione.

Cos'è ftp_cdup()?

ftp_cdup() cambia la directory di lavoro corrente sul server FTP remoto alla sua directory padre. Fa esattamente una cosa: salire di un livello. Se ci si trova in /var/www/html/uploads, chiamare ftp_cdup() una volta porta in /var/www/html.

È il corrispettivo di ftp_chdir(), che si sposta all'interno di una directory con nome. Usa ftp_chdir() per scendere o saltare a un percorso, e ftp_cdup() per tornare indietro verso la root.

ftp_cdup() influisce solo sulla directory corrente tracciata dalla sessione FTP. Non sposta, copia o elimina nulla sul server.

Sintassi

ftp_cdup(FTP\Connection $ftp): bool

Valore restituito: true in caso di successo, false in caso di errore (ad esempio, se ci si trova già nella directory root o la connessione non è autenticata).

A partire da PHP 8.1, ftp_connect() restituisce un oggetto FTP\Connection invece di una risorsa. La funzione funziona allo stesso modo; è cambiato solo il tipo.

Come usare ftp_cdup()

Prima di poter chiamare ftp_cdup(), è necessario:

1. Aprire una connessione con ftp_connect().
2. Autenticarsi con ftp_login().
3. (Di solito) passare alla modalità passiva con ftp_pasv() affinché i trasferimenti funzionino dietro NAT/firewall.

L'esempio seguente effettua il login, scende in una sotto-directory con ftp_chdir(), poi usa ftp_cdup() per risalire. Stampa la directory di lavoro prima e dopo con ftp_pwd() così da poter vedere l'effetto:

<?php

$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'username', 'password');
ftp_pasv($ftp, true);

// Move into a sub-directory first.
ftp_chdir($ftp, 'uploads');
echo "Before: " . ftp_pwd($ftp) . PHP_EOL; // e.g. /uploads

// Step back up to the parent directory.
if (ftp_cdup($ftp)) {
    echo "After:  " . ftp_pwd($ftp) . PHP_EOL; // e.g. /
} else {
    echo "Failed to change to the parent directory" . PHP_EOL;
}

ftp_close($ftp);

Qui ci colleghiamo, effettuiamo il login e abilitiamo la modalità passiva. Poi scendiamo in uploads, confermiamo la posizione con ftp_pwd(), e chiamiamo ftp_cdup() per tornare alla directory padre. Il controllo if ci permette di reagire quando lo spostamento fallisce invece di assumere che abbia avuto successo. Infine rilasciamo la connessione con ftp_close().

Insidie comuni

• Sei già alla root. Chiamare ftp_cdup() dalla cima dell'albero restituisce false. Controlla sempre il valore restituito invece di presumere il successo.
• Confonderla con un'operazione su file. ftp_cdup() cambia solo la tua posizione. Per eliminare o rinominare elementi remoti usa ftp_delete() o ftp_rename().
• Avvisi in caso di errore. Una chiamata fallita emette anche un E-WARNING. Sopprimilo o gestiscilo secondo la tua strategia di gestione degli errori, ma non fare mai affidamento sulla soppressione invece di verificare il risultato boolean.
• Dimenticare la modalità passiva. Se gli elenchi o i trasferimenti si bloccano dopo la navigazione, probabilmente hai saltato ftp_pasv($ftp, true).

Conclusione

ftp_cdup() è il più semplice strumento di navigazione nel toolkit FTP di PHP: sposta la directory corrente della sessione su di un livello e restituisce un boolean che indica se l'operazione è riuscita. Abbinala a ftp_chdir() per scendere e a ftp_pwd() per confermare dove ti trovi, e avrai tutto il necessario per navigare in modo affidabile un albero di directory remoto.

Pratica