Formulário de contato

Nome

E-mail *

Mensagem *

Imagem
CanalQbCanalQb julho 19, 2019

PHP: Como Listar Arquivos e Pastas em Diretórios de Forma Simples

PHP: Como Listar Arquivos e Pastas em Diretórios de Forma Simples

Publicado por em

@CanalQb no YouTube

@CanalQb

PHP: Listar Arquivos e Pastas no Servidor

ℹ️ Nota Técnica: Os scripts apresentados neste post são para fins educacionais. Teste sempre em ambiente isolado antes de usar em produção. Nunca exponha listagem de diretórios em servidores públicos sem autenticação — veja as dicas de segurança ao longo do post.
📂 Script PHP

Listar arquivos e pastas em PHP é uma daquelas tarefas que parece simples na teoria — mas na prática, muita gente trava na hora de escolher a função certa. opendir ou glob? scandir ou DirectoryIterator? Cada uma tem um caso de uso diferente, e saber quando usar cada abordagem economiza horas de depuração. Neste tutorial, você vai ver scripts PHP prontos para listar arquivos e pastas no servidor, com explicação real de como cada um funciona, os erros mais comuns e como evitá-los.

Já precisei desses scripts várias vezes — desde painéis simples de download até gerenciadores de backup em VPS. O que aprendi na prática está tudo aqui.

Por que dominar listagem de diretórios em PHP?

Funciona em qualquer servidor Linux

Os scripts usam funções nativas do PHP — sem dependências externas, sem instalar nada. Funciona no shared hosting mais básico ou numa VPS com Ubuntu.

Base para gerenciadores de arquivos

Todo painel de administração de arquivos começa com a leitura do diretório. Entender isso fundo é o pré-requisito para construir qualquer sistema mais elaborado.

Filtro por tipo de arquivo

Com glob(), você filtra por extensão direto na chamada da função: apenas .php, apenas .txt, apenas .log — sem iterar sobre tudo e depois filtrar na mão.

Controle total sobre o que é exibido

Ao listar arquivos via script próprio, você decide exatamente o que aparece — ocultando arquivos de configuração, pastas sensíveis e arquivos do sistema sem depender do servidor web.

Facilita auditoria e manutenção

Saber o que existe dentro de uma pasta de upload, de backup ou de logs é essencial para manter o servidor organizado. Um script simples de listagem já resolve isso durante a manutenção.

Ponto de partida para automação

Listar arquivos é o primeiro passo de automações como: renomeação em lote, compactação automática, envio por e-mail, sincronização com FTP ou processamento de CSVs de uma pasta.

Como funciona na prática

PHP abre o ponteiro do diretório

Usando opendir() ou glob(), o PHP solicita ao sistema operacional um ponteiro para o diretório informado. A partir daí, ele consegue ler o conteúdo entrada por entrada. É como abrir uma pasta no explorador de arquivos, só que via código.

Iteração e filtragem dos itens

O script percorre cada item retornado, ignorando as entradas especiais . e .. (que representam o diretório atual e o diretório pai). Com verificações como is_dir() e is_file(), você decide se quer mostrar pastas, arquivos ou ambos.

Exibição e fechamento do ponteiro

Os itens são renderizados como HTML — links, listas, tabelas ou cards, conforme seu layout. Após percorrer tudo, o ponteiro é fechado com closedir() para liberar recursos do servidor. Esse detalhe faz diferença em scripts que rodam com frequência.

Para quem é este conteúdo

🎓 Iniciantes em PHP Aprendendo as funções básicas de sistema de arquivos — opendir, readdir, glob — com exemplos diretos e comentados.
🖥️ Administradores de servidor Precisam de um script rápido para auditar pastas de upload, log ou backup sem precisar de um painel completo de FTP.
🛠️ Desenvolvedores de painéis admin Construindo sistemas internos que precisam navegar e listar estruturas de diretórios com controle total sobre o que é exibido e como.
🤖 Criadores de scripts de automação Usando a listagem de arquivos como base para processar, renomear, mover ou compactar conteúdo automaticamente via PHP CLI ou cron job.

Scripts PHP prontos — listar arquivos e pastas

Testei todos esses scripts em servidores com PHP 7.4+ e PHP 8.x. O resultado foi consistente. Veja cada abordagem, quando usar e onde cada uma se destaca.

1. Listar tudo com opendir() — o clássico

Essa é a abordagem mais antiga e compatível. Funciona desde o PHP 4 e está presente em qualquer versão que você possa encontrar num servidor legado. O fluxo é simples: abre, lê em loop, fecha.

script_listar_tudo.php PHP 
// Lista todos os arquivos e pastas do diretório atual
<?php
$diretorio = "."; // Altere para o caminho desejado

if ($handle = opendir($diretorio)) {
    echo "<ul>";
    while (false !== ($item = readdir($handle))) {
        if ($item != "." && $item != "..") {
            $tipo = is_dir($diretorio . "/" . $item) ? "📁 " : "📄 ";
            echo "<li>" . $tipo
               . "<a href='" . htmlspecialchars($item) . "'"
               . " title='" . htmlspecialchars($item) . "'"
               . " target='_blank' rel='noopener noreferrer'>"
               . htmlspecialchars($item)
               . "</a></li>";
        }
    }
    echo "</ul>";
    closedir($handle);
} else {
    echo "Erro: não foi possível abrir o diretório.";
}
?>
💡 Melhoria importante em relação ao script original: Note o uso de htmlspecialchars() em todos os valores antes de inserir no HTML. Sem isso, um nome de arquivo com <, > ou aspas pode quebrar o layout ou criar brechas XSS. É um detalhe pequeno com impacto enorme.

2. Listar apenas pastas com glob()

Quando você só quer os diretórios — sem arquivos no meio — o glob() com a flag GLOB_ONLYDIR é muito mais direto. Sem loop de verificação manual, sem is_dir() dentro do while. A filtragem acontece na própria chamada da função.

script_listar_pastas.php PHP 
// Lista apenas os subdiretórios do caminho especificado
<?php
$dir = "./"; // Altere conforme necessário

$pastas = glob($dir . "*", GLOB_ONLYDIR);

if (!empty($pastas)) {
    echo "<ul>";
    foreach ($pastas as $pasta) {
        $nome = basename($pasta); // Exibe só o nome, sem o caminho
        echo "<li>📁 "
           . "<a href='" . htmlspecialchars($pasta) . "'"
           . " title='" . htmlspecialchars($nome) . "'"
           . " target='_blank' rel='noopener noreferrer'>"
           . htmlspecialchars($nome)
           . "</a></li>";
    }
    echo "</ul>";
} else {
    echo "Nenhum diretório encontrado.";
}
?>

3. Filtrar por extensão com glob() — bônus prático

Esse script não estava no conteúdo original, mas é o que mais uso no dia a dia. Quando você tem uma pasta de uploads com mil arquivos e quer listar apenas os .pdf ou os .csv, o glob() resolve com uma linha.

script_listar_por_extensao.php PHP 
// Lista apenas arquivos .php — troque a extensão conforme precisar
<?php
$dir       = "./";
$extensao  = "php"; // "pdf", "txt", "csv", "jpg" etc.

$arquivos = glob($dir . "*." . $extensao);

if (!empty($arquivos)) {
    echo "<ul>";
    foreach ($arquivos as $arquivo) {
        $nome    = basename($arquivo);
        $tamanho = round(filesize($arquivo) / 1024, 2); // em KB
        echo "<li>📄 "
           . "<a href='" . htmlspecialchars($arquivo) . "'"
           . " target='_blank' rel='noopener noreferrer'>"
           . htmlspecialchars($nome)
           . "</a> <small>(" . $tamanho . " KB)</small></li>";
    }
    echo "</ul>";
} else {
    echo "Nenhum arquivo ." . htmlspecialchars($extensao) . " encontrado.";
}
?>
✅ Diferencial prático: Esse script já exibe o tamanho do arquivo em KB. Em sistemas de download ou painéis de backup, esse dado faz muita diferença para o usuário decidir o que baixar ou deletar.

4. Integrando o script num template HTML

A forma mais limpa de usar esses scripts é separar a lógica PHP do HTML. Você cria o arquivo PHP com a função de listagem e inclui onde precisar. Assim, qualquer alteração no script não exige mexer no template.

template_com_inclusao.php PHP + HTML 
<!DOCTYPE html>
<html lang="pt-BR">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Gerenciador de Arquivos</title>
</head>
<body>

  <div class="listagem">
    <h2>Arquivos e Pastas do Servidor</h2>
    <ul>
      <?php include("script_listar_tudo.php"); ?>
    </ul>
  </div>

</body>
</html>

Erros comuns — e o que realmente acontece

Esses são os problemas que mais aparecem quando alguém usa esses scripts pela primeira vez. Já cometi todos.

⚠️ Erro #1 — Exibir o caminho completo em vez do nome do arquivo: O glob() retorna o caminho completo (./pasta/arquivo.php). Se você exibir direto no link sem usar basename(), o visual fica feio e inconsistente. Sempre use basename($item) para exibição.
⚠️ Erro #2 — Não escapar o nome dos arquivos no HTML: Sem htmlspecialchars(), um arquivo chamado teste<script>.php pode causar XSS. É raro num servidor controlado, mas em pastas de upload é um risco real.
⚠️ Erro #3 — Esquecer o closedir(): Parece detalhe, mas em scripts executados via cron com muita frequência, acumular descritores de arquivo abertos pode causar erros de sistema. Sempre feche.
🛡️ Segurança — nunca exponha este script publicamente sem autenticação: Um script de listagem sem proteção vira um mapa do seu servidor para qualquer visitante. Se for usar em ambiente web, coloque autenticação HTTP ou restrinja por IP no .htaccess.

📚 Recursos e Documentação Oficial

php.net — opendir() — Documentação oficial com exemplos e notas de compatibilidade por versão.
php.net — glob() — Todas as flags disponíveis (GLOB_ONLYDIR, GLOB_BRACE, GLOB_NOSORT) com exemplos.
php.net — scandir() — Alternativa moderna ao opendir+readdir. Retorna array direto, mais prático para quem já conhece array_filter().
php.net — DirectoryIterator — A abordagem orientada a objetos (SPL). Mais verbosa, mas muito mais flexível para projetos maiores.
▶ Inscreva-se no @CanalQb 📂 Mais tutoriais PHP
ℹ️ Aviso Técnico: Scripts fornecidos neste post são para fins educacionais. Teste sempre em ambiente seguro e isolado antes de usar em produção. O autor não se responsabiliza por danos causados por uso indevido, exposição de dados ou falhas de segurança decorrentes da implementação sem as devidas precauções.

@CanalQb  ·  canalqb.com.br

#PHP #ListagemDeArquivos #DesenvolvimentoWeb #ServidorLinux #ScriptPHP

Marcadores: Airdrop Blogger IA Script Sistemas Tutorial

© julho 19, 2019 CanalQb — Python, Scripts, Automação, Airdrops e Criptomoedas | Web3 e Tech na Prática

Tags:

Comentários

Comente só assim vamos crescer juntos!