PHP lchgrp() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Filesystem

Definition

In PHP, lchgrp() changes the group of a symbolic link itself. It does not follow the link to the file it points to.

The regular chgrp() function changes the target file, but lchgrp() changes only the link. It is used mostly in server and deployment scripts on Linux and macOS.

Syntax

Call lchgrp() with the values you need. Start with this line.

PHP
$ok = lchgrp('current', 'www-data');
CallWhat it does
lchgrp('current', 'www-data')Changes the group of the link named current to www-data.
lchgrp('current', 33)Does the same job by using the numeric group id.
lchgrp('missing-link', 'staff')Returns false with a warning because the link does not exist.

lchgrp() is not available on Windows. On Linux, you normally need to be the owner of the link and a member of the new group, or run as root. Changing the group of a normal file works too, but chgrp() is the clearer choice there.

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

Parameters

ParameterDescription
filenameRequired. The path to the symbolic link.
groupRequired. A group name as a string, or a group id as an integer.

Return Value

Return ValueDescription
boolReturns true on success or false on failure.

PHP Examples

Example 1 — Change the Group of a Link

Create a symbolic link and give the link a new group. Run this as a user who is allowed to do so, such as root.

PHP
<?php
$link = __DIR__ . '/current';
symlink('releases/v1', $link);

if (lchgrp($link, 'www-data')) {
    echo "Group of the link changed", PHP_EOL;
} else {
    echo "Could not change the group", PHP_EOL;
}

How It Works

  1. symlink() creates a link named current that points to releases/v1.
  2. lchgrp() sends the new group name to the operating system.
  3. Only the link is changed, not the folder releases/v1.
  4. A true result prints the success message.

Example 2 — Handle a Missing Link

lchgrp() returns false and raises a warning when the link does not exist.

PHP
<?php
$link = __DIR__ . '/no-such-link';

if (!@lchgrp($link, 'www-data')) {
    echo "Could not change the group", PHP_EOL;
}

How It Works

  1. The path does not point to any link or file.
  2. lchgrp() cannot find it and returns false.
  3. The @ symbol hides the PHP warning so you can show your own message.
  4. Always check the result before you assume the group was changed.

Example 3 — Confirm the New Group with lstat()

Use lstat() to read the group id of the link itself and prove that it changed.

PHP
<?php
$link = __DIR__ . '/current';
@unlink($link);
symlink('releases/v1', $link);

lchgrp($link, 33);

$info = lstat($link);
echo "Group id: ", $info['gid'], PHP_EOL;

How It Works

  1. unlink() removes an old link so the script can be run again.
  2. lchgrp() sets the group id 33 on the link, which is www-data on many Linux systems.
  3. lstat() reads information about the link itself, not the folder it points to.
  4. The gid value in the result shows the new group id.

Frequently Asked Questions

It changes the group ownership of a symbolic link without touching the file or folder that the link points to.
chgrp() follows a symbolic link and changes the target. lchgrp() changes the link itself.
No. The function is not available on Windows, so use function_exists() if your code must work on all systems.
Changing a group needs the right privileges. You usually must own the link and belong to the new group, or run PHP as root.
Yes. Pass an integer such as 33 and PHP will use it as the group id.

Next: lchown()

lchown() changes the owner of a symbolic link itself. It does not follow the link to the f.

lchown() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful