chgrp()

Introdução

Em sistemas Unix, cada arquivo pertence a um usuário (o proprietário) e a um grupo. O grupo permite que várias contas compartilhem o acesso ao mesmo arquivo por meio dos bits de permissão de grupo. A função chgrp() em PHP muda o grupo ao qual um arquivo ou diretório pertence — a mesma função do comando shell chgrp, mas que pode ser chamada a partir do seu código.

Isso é mais frequentemente necessário quando um script cria arquivos que um servidor web, um usuário de implantação ou um worker em segundo plano também precisa ler ou gravar: você define o grupo para que todas essas contas (que pertencem a esse grupo compartilhado) possam acessar o arquivo.

Este artigo aborda a sintaxe, os parâmetros, o valor de retorno, armadilhas comuns e exemplos executáveis, incluindo como alterar toda uma árvore de diretórios.

chgrp() só tem efeito em sistemas do tipo Unix (Linux, macOS, BSD). No Windows, ela não faz nada e retorna true. É uma função relacionada a chown() (altera o proprietário) e chmod() (altera os bits de permissão).

Sintaxe

chgrp(string $filename, string|int $group): bool

• $filename — o caminho para o arquivo ou diretório cujo grupo será alterado.
• $group — o novo grupo, fornecido como nome de grupo (ex.: "www-data") ou como ID de grupo numérico / GID (ex.: 33).

Parâmetros

Passar um GID é útil quando o nome do grupo pode não ser resolvido no host atual, mas você sabe que o ID numérico é estável.

Valores de Retorno

chgrp() retorna um boolean:

• true — o grupo foi alterado com sucesso (ou a plataforma é Windows, onde a chamada não tem efeito).
• false — a alteração falhou, geralmente porque o processo não tem permissão ou o grupo/arquivo não existe. Um aviso também é emitido.

Como o valor de retorno por si só não indica por que falhou, sempre o verifique explicitamente em vez de ignorá-lo.

Exemplos

Alterar o grupo de um único arquivo

<?php

$filename = "/path/to/file.txt";
$group    = "www-data";

if (chgrp($filename, $group)) {
    echo "Group ownership changed to {$group}.";
} else {
    echo "Failed to change group ownership.";
}

Ler o grupo após alterá-lo

Para confirmar a alteração, consulte o grupo com filegroup(), que retorna o GID do arquivo. O cache compartilhado pelas funções stat pode estar desatualizado logo após uma alteração, portanto limpe-o primeiro com clearstatcache():

<?php

$filename = "/path/to/file.txt";

chgrp($filename, "www-data");

clearstatcache();           // forget any cached stat info for the file
$gid = filegroup($filename); // numeric group ID

// On systems with the POSIX extension you can turn the GID into a name:
if (function_exists("posix_getgrgid")) {
    $info = posix_getgrgid($gid);
    echo "File now belongs to group: " . $info["name"];
} else {
    echo "File now belongs to GID: " . $gid;
}

Alterar o grupo de toda uma árvore de diretórios (recursivo)

chgrp() não percorre recursivamente, portanto, para alterar cada arquivo em um diretório, você precisa iterar por conta própria. Um RecursiveDirectoryIterator torna isso conciso:

<?php

function chgrpRecursive(string $path, string|int $group): bool
{
    $ok = chgrp($path, $group);

    if (is_dir($path)) {
        $items = new RecursiveIteratorIterator(
            new RecursiveDirectoryIterator($path, FilesystemIterator::SKIP_DOTS),
            RecursiveIteratorIterator::SELF_FIRST
        );

        foreach ($items as $item) {
            $ok = chgrp($item->getPathname(), $group) && $ok;
        }
    }

    return $ok;
}

if (chgrpRecursive("/var/www/uploads", "www-data")) {
    echo "Whole tree updated.";
} else {
    echo "At least one path could not be changed.";
}

Armadilhas Comuns

• Permissões. Somente o proprietário do arquivo (quando ele é membro do grupo de destino) ou o superusuário pode alterar o grupo de um arquivo. Uma requisição web típica executando como www-data não pode reatribuir arquivos a grupos arbitrários, portanto isso geralmente falha silenciosamente em hospedagem compartilhada — sempre verifique o valor de retorno.
• Links simbólicos. chgrp() segue symlinks e altera o grupo do arquivo alvo. Para alterar o grupo do próprio link, use o comportamento da família lchown() (lchgrp não está disponível em PHP, então opere no caminho do link com as ferramentas do SO quando necessário).
• Cache de stat desatualizado. PHP armazena em cache metadados de arquivo; após chgrp(), chame clearstatcache() antes de reler o grupo, ou você poderá ver o valor antigo.
• Sem expansão glob. chgrp("uploads/*", ...) não funciona — passe um caminho real e itere sobre os resultados de glob() por conta própria.

Funções Relacionadas

• chown() — altera o proprietário do arquivo.
• chmod() — altera os bits de permissão.
• filegroup() — lê o grupo atual de um arquivo (GID).
• clearstatcache() — redefine os metadados de arquivo em cache.

Conclusão

chgrp() oferece ao PHP uma maneira direta de gerenciar qual grupo é dono de um arquivo ou diretório — a chave para permitir que várias contas Unix compartilhem o acesso. Lembre-se de que ela precisa de privilégios suficientes, não percorre recursivamente por conta própria e que você deve limpar o cache de stat antes de reler o resultado. Use-a em conjunto com chown() e chmod() quando precisar de controle total sobre propriedade e permissões.

Prática