umask()

Introdução

Em PHP, a função umask() define as permissões padrão para arquivos e diretórios recém-criados. É uma ferramenta útil para gerenciar o acesso a arquivos em seus scripts. Neste artigo, abordaremos tudo o que você precisa saber sobre umask(), incluindo sua sintaxe, parâmetros e exemplos práticos.

Entendendo a Função umask()

O umask (máscara de modo de criação de arquivo do usuário) é um conjunto de bits de permissão que o sistema operacional remove das permissões padrão sempre que um processo cria um arquivo ou diretório. A função umask() lê ou altera essa máscara para o processo PHP atual.

• Ela aceita um parâmetro opcional $mask. Se chamada sem argumentos, retorna a máscara atual sem alterar nada.
• Quando uma máscara é fornecida, ela se torna a nova máscara e a função retorna o valor da máscara anterior.
• A máscara se aplica a todo o processo PHP, não apenas ao script atual — portanto, alterá-la pode afetar operações de arquivo posteriores na mesma requisição.

O PHP parte das permissões base do sistema — tipicamente 0666 para arquivos (leitura + escrita, sem execução) e 0777 para diretórios — e calcula as permissões finais com um AND bit a bit contra a máscara invertida:

final = base & ~mask

Como Funciona a Matemática da Máscara

A máscara limpa os bits que contém. Cada dígito octal corresponde a proprietário, grupo e outros, e cada dígito é a soma de leitura (4), escrita (2) e execução (1).

Com umask(022):

files:        0666 & ~022 = 0666 & 0755 = 0644   (rw-r--r--)
directories:  0777 & ~022 = 0777 & 0755 = 0755   (rwxr-xr-x)

O 2 nas posições de grupo e outros remove o bit de escrita, portanto grupo e outros podem ler, mas não escrever. Um umask(077) mais restritivo limparia todas as permissões de grupo/outros, resultando em 0600 para arquivos e 0700 para diretórios — arquivos acessíveis apenas pelo proprietário.

Sintaxe da Função umask()

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

umask($mask);

Aqui, $mask é a nova máscara. Deve ser especificada em notação octal, portanto sempre escreva-a com um zero inicial (por exemplo, 022). Escrever 22 seria interpretado como o valor decimal 22, não a máscara octal pretendida.

Exemplos de Uso do umask()

Exemplo 1: Definindo as Permissões Padrão para Novos Arquivos

<?php

umask(022);
$file_handle = fopen('example.txt', 'w');
fclose($file_handle);
echo 'File permissions: ' . decoct(fileperms('example.txt') & 0777);
unlink('example.txt');

Saída:

File permissions: 644

Isso define a máscara como 022, depois cria example.txt. A permissão base do arquivo 0666 menos os bits de escrita mascarados resulta em 0644. A chamada fileperms() lê as permissões reais de volta, e & 0777 remove os bits de tipo de arquivo para que decoct() imprima apenas a parte de acesso.

Exemplo 2: Lendo e Restaurando a Máscara Atual

Como a máscara afeta todo o processo, uma função bem-comportada deve restaurá-la quando terminar. Chamar umask() sem argumento retorna o valor atual sem alterá-lo.

<?php

// Save the current mask, then apply a strict one
$old = umask(077);

$dir = sys_get_temp_dir() . '/private';
mkdir($dir);
echo 'Dir permissions: ' . decoct(fileperms($dir) & 0777) . "\n";

// Restore the original mask
umask($old);
echo 'Restored mask: ' . decoct(umask()) . "\n";

rmdir($dir);

Saída:

Dir permissions: 700
Restored mask: 22

Aqui umask(077) limpa todos os bits de grupo e outros, então o novo diretório recebe 0777 & ~077 = 0700 — acessível apenas pelo proprietário. Salvar a máscara anterior em $old e passá-la de volta para umask() deixa o processo no estado em que começou.

Armadilhas Comuns

• umask() é válida para todo o processo. Em um contexto de longa execução (workers FPM, daemons CLI) a chamada umask() de um script vaza para requisições posteriores no mesmo worker. Sempre restaure o valor anterior como no Exemplo 2.
• Ela afeta apenas a criação. Arquivos existentes não são alterados; use chmod() para modificar permissões depois do fato.
• O SO limita o resultado. umask() só pode remover bits. Ela não pode conceder o bit de execução a um arquivo regular, pois o modo base para arquivos já é 0666.
• Esquecer o zero inicial. umask(22) e umask(022) significam coisas diferentes — o primeiro é decimal, o segundo é octal.

Funções Relacionadas

• chmod() — altera as permissões de um arquivo ou diretório existente.
• fileperms() — lê os bits de permissão atuais de um arquivo.
• mkdir() — cria um diretório (seu argumento de modo também é filtrado pelo umask).
• fopen() — abre ou cria um arquivo.

Conclusão

A função umask() controla quais bits de permissão são removidos dos arquivos e diretórios recém-criados. Lembre-se de que ela funciona removendo bits (base & ~mask), aplica-se a todo o processo e afeta apenas novas criações. Quando você a altera dentro de uma função, salve e restaure o valor anterior para evitar surpreender o código posterior.

Prática