ftp_pwd()

La funzione PHP ftp_pwd() restituisce la directory di lavoro corrente di una connessione FTP aperta — l'equivalente di digitare pwd ("print working directory") in un client FTP. Questa pagina spiega cosa restituisce la funzione, come chiamarla correttamente nelle varie versioni di PHP e come si inserisce in una tipica sessione FTP.

Cosa fa ftp_pwd()

Dopo aver stabilito la connessione e aver effettuato il login su un server FTP, il server tiene traccia di una "directory corrente" per la sessione. Man mano che ci si sposta con ftp_chdir() o ftp_cdup(), tale posizione cambia. ftp_pwd() indica dove ci si trova in quel momento, restituendo il percorso assoluto come string.

Questo è particolarmente utile per:

• Logging o debug — confermare di essere atterrati nella directory prevista dopo il login.
• Salvare e ripristinare una posizione: catturare il percorso con ftp_pwd(), cambiare directory per svolgere del lavoro, quindi tornare indietro con ftp_chdir().
• Costruire percorsi per upload/download relativi alla posizione corrente del server.

Sintassi

ftp_pwd(FTP\Connection $ftp): string|false

Accetta un singolo argomento:

• $ftp — l'handle della connessione FTP restituito da ftp_connect() (o da ftp_ssl_connect()).

Restituisce la directory corrente come string in caso di successo, oppure false in caso di errore.

Nota sulla versione: In PHP 8.1 e versioni successive, la connessione è un oggetto FTP\Connection. In PHP 7.x e versioni precedenti, le funzioni FTP utilizzavano una resource al suo posto — il codice chiamante è identico, è cambiato solo il tipo di $ftp. Il codice scritto per le versioni precedenti continua a funzionare senza modifiche.

Utilizzo di base

È necessario connettersi e accedere prima di chiamare ftp_pwd():

<?php

// Open an FTP connection
$ftp = ftp_connect('ftp.example.com');

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

// Ask the server where we are
$current = ftp_pwd($ftp);

echo "Current directory: $current\n"; // e.g. "Current directory: /"

// Always close the connection when done
ftp_close($ftp);

Subito dopo il login la maggior parte dei server posiziona nella home directory dell'account, quindi la prima chiamata a ftp_pwd() restituisce comunemente / oppure qualcosa come /home/username.

Tracciare la posizione dopo aver cambiato directory

Il valore restituito da ftp_pwd() riflette ogni passo di navigazione. Combinato con ftp_chdir(), consente di confermare che uno spostamento sia andato a buon fine:

<?php

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

echo ftp_pwd($ftp) . "\n";        // /

ftp_chdir($ftp, 'public_html');
echo ftp_pwd($ftp) . "\n";        // /public_html

ftp_chdir($ftp, 'images');
echo ftp_pwd($ftp) . "\n";        // /public_html/images

ftp_close($ftp);

Salvare e ripristinare la directory di lavoro

Un pattern comune consiste nel memorizzare la posizione corrente, svolgere del lavoro altrove e poi tornare indietro:

<?php

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

// Remember the starting point
$home = ftp_pwd($ftp);

// Move into a subfolder and upload a file
ftp_chdir($ftp, 'uploads');
ftp_put($ftp, 'report.pdf', '/tmp/report.pdf', FTP_BINARY);

// Go back to where we started
ftp_chdir($ftp, $home);

ftp_close($ftp);

Gestione degli errori

ftp_pwd() restituisce false se la connessione non è valida o se il server rifiuta la richiesta. Poiché anche una string vuota è falsy, utilizzare un controllo rigoroso === false anziché !$current:

<?php

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

$current = ftp_pwd($ftp);

if ($current === false) {
    echo "Failed to get the current directory.\n";
} else {
    echo "You are in: $current\n";
}

ftp_close($ftp);

Si noti che ftp_connect() stesso restituisce false se non riesce a raggiungere l'host, quindi nel codice in produzione è opportuno verificare i risultati di connessione e login prima di chiamare ftp_pwd().

Funzioni correlate

• ftp_connect() — apre una connessione FTP.
• ftp_login() — esegue l'autenticazione sul server.
• ftp_chdir() — cambia la directory corrente.
• ftp_cdup() — si sposta nella directory padre.
• ftp_close() — chiude la connessione.
• Panoramica FTP di PHP — tutte le funzioni FTP a colpo d'occhio.

Esercitazione