chmod()

Entendendo a Função PHP chmod()

chmod() altera o modo (os bits de permissão) de um arquivo ou diretório em um sistema de arquivos Unix. O modo controla quem pode fazer o quê com o arquivo: ler seu conteúdo, escrever nele ou executá-lo. Definir as permissões corretamente é importante para a segurança — permissivas demais e qualquer pessoa pode ler ou sobrescrever dados sensíveis; restritivas demais e o seu servidor web não consegue ler os arquivos que precisa servir.

Esta página aborda a sintaxe, como ler e escrever o modo octal, os valores de permissão mais comuns que você realmente vai usar, o valor de retorno e os problemas que pegam as pessoas de surpresa (o zero inicial, o umask e o Windows).

Sintaxe

chmod(string $filename, int $permissions): bool

Retorna true em caso de sucesso e false em caso de falha.

Como funciona o modo octal

O modo é um número octal de três dígitos. Cada dígito descreve uma classe de usuário:

Cada dígito é a soma das permissões concedidas àquela classe:

Some-os: leitura + escrita = 4 + 2 = 6, e leitura + execução = 4 + 1 = 5. Portanto, 0750 significa proprietário: leitura/escrita/execução (7), grupo: leitura/execução (5), outros: nada (0).

Valores de permissão comuns

Exemplos

Definir permissões em um único arquivo

O modo 0644 permite que o proprietário leia e escreva, enquanto o grupo e todos os demais podem apenas ler:

<?php
if (chmod("example.txt", 0644)) {
    echo "Permissions updated.";
} else {
    echo "Failed to change permissions.";
}

Tornar um script executável

Para executar um script PHP diretamente (por exemplo, um cron job de CLI), o proprietário precisa de permissão de execução:

<?php
chmod("backup.php", 0744); // owner: rwx, group & others: read only

Sempre verifique o valor de retorno

chmod() falha silenciosamente retornando false — por exemplo, quando o script não é o proprietário do arquivo. Não presuma que funcionou:

<?php
$file = "config.ini";
if (!chmod($file, 0600)) {
    error_log("Could not secure {$file}");
}

Armadilhas

• A propriedade importa. Um processo só pode executar chmod() em um arquivo que ele possui (ou como superusuário). Em hospedagens compartilhadas, o usuário do servidor web geralmente não é o proprietário, então a chamada retorna false.
• umask não afeta chmod(). Ao contrário de mkdir() e da criação de arquivos, chmod() define o modo exatamente como solicitado. O umask só mascara arquivos recém-criados — veja umask().
• O Windows ignora a maioria dos bits. O NTFS não possui o modelo de permissões Unix, portanto no Windows apenas o bit somente leitura é afetado de forma significativa.
• Verifique antes de alterar. Use is_writable() para testar o acesso e fileperms() para ler o modo atual antes de sobrescrevê-lo.

Funções relacionadas

• fileperms() — lê os bits de permissão atuais de um arquivo.
• is_writable() — verifica se o script pode escrever em um caminho.
• umask() — define a máscara padrão aplicada a arquivos recém-criados.
• mkdir() — cria um diretório com um modo específico.

Conclusão

chmod() é sua ferramenta para restringir ou ampliar o acesso a arquivos e diretórios a partir do PHP. Lembre-se das três regras que evitam a maioria dos erros: escreva o modo em octal com um zero inicial, escolha a menor permissão que ainda funcione (0644 para arquivos, 0755 para diretórios) e verifique o valor de retorno, pois a função falha silenciosamente quando o script não é o proprietário do alvo.

Prática