ftp_pwd()

A função PHP ftp_pwd() retorna o diretório de trabalho atual de uma conexão FTP aberta — equivalente a digitar pwd ("print working directory") em um cliente FTP. Esta página explica o que a função retorna, como chamá-la corretamente nas diferentes versões do PHP e como ela se encaixa em uma sessão FTP típica.

O que ftp_pwd() faz

Após conectar e fazer login em um servidor FTP, o servidor mantém o controle de um "diretório atual" para a sua sessão. À medida que você navega com ftp_chdir() ou ftp_cdup(), essa localização muda. O ftp_pwd() informa onde você está atualmente, retornando o caminho absoluto como uma string.

Isso é especialmente útil para:

• Registro ou depuração — confirmar que você chegou ao diretório esperado após o login.
• Salvar e restaurar uma localização: capture o caminho com ftp_pwd(), mude de diretório para realizar algum trabalho e, em seguida, use ftp_chdir() para voltar.
• Construir caminhos para uploads/downloads relativos à localização atual do servidor.

Sintaxe

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

Ela recebe um único argumento:

• $ftp — o identificador de conexão FTP retornado por ftp_connect() (ou ftp_ssl_connect()).

Ela retorna o diretório atual como uma string em caso de sucesso, ou false em caso de falha.

Nota de versão: No PHP 8.1 e versões posteriores, a conexão é um objeto FTP\Connection. No PHP 7.x e anteriores, as funções FTP usavam um resource — o código de chamada é idêntico, apenas o tipo de $ftp mudou. O código escrito para versões antigas continua funcionando sem modificação.

Uso básico

Você deve conectar e fazer login antes de chamar 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);

Logo após o login, a maioria dos servidores coloca você no diretório home da conta, portanto a primeira chamada a ftp_pwd() geralmente retorna / ou algo como /home/username.

Rastreando sua localização após mudar de diretório

O valor retornado por ftp_pwd() reflete cada etapa de navegação. Combinado com ftp_chdir(), ele permite confirmar que uma movimentação foi bem-sucedida:

<?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);

Salvando e restaurando o diretório de trabalho

Um padrão comum é lembrar onde você está, realizar trabalho em outro lugar e depois retornar:

<?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);

Tratamento de erros

O ftp_pwd() retorna false se a conexão for inválida ou o servidor rejeitar a solicitação. Como uma string vazia também é falsy, use uma verificação estrita === false em vez de !$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);

Observe que o ftp_connect() em si retorna false se não conseguir alcançar o host, portanto, em código de produção, você deve verificar os resultados da conexão e do login antes de chamar ftp_pwd().

Funções relacionadas

• ftp_connect() — abre uma conexão FTP.
• ftp_login() — autentica no servidor.
• ftp_chdir() — muda o diretório atual.
• ftp_cdup() — sobe para o diretório pai.
• ftp_close() — fecha a conexão.
• Visão geral do FTP em PHP — todas as funções FTP de relance.

Prática