Criar pasta em PHP se não existir: melhores práticas 2025

«Create a folder if it doesn't already exist»: Como não reinventar a roda em 2025

Você já escreveu um script que precisava salvar arquivos e, de repente, recebeu o erro Warning: mkdir(): No such file or directory? Se sim, você não está sozinho. A questão «Create a folder if it doesn't already exist» no Stack Overflow acumulou milhares de visualizações, e por um bom motivo. Parece simples, certo? Mas, na prática, iniciantes (e até veteranos) frequentemente esbarram em armadilhas: permissões de acesso, criação recursiva e condições de corrida.

Neste artigo, vamos explorar as melhores práticas PHP para criar pastas em 2025. Você aprenderá a usar mkdir() corretamente, evitar erros comuns e escrever um código robusto que não falhe no momento mais crítico. Vamos nessa!

Por que a questão «Create a folder if it doesn't exist» é tão popular?

Todo segundo projeto web, de uma forma ou de outra, lida com arquivos: upload de avatares, geração de relatórios, cache, logs. E em todos eles, é preciso garantir que o diretório de destino exista. Se não existir, o script gera um erro, o usuário vê um «500 Internal Server Error», e você passa a madrugada caçando o bug.

O problema é que a função mkdir() do PHP não cria a pasta automaticamente se o diretório pai não existir. Muitos desenvolvedores escrevem algo como:

if (!file_exists($path)) {\n    mkdir($path);\n}\n

Isso funciona… até ocorrer uma race condition (condição de corrida). Se dois scripts verificarem a existência da pasta ao mesmo tempo e ambos tentarem criá-la, um deles falhará com erro. Em 2025, com o aumento da carga nos sites, esses bugs se tornam críticos.

A função mkdir() no PHP: análise completa

Vamos relembrar a assinatura:

mkdir(string $directory, int $permissions = 0777, bool $recursive = false, resource $context = ?): bool\n

\n
• $directory — caminho para a pasta a ser criada.
\n
• $permissions — permissões de acesso (padrão 0777, mas a máscara umask é aplicada).
\n
• $recursive — se true, cria todos os diretórios pai que estiverem faltando.
\n
• $context — contexto de fluxo (raramente usado).
\n

O segredo está no parâmetro $recursive. A maioria dos problemas é resolvida com ele. Mas vamos por partes.

Método simples: is_dir() + mkdir()

A maneira mais óbvia e correta de verificar se uma pasta existe é usar is_dir(), e não file_exists(). Por quê? Porque file_exists() retorna true também para um arquivo com o mesmo nome, o que causaria erro.

$dir = '/caminho/para/upload';\n\nif (!is_dir($dir)) {\n    mkdir($dir, 0755, true);\n}\n

Aqui nós:

\n
• Verificamos se o diretório não existe e não é um arquivo.
\n
• Criamos a pasta com permissões 0755 (dono tem acesso total, outros podem ler e executar).
\n
• Usamos true para criação recursiva — se a pasta pai /caminho/para não existir, ela também será criada.
\n

Esse método cobre 90% dos casos. Mas e se duas requisições executarem esse código ao mesmo tempo?

Proteção contra race condition (condição de corrida)

Em sistemas de alta carga, dois scripts podem tentar criar a pasta simultaneamente. Para evitar o erro, use @ (supressão de erros) ou, melhor ainda, verifique o resultado de mkdir():

$dir = '/caminho/para/cache';\n\nif (!is_dir($dir)) {\n    // Tenta criar. Se outro processo já criou a pasta, tudo bem\n    if (!mkdir($dir, 0755, true) && !is_dir($dir)) {\n        throw new \\RuntimeException('Não foi possível criar o diretório: ' . $dir);\n    }\n}\n

Essa abordagem é segura e evita que seu código quebre em cenários de concorrência.