Criar pasta em PHP se ela não existir: 5 melhores maneiras em 2025

Criar pasta em PHP se ela não existir: a evolução de uma questão

Se você já escreveu um script que faz upload de arquivos, salva cache ou gera relatórios, certamente já se deparou com a situação: "Mas a pasta não existe!". Um erro que derruba todo o script, e o usuário vê uma tela branca ou (pior ainda) um erro PHP incompreensível.

A pergunta "Create a folder if it doesn't already exist" no Stack Overflow acumula milhares de visualizações. E não é à toa. Parece simples, não? Mas o diabo, como sempre, está nos detalhes: permissões de acesso, recursão, tratamento de exceções, codificação do nome da pasta. Em 2025, com projetos cada vez mais complexos e requisitos de segurança mais rigorosos, a criação correta de diretórios é a base que todo desenvolvedor PHP precisa conhecer.

Neste artigo, vamos abordar as 5 melhores práticas para criar uma pasta em PHP se ela não existir. Desde uma solução simples para iniciantes até um código robusto com proteção contra race condition. Vamos lá!

Por que apenas mkdir() é ruim? (a história de um erro)

No início, muitos escrevem assim:

<?php\nmkdir('/caminho/para/minha/pasta');\n?>

E recebem:

\n
• Warning: mkdir(): No such file or directory — se a pasta pai não existir.
\n
• Warning: mkdir(): File exists — se a pasta já existir.
\n

Ambos os avisos não são apenas "texto amarelo". Em modo de produção, podem se transformar em erros fatais se o modo estrito de relatório de erros estiver ativado. Além disso, é uma brecha de segurança: um invasor pode criar uma pasta com o mesmo nome antes do seu script (race condition).

Portanto, a abordagem moderna é sempre verificação, recursão e controle de permissões.

Método 1: Clássico com is_dir() e mkdir() (para iniciantes)

A maneira mais simples e clara é primeiro verificar se a pasta existe e depois criá-la.

<?php\n$pasta = '/var/www/uploads/images';\n\nif (!is_dir($pasta)) {\n    mkdir($pasta, 0755, true);\n    echo "Pasta criada!";\n} else {\n    echo "A pasta já existe.";\n}\n?>

O que é importante aqui:

\n
• is_dir() — retorna true se o caminho existir e for um diretório.
\n
• mkdir($pasta, 0755, true) — o terceiro parâmetro true ativa a criação recursiva. Se a pasta pai não existir, o PHP criará toda a cadeia (/var/www/uploads/images → criará uploads, depois images).
\n
• 0755 — permissões de acesso: o proprietário pode tudo, os demais podem ler e executar.
\n

Desvantagem: este código não é protegido contra race condition. Se duas requisições verificarem is_dir() ao mesmo tempo e ambas tentarem criar a pasta, a segunda gerará um aviso.

Método 2: Abordagem robusta com @mkdir() e verificação de erros

Desenvolvedores experientes costumam usar o operador de supressão de erros @ e depois verificam explicitamente o resultado.

<?php\n$pasta = '/var/www/uploads/images';\n\nif (!is_dir($pasta)) {\n    // Suprime o warning se a pasta já existir\n    if (!@mkdir($pasta, 0755, true) && !is_dir($pasta)) {\n        throw new \\RuntimeException('Não foi possível criar a pasta: ' . $pasta);\n    }\n}\n?>

Por que isso é melhor?

\n
• Suprimimos o warning, mas não ignoramos o erro — se não for possível criar, uma exceção é lançada.
\n
• A dupla verificação !is_dir($pasta) após mkdir() protege contra race condition: se outro processo criou a pasta entre nossa verificação e a chamada de mkdir(), não falhamos.
\n

Atenção: o operador @ reduz a performance, pois o PHP ainda gera o erro, mas o oculta. Em projetos de alta carga, é melhor usar o método 3.