lchgrp()

A função PHP lchgrp() altera a propriedade de grupo do próprio link simbólico, não do arquivo para o qual o link aponta. Esta página explica o que ela faz, como se diferencia de chgrp(), os parâmetros que aceita, o que retorna e as regras de permissão e plataforma que determinam se a chamada terá sucesso.

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

Um link simbólico (symlink) é um pequeno arquivo que aponta para outro caminho. A maioria das funções do sistema de arquivos "segue" o link e opera no destino. lchgrp() é a exceção: o prefixo l significa que ela atua no nó do link, deixando o grupo do destino intocado.

Isso importa quando o link e seu destino pertencem a grupos diferentes, ou quando você deseja gerenciar permissões no link sem alterar o arquivo ao qual ele faz referência. Para o equivalente de proprietário, consulte lchown(); para a versão que segue o destino, consulte chgrp().

Sintaxe

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

Retorna true em caso de sucesso e false em caso de falha. Em caso de falha, o PHP também emite um E_WARNING.

Como Usar lchgrp()

Passe o caminho do link e o grupo de destino, depois verifique o resultado booleano:

<?php

$link  = __DIR__ . '/data-current'; // a symlink, e.g. -> data-2026
$group = 'staff';

if (lchgrp($link, $group)) {
    echo "Link group changed to {$group}.";
} else {
    echo 'Could not change the link group.';
}

Como lchgrp() tem como alvo o link, o grupo do arquivo data-2026 não muda — apenas o symlink data-current é alterado.

lchgrp() vs chgrp()

As duas funções compartilham a mesma assinatura, mas diferem no que alteram:

<?php

// Acts on the LINK only:
lchgrp('/var/www/current', 'www-data');

// Follows the link and acts on the TARGET file/directory:
chgrp('/var/www/current', 'www-data');

Use lchgrp() quando precisar especificamente alterar os metadados do symlink e quiser deixar a propriedade do destino como está.

Valor de Retorno, Permissões e Plataformas

Um retorno true indica que a alteração foi aplicada. Várias condições fazem com que retorne false (com um aviso):

• Permissões. Apenas o proprietário do link (ou o superusuário) pode alterar seu grupo, e o usuário deve ser membro do grupo de destino. Na maioria dos sistemas, isso significa que o script efetivamente precisa de privilégios root.
• O caminho deve ser um symlink. Se $filename for um arquivo comum ou não existir, a chamada falha.
• Windows. A propriedade de grupo é um conceito POSIX, portanto lchgrp() não é suportada de forma significativa no Windows.

Como falhas são comuns em ambientes compartilhados, sempre ramifique com base no valor de retorno em vez de assumir o sucesso. Para inspecionar um link antes de alterá-lo, is_link() e readlink() são companheiros úteis.

<?php

$link = '/var/www/current';

if (!is_link($link)) {
    echo "{$link} is not a symbolic link.";
} elseif (lchgrp($link, 'www-data')) {
    echo 'Group updated.';
} else {
    echo 'Update failed — check ownership and group membership.';
}

Conclusão

lchgrp() altera o grupo de um link simbólico sem seguir até o destino — a contraparte com conhecimento de symlink de chgrp() e o equivalente de grupo de lchown(). Retorna true ou false, requer propriedade e associação de grupo adequadas, e não tem efeito no Windows. Sempre verifique seu valor de retorno e confirme que o caminho é um link com is_link() antes de confiar no resultado.

Prática