Entendendo a função PHP ftp_cdup()

Ao criar scripts de transferência de arquivos via FTP, com frequência você precisa navegar pela árvore de diretórios remota antes de fazer upload, download ou listar arquivos. A extensão FTP embutida do PHP oferece um pequeno conjunto de funções de navegação, e ftp_cdup() é a responsável por subir um nível — o equivalente FTP de cd .. na linha de comando.

Este capítulo aborda o que ftp_cdup() faz, sua sintaxe e valor de retorno, um exemplo completo e funcional, além dos problemas comuns que vale conhecer antes de usá-la em produção.

O que é ftp_cdup()?

ftp_cdup() muda o diretório de trabalho atual no servidor FTP remoto para seu diretório pai. Ela faz exatamente uma coisa: subir um nível. Se você estiver em /var/www/html/uploads, chamar ftp_cdup() uma vez o leva para /var/www/html.

É a contrapartida de ftp_chdir(), que entra em um diretório específico. Use ftp_chdir() para descer ou ir a um caminho, e ftp_cdup() para voltar em direção à raiz.

ftp_cdup() afeta apenas o diretório atual rastreado pela sua sessão FTP. Ela não move, copia nem exclui nada no servidor.

Sintaxe

ftp_cdup(FTP\Connection $ftp): bool

Valor de retorno: true em caso de sucesso, false em caso de falha (por exemplo, se você já está no diretório raiz ou a conexão não está autenticada).

A partir do PHP 8.1, ftp_connect() retorna um objeto FTP\Connection em vez de um resource. A função funciona da mesma forma; apenas a indicação de tipo mudou.

Como usar ftp_cdup()

Antes de chamar ftp_cdup(), você deve:

1. Abrir uma conexão com ftp_connect().
2. Autenticar com ftp_login().
3. (Geralmente) ativar o modo passivo com ftp_pasv() para que as transferências funcionem atrás de NAT/firewalls.

O exemplo abaixo faz login, desce para um subdiretório com ftp_chdir() e então usa ftp_cdup() para voltar um nível. Ele exibe o diretório de trabalho antes e depois com ftp_pwd() para que você veja o efeito:

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

Aqui nos conectamos, fazemos login e ativamos o modo passivo. Em seguida, descemos para uploads, confirmamos a localização com ftp_pwd() e chamamos ftp_cdup() para voltar ao diretório pai. A verificação com if permite reagir quando a operação falha em vez de presumir que funcionou. Por fim, liberamos a conexão com ftp_close().

Problemas comuns

• Você já está na raiz. Chamar ftp_cdup() do topo da árvore retorna false. Sempre verifique o valor de retorno em vez de presumir sucesso.
• Confundir com uma operação de arquivo. ftp_cdup() altera apenas a sua posição. Para excluir ou renomear itens remotos, use ftp_delete() ou ftp_rename().
• Avisos em caso de falha. Uma chamada com falha também emite um E-WARNING. Suprima ou trate conforme sua estratégia de erros, mas nunca dependa da supressão em vez de verificar o resultado boolean.
• Esquecer o modo passivo. Se listagens ou transferências travarem após navegar, provavelmente você não chamou ftp_pasv($ftp, true).

Conclusão

ftp_cdup() é o auxiliar de navegação mais simples no kit de ferramentas FTP do PHP: ele move o diretório atual da sessão um nível acima e retorna um boolean indicando se funcionou. Use-a junto com ftp_chdir() para descer e ftp_pwd() para confirmar sua localização, e você terá tudo o que precisa para percorrer uma árvore de diretórios remota de forma confiável.

Prática