ftp_delete()

A Função PHP ftp_delete()

ftp_delete() remove um único arquivo de um servidor FTP remoto. É o equivalente FTP de unlink() em um sistema de arquivos local: você passa uma conexão FTP aberta e o caminho do arquivo a ser removido, e ela informa se a exclusão foi bem-sucedida.

Esta página abrange a assinatura da função, o valor de retorno, um exemplo completo, o tratamento de erros e as armadilhas mais comuns (exclusão de diretórios, caminhos relativos vs. absolutos e permissões).

Sintaxe

ftp_delete(FTP\Connection $ftp, string $filename): bool

Nota: Antes do PHP 8.1, o primeiro argumento era um resource retornado por ftp_connect(). A partir do PHP 8.1, é um objeto FTP\Connection, mas o seu código não muda — você ainda passa o valor retornado por ftp_connect().

Valor de retorno

ftp_delete() retorna:

• true — o arquivo foi excluído com sucesso.
• false — a exclusão falhou (o arquivo não existe, você não tem permissão, o caminho é um diretório ou a conexão é inválida).

Como um caminho vazio válido ou qualquer falha resultam em false, sempre teste o resultado explicitamente em vez de presumir sucesso.

Um exemplo completo

Primeiro, abra uma conexão com ftp_connect(), autentique-se com ftp_login(), exclua o arquivo e, em seguida, feche a sessão com ftp_close():

<?php

// Open an FTP connection (default port 21, 90-second timeout)
$ftp = ftp_connect('ftp.example.com');

if ($ftp === false) {
    exit("Could not connect to the FTP server.\n");
}

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

// Switch to passive mode — required behind most firewalls/NAT
ftp_pasv($ftp, true);

// Attempt the delete
if (ftp_delete($ftp, '/uploads/old-report.txt')) {
    echo "File deleted successfully.\n";
} else {
    echo "Failed to delete the file.\n";
}

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

Tratamento de erros

ftp_delete() emite um aviso PHP e retorna false quando não consegue remover o arquivo. A verificação confiável é o valor de retorno boolean. Use === para que o resultado não seja confundido com um valor de conexão falso:

<?php

if (ftp_delete($ftp, '/uploads/old-report.txt') === true) {
    echo "Deleted.\n";
} else {
    echo "Delete failed — check the path, permissions, and that it is a file, not a folder.\n";
}

Se você quiser suprimir o aviso embutido e exibir sua própria mensagem, prefixe a chamada com @:

<?php

if (@ftp_delete($ftp, $remotePath) === false) {
    error_log("ftp_delete failed for: $remotePath");
}

Armadilhas comuns

• Diretórios não são arquivos. ftp_delete() remove apenas arquivos. Para excluir um diretório, use ftp_rmdir() — e o diretório deve estar vazio, portanto exclua seu conteúdo (você pode listá-lo com ftp_nlist()) antes de removê-lo.
• Caminhos relativos dependem do diretório atual. Um nome simples como report.txt é resolvido em relação ao diretório de trabalho atual do servidor. Prefira caminhos absolutos (/uploads/report.txt) ou defina o diretório explicitamente com ftp_chdir().
• Renomear em vez de excluir. Se você apenas precisa mover ou arquivar um arquivo, use ftp_rename() em vez de excluir e reenviar.
• Permissões. A exclusão falha silenciosamente (retorna false) quando o usuário FTP não tem direitos de escrita/exclusão no diretório de destino.

Resumo

ftp_delete() exclui um único arquivo em um servidor FTP remoto e retorna um boolean indicando sucesso. Abra e autentique a conexão primeiro, alterne para o modo passivo para compatibilidade, verifique o valor de retorno explicitamente e recorra a ftp_rmdir() quando precisar remover um diretório. Para o conjunto completo de operações FTP, consulte a referência FTP do PHP.

Prática