ftp_nlist()

A Função PHP ftp_nlist()

ftp_nlist() retorna um array simples com os nomes dos arquivos e subdiretórios dentro de um diretório em um servidor FTP. É o equivalente FTP de executar o comando nls/ls — você obtém apenas os nomes, sem informações de tamanho, permissão ou data.

Esta página aborda a sintaxe e os parâmetros, um exemplo completo e funcional, como é o valor de retorno, como lidar com falhas, as armadilhas que pegam as pessoas de surpresa (modo passivo, nomes sem prefixo de caminho) e quando usar ftp_rawlist() em vez disso.

Sintaxe

ftp_nlist(FTP\Connection $ftp, string $directory): array|false

Valor de retorno: um array de nomes em caso de sucesso, ou false em caso de falha.

Os nomes retornados não incluem o prefixo do diretório — listar /public_html/ fornece index.php, não /public_html/index.php. Se o diretório estiver vazio, você obtém um array vazio [], que não é o mesmo que false.

Um Exemplo Completo

Antes de poder listar qualquer coisa, você precisa de uma conexão aberta e autenticada. O fluxo típico é ftp_connect() → ftp_login() → ftp_pasv() → ftp_nlist() → ftp_close():

Uso de ftp_nlist()

<?php

// Set up an FTP connection
$conn = ftp_connect('ftp.example.com');
if (!$conn) {
    die('Could not connect to FTP server.');
}

// Login with your FTP credentials
if (!ftp_login($conn, 'username', 'password')) {
    die('Login failed.');
}

// Enable passive mode (often required for directory listings)
ftp_pasv($conn, true);

// Get an array of filenames in the specified directory
$files = ftp_nlist($conn, '/public_html/');

// Output the array of filenames
print_r($files);

// Close the FTP connection
ftp_close($conn);

Cada etapa é verificada: saímos se a conexão ou o login falhar. Habilitar o modo passivo com ftp_pasv() é importante — muitos servidores (e a maioria dos firewalls) exigem isso antes que uma listagem de diretório seja bem-sucedida, portanto, uma chamada ausente de ftp_pasv() é a razão mais comum pela qual ftp_nlist() silenciosamente retorna false.

Para um diretório contendo dois arquivos, print_r() produziria algo como:

Array
(
    [0] => index.php
    [1] => style.css
)

ftp_nlist() vs ftp_rawlist()

Use a função que corresponde ao que você precisa:

• ftp_nlist() retorna apenas um array de nomes — perfeito para "este arquivo existe?" ou para iterar sobre downloads.
• ftp_rawlist() retorna a saída LIST bruta e não analisada (uma string por linha, como ls -l), que inclui tamanhos, permissões e datas — útil quando você precisa desses metadados e está disposto a analisá-los.

Se você precisar apenas de nomes, prefira ftp_nlist(): sua saída é consistente entre servidores, enquanto o formato de ftp_rawlist() varia de acordo com o tipo de servidor FTP.

Tratamento de Erros

É importante tratar os erros corretamente ao usar a função ftp_nlist(). Se a função retornar false, significa que a listagem não foi bem-sucedida. Observe que um diretório vazio retorna um array vazio [], não false. Aqui está um exemplo de como tratar os erros:

Tratamento de erros em ftp_nlist()

<?php

// $conn is assumed to be established from the previous example
$file_list = ftp_nlist($conn, '/public_html/');

if ($file_list === false) {
    echo "Failed to list directory on remote server.\n";
}

ftp_close($conn);

Sempre compare com === (igualdade estrita). Usar um if (!$file_list) solto trataria um diretório legitimamente vazio ([]) como um erro, já que um array vazio é falso em PHP.

Armadilhas Comuns

• Esquecer o modo passivo. Chame ftp_pasv($conn, true) após o login se as listagens retornarem false.
• Array vazio vs false. [] significa "o diretório existe, mas está vazio"; false significa que a listagem falhou. Diferencie-os com ===.
• Nomes sem caminho. Prefixe o diretório você mesmo quando precisar de um caminho completo: $dir . '/' . $name.
• Arquivos ocultos. Alguns servidores omitem arquivos com ponto (.htaccess) de ftp_nlist(). Passe -a via argumento de diretório (ex.: '-a /public_html/') em servidores que suportam isso.

Conclusão

ftp_nlist() é a maneira mais simples de obter os nomes dos arquivos em um diretório remoto. Combine-o com ftp_pasv() para confiabilidade, verifique o valor de retorno com === e use ftp_rawlist() quando você também precisar de metadados de arquivo. Para o fluxo completo de FTP, consulte a visão geral de PHP FTP.

Prática