filegroup()

A função filegroup() retorna o ID do grupo proprietário de um arquivo. Em sistemas Unix, cada arquivo pertence a um usuário e a um grupo; filegroup() informa o ID numérico desse grupo. Este capítulo aborda sua sintaxe, valor de retorno, como converter o ID numérico em um nome de grupo, armadilhas comuns e onde ela se encaixa entre as outras funções PHP de inspeção de arquivos.

Sintaxe

filegroup(string $filename): int|false

$filename é o caminho para o arquivo (ou diretório) a ser inspecionado. Em caso de sucesso, a função retorna o ID do grupo como um integer. Em caso de falha, retorna false.

Alguns pontos importantes a saber de antemão:

• O ID do grupo é um número, não um nome. Na maioria dos sistemas, 0 é o grupo root/wheel, mas o mapeamento exato é específico do sistema.
• O resultado é armazenado em cache. PHP armazena em cache os dados de stat() por arquivo; portanto, se o grupo de um arquivo mudar durante a execução do script, pode ser necessário chamar clearstatcache() para ver o novo valor.
• No Windows, o conceito de grupo de arquivo não se aplica, e filegroup() não tem significado nessa plataforma.

Exemplo básico

<?php

$filename = __FILE__; // the script file itself — guaranteed to exist
$groupId = filegroup($filename);

echo "The group ID of $filename is $groupId";

Usar __FILE__ garante que o caminho exista, tornando o exemplo reproduzível. A saída é um número como:

The group ID of /var/www/example.php is 33

Convertendo o ID em nome de grupo

Um número bruto raramente é o que você quer exibir. Em sistemas com a extensão POSIX, é possível resolvê-lo para um nome legível com posix_getgrgid():

<?php

$groupId = filegroup(__FILE__);

if ($groupId === false) {
    echo "Could not read the file group.";
} elseif (function_exists('posix_getgrgid')) {
    $group = posix_getgrgid($groupId);
    echo "Group name: " . $group['name']; // e.g. "www-data"
} else {
    echo "Group ID: $groupId";
}

Nota: posix_getgrgid() faz parte da extensão POSIX e não está disponível no Windows. Sempre proteja a chamada com function_exists() caso seu código possa ser executado em múltiplas plataformas.

Tratamento de erros

Quando o arquivo não existe ou não pode ser acessado, filegroup() retorna false e emite um E_WARNING. Como false pode ser confundido com 0 (um ID de grupo válido para root), sempre compare usando o operador estrito ===:

<?php

$result = filegroup('does-not-exist.txt');

if ($result === false) {
    echo "Unable to determine the file group.";
} else {
    echo "Group ID: $result";
}

Para suprimir o aviso quando um arquivo ausente é um caso esperado, verifique a existência primeiro com file_exists(), em vez de silenciar com o operador @.

Quando usar esta função?

filegroup() é útil quando você precisa auditar ou verificar a propriedade de arquivos — por exemplo, confirmar que arquivos enviados ou arquivos de cache gerados pertencem ao grupo do servidor web (geralmente www-data) para que o servidor possa lê-los e gravá-los. Ela é comumente usada em conjunto com:

• fileowner() — o ID do usuário proprietário do arquivo.
• fileperms() — os bits de permissão do arquivo.
• filetype() — se é um arquivo, diretório, link, etc.
• stat() — todos os itens acima (e mais) em uma única chamada.

Conclusão

filegroup() retorna o ID numérico do grupo de um arquivo, ou false em caso de falha. Combine-a com posix_getgrgid() para exibir um nome de grupo legível, sempre compare o resultado com === para distinguir falha de um 0 legítimo, e lembre-se de usar clearstatcache() quando a propriedade pode ter mudado durante a execução do script. Para uma visão mais completa dos metadados de um arquivo, utilize fileowner(), fileperms() e stat().

Prática