ftp_rawlist()

Entendendo a Função PHP ftp_rawlist()

A função ftp_rawlist() retorna uma listagem detalhada de um diretório em um servidor FTP. Cada elemento do array que ela retorna é uma linha da saída bruta LIST do servidor — o mesmo texto que você veria em um cliente FTP de terminal, incluindo permissões de arquivo, proprietário, tamanho e data de modificação.

Esta página aborda o que ftp_rawlist() retorna, sua sintaxe, um exemplo funcional completo, como analisar as linhas brutas em dados utilizáveis, listagens recursivas e tratamento de erros. Se você precisar apenas dos nomes dos arquivos em um diretório, use ftp_nlist() — ela é mais simples e muito mais fácil de analisar.

O que é ftp_rawlist()?

ftp_rawlist() aceita dois parâmetros obrigatórios e um parâmetro opcional:

ftp_stream — o objeto de conexão (PHP 8.1+) ou resource retornado por ftp_connect() (ou ftp_ssl_connect()).
directory — o diretório a ser listado.
recursive (opcional) — defina como true para listar subdiretórios recursivamente.

Em caso de sucesso, retorna um array de strings, onde cada string é uma linha bruta da saída; em caso de falha (ou para um diretório vazio que não pode ser lido) retorna false.

O ponto principal a entender é que essa saída não é padronizada. É o que quer que o comando LIST do servidor emita, portanto seu formato depende do sistema operacional e da configuração do servidor. Um servidor no estilo Unix tipicamente retorna linhas que se parecem com a saída de ls -l:

drwxr-xr-x   2 owner group        4096 Jun 21 10:00 images
-rw-r--r--   1 owner group       10240 Jun 20 14:32 index.html

Servidores no estilo Windows/DOS retornam um layout completamente diferente. Por causa disso, ftp_rawlist() fornece detalhes completos ao custo de ter que analisar texto de formato livre por conta própria. Compare com:

ftp_nlist() — retorna um array simples contendo apenas os nomes dos arquivos.
ftp_mlsd() — retorna uma listagem estruturada e legível por máquina (preferível quando o servidor suporta o comando MLSD).

Sintaxe de ftp_rawlist()

A sintaxe da função ftp_rawlist() é a seguinte:

Sintaxe de ftp_rawlist()

array ftp_rawlist ( FTP\Connection|resource $ftp_stream , string $directory [, bool $recursive = false ] )

A função ftp_rawlist() recebe dois parâmetros obrigatórios, ftp_stream e directory. O parâmetro ftp_stream é o identificador de conexão retornado pela função ftp_connect(), e o parâmetro directory é o diretório a ser listado. A função também possui um parâmetro opcional, recursive, que permite especificar se os subdiretórios devem ser listados.

Uso de ftp_rawlist()

Para usar a função ftp_rawlist(), primeiro você precisa estabelecer uma conexão com o servidor FTP usando a função ftp_connect(). Veja um exemplo:

Uso de ftp_rawlist()

<?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.");
}

// Get a detailed listing of the directory
$listing = ftp_rawlist($conn, '/public_html');

// Output the listing to the console
if ($listing) {
    foreach ($listing as $item) {
        echo $item . "\n";
    }
}

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

Aqui nos conectamos com ftp_connect(), autenticamos com ftp_login(), recuperamos a listagem com ftp_rawlist(), imprimimos cada linha bruta e, por fim, liberamos a conexão com ftp_close().

Dica — modo passivo: Muitas redes e firewalls bloqueiam o canal de dados em modo ativo que ftp_rawlist() usa para buscar a listagem, fazendo com que ela trave ou retorne false. Se isso acontecer, habilite o modo passivo com ftp_pasv($conn, true) após fazer o login.

Nota de Segurança: O FTP padrão transmite credenciais e dados em texto simples. Para ambientes de produção, considere usar ftp_ssl_connect() para FTP explícito sobre TLS, ou mude para SFTP (via extensão ssh2) para transferências criptografadas.

