lchgrp()

The PHP lchgrp() function changes the group ownership of a symbolic link itself, not the file the link points to. This page explains what it does, how it differs from chgrp(), the parameters it accepts, what it returns, and the permission and platform rules that decide whether the call succeeds.

What is the lchgrp() Function?

A symbolic link (symlink) is a small file that points to another path. Most filesystem functions "follow" the link and operate on the target. lchgrp() is the exception: the l prefix means it acts on the link node, leaving the target's group untouched.

This matters when the link and its target are owned by different groups, or when you want to manage permissions on the link without changing the file it references. For the owner equivalent, see lchown(); for the target-following version, see chgrp().

Syntax

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

It returns true on success and false on failure. On failure PHP also emits an E_WARNING.

How to Use lchgrp()

Pass the link path and the target group, then check the boolean result:

<?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.';
}

Because lchgrp() targets the link, the group of the file data-2026 does not change — only the data-current symlink does.

lchgrp() vs chgrp()

The two functions share a signature but differ on what they touch:

<?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() when you specifically need the symlink's metadata changed and want to leave the target's ownership as-is.

Return Value, Permissions, and Platforms

A true return tells you the change was applied. Several conditions make it return false (with a warning):

• Permissions. Only the link's owner (or the superuser) can change its group, and the user must be a member of the target group. On most systems this means the script effectively needs root.
• The path must be a symlink. If $filename is a regular file or doesn't exist, the call fails.
• Windows. Group ownership is a POSIX concept, so lchgrp() is not meaningfully supported on Windows.

Because failures are common in shared environments, always branch on the return value rather than assuming success. To inspect a link before changing it, is_link() and readlink() are useful companions.

<?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.';
}

Conclusion

lchgrp() changes the group of a symbolic link without following it to the target — the symlink-aware counterpart to chgrp() and the group equivalent of lchown(). It returns true or false, requires appropriate ownership and group membership, and is a no-op on Windows. Always check its return value and confirm the path is a link with is_link() before relying on the result.

Practice