mkdir()

O que é a Função mkdir()?

A função mkdir() é uma função PHP nativa que cria um novo diretório no sistema de arquivos. Você a utiliza sempre que seu script precisa criar uma pasta em tempo de execução — por exemplo, para armazenar arquivos enviados, gerar diretórios de cache por usuário ou configurar uma pasta de exportação antes de gravar relatórios nela.

Esta página aborda a assinatura da função, cada parâmetro (incluindo o argumento de permissões, frequentemente mal compreendido), como criar diretórios aninhados em uma única chamada, o valor de retorno e como tratar erros, além das armadilhas comuns que costumam pegar as pessoas de surpresa.

Aqui está a sintaxe básica da função mkdir():

A sintaxe PHP de mkdir()

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

Parâmetros

Uma observação sobre permissões e umask

O valor $permissions que você passa não é aplicado literalmente. O sistema operacional subtrai o umask do processo. Por exemplo, com o umask comum 022, chamar mkdir($dir, 0777) produz um diretório com modo 0755, não 0777. Por isso, sempre passe o modo que você realmente deseja e não assuma que 0777 significa "gravável por todos" — geralmente não significa.

Por segurança, prefira 0755 (proprietário pode ler/gravar/executar, todos os outros podem ler/executar) ao invés do padrão 0777. Se você precisar de um modo exato independente do umask, chame chmod() após criar o diretório.

Como Usar a Função mkdir()?

Usar a função mkdir() é simples. Siga estas etapas:

1. Especifique o caminho do diretório que deseja criar.
2. Chame a função mkdir(), passando o caminho do diretório como primeiro parâmetro, um modo de permissões opcional como segundo parâmetro e um sinalizador booleano como terceiro parâmetro para criar diretórios pai se necessário.

Aqui está um exemplo de código que demonstra como usar a função mkdir():

Como Usar a Função mkdir()?

<?php

$dir = '/path/to/new/directory';
// 0755 is recommended for security (owner: rwx, others: rx)
$permissions = 0755;
if (!is_dir($dir)) {
    if (mkdir($dir, $permissions, true)) {
        echo "Directory created successfully!";
    } else {
        echo "Failed to create directory.";
    }
} else {
    echo "Directory already exists!";
}

Neste exemplo, usamos is_dir() para verificar se o destino já existe. Especificamos um modo de permissões mais seguro (0755) e passamos true como terceiro argumento para habilitar a criação recursiva. A função mkdir() retorna um valor booleano, então envolvemos a chamada em uma instrução if para tratar sucesso ou falha de forma adequada. Se o diretório não existir, tentamos criá-lo e exibimos uma mensagem de sucesso ou falha. Se já existir, exibimos uma mensagem indicando isso.

Criando diretórios aninhados

Sem o sinalizador recursivo, mkdir() só pode criar o último segmento de um caminho — todos os pais já devem existir. Passar true como terceiro argumento instrui o PHP a criar toda a cadeia de uma vez:

<?php

// Fails if "cache" or "cache/images" don't already exist:
// mkdir('cache/images/thumbs');           // Warning + returns false

// Works — creates cache, cache/images and cache/images/thumbs as needed:
if (mkdir('cache/images/thumbs', 0755, true)) {
    echo 'Nested directories created.';
}

Valor de retorno e tratamento de erros

mkdir() retorna true em caso de sucesso e false em caso de falha. Em caso de falha, também gera um E_WARNING — por exemplo, quando o diretório pai está ausente, o caminho já existe ou o processo não tem permissão de escrita.

Existem duas maneiras limpas de lidar com esse aviso:

<?php

// 1. Guard with is_dir() so you never try to recreate an existing folder.
$dir = 'uploads';
if (!is_dir($dir) && !mkdir($dir, 0755, true) && !is_dir($dir)) {
    // The second is_dir() guards against a race where another
    // process created the directory between our two checks.
    throw new RuntimeException("Directory \"$dir\" could not be created");
}

// 2. Suppress the warning with @ only if you immediately check the result.
if (!@mkdir($dir, 0755) && !is_dir($dir)) {
    echo 'Could not create directory.';
}

Evite usar @ sozinho sem verificar o valor de retorno — engolir silenciosamente o aviso torna as falhas invisíveis.

Armadilhas comuns

• O diretório já existe. mkdir() retorna false e emite um aviso. Sempre verifique com is_dir() primeiro, ou confie no idioma de criação recursiva acima.
• As permissões são filtradas pelo umask. Como abordado acima, o modo que você passa é mascarado. Use chmod() para um modo exato.
• Caminhos relativos dependem do diretório de trabalho. Um caminho relativo é resolvido em relação ao diretório atual do script, que pode diferir da localização do arquivo. Use um caminho absoluto (por exemplo, __DIR__ . '/uploads') quando houver dúvida.
• O Windows ignora o argumento de permissões completamente — é uma operação sem efeito lá.

Funções relacionadas

• rmdir() — remove um diretório vazio (a contraparte de mkdir()).
• scandir() — lista o conteúdo de um diretório.
• chmod() — altera as permissões de um diretório após a criação.
• fopen() — abre ou cria um arquivo quando o diretório já existe.

Conclusão

A função mkdir() é uma ferramenta útil em PHP para criar novos diretórios no sistema de arquivos. As principais coisas a lembrar são: passe um modo de permissão explícito e seguro (como 0755) em vez de depender do padrão 0777, use o sinalizador recursivo quando os diretórios pai podem estar ausentes e sempre verifique o valor de retorno booleano para que as falhas não passem despercebidas. Com esses hábitos, mkdir() se torna um bloco de construção confiável para qualquer script que trabalhe com o sistema de arquivos.

Prática