Analisando a listagem bruta

Como cada linha é texto não estruturado, geralmente você vai querer extrair campos individuais. Para um servidor no estilo Unix, você pode dividir cada linha por espaços em branco: as permissões estão no primeiro token, o tamanho está no quinto, e o nome do arquivo é tudo após o oitavo token (o nome pode conter espaços).

Analisando uma listagem bruta no estilo Unix

<?php

// One line of typical ftp_rawlist() output:
$line = '-rw-r--r--   1 owner group       10240 Jun 20 14:32 index.html';

// Split on runs of whitespace, limited so the name stays intact.
$parts = preg_split('/\s+/', $line, 9);

$type        = $parts[0][0] === 'd' ? 'directory' : 'file';
$permissions = $parts[0];
$size        = (int) $parts[4];
$name        = $parts[8];

echo "Name:        $name\n";
echo "Type:        $type\n";
echo "Size:        $size bytes\n";
echo "Permissions: $permissions\n";
?>

Isso imprime:

Name:        index.html
Type:        file
Size:        10240 bytes
Permissions: -rw-r--r--

Se o seu servidor suportar, prefira ftp_mlsd(), que retorna esses dados já estruturados para que você possa evitar a análise frágil de strings.

Listando subdiretórios recursivamente

Passar true como terceiro argumento instrui o servidor a descer nos subdiretórios. A saída então inclui linhas em branco e cabeçalhos de diretório (um caminho seguido de dois-pontos) que separam o conteúdo de cada subdiretório — esteja pronto para pulá-los ao iterar:

<?php

// Assuming $conn is an active FTP connection
$listing = ftp_rawlist($conn, '/public_html', true);

foreach ($listing as $line) {
    if ($line === '' || str_ends_with($line, ':')) {
        // Skip blank separators and "/path/to/dir:" headers
        continue;
    }
    echo $line . "\n";
}
?>

Note que nem todo servidor FTP respeita a flag recursiva, e uma árvore profunda pode ser lenta, portanto teste contra o servidor de destino.

Tratamento de erros em ftp_rawlist()

É importante tratar erros adequadamente ao usar a função ftp_rawlist(). Se a função retornar false, significa que a operação não foi bem-sucedida. Veja um exemplo de como tratar erros:

Tratamento de erros em ftp_rawlist()

<?php

// Assuming $conn is an active FTP connection
$listing = ftp_rawlist($conn, '/public_html');

if (!$listing) {
    echo "Failed to get directory listing from FTP server.\n";
}

ftp_close($conn);
?>

Ao tratar erros adequadamente e verificar o valor de retorno da função, você pode garantir o sucesso de suas operações FTP usando a função ftp_rawlist().

Conclusão

ftp_rawlist() é a função indicada quando você precisa de metadados completos dos arquivos — permissões, proprietário, tamanho e data — de um diretório FTP, não apenas os nomes. A desvantagem é que sua saída é o texto bruto LIST do servidor, dependente do SO, portanto planeje analisá-lo (ou use o estruturado ftp_mlsd() quando disponível). Sempre verifique o valor de retorno, habilite o modo passivo quando estiver atrás de um firewall e prefira uma conexão criptografada para produção.

Funções relacionadas

ftp_nlist() — lista apenas os nomes dos arquivos
ftp_mlsd() — listagem estruturada e legível por máquina
ftp_connect() / ftp_login() — abre e autentica uma sessão
ftp_get() — baixa um arquivo após encontrá-lo
ftp_close() — fecha a conexão

Prática

Qual é a função de ftp_rawlist em PHP?

Ela exibe uma lista de arquivos em um diretório especificado.Ela fornece informações sobre um arquivo em um servidor.Ela retorna uma lista detalhada de arquivos no diretório informado em um servidor FTP.Ela busca o conteúdo de um arquivo em um servidor.