filegroup()

The filegroup() function returns the group ID of the owning group of a file. On Unix-like systems every file belongs to a user and a group; filegroup() tells you the numeric ID of that group. This chapter covers its syntax, return value, how to turn the numeric ID into a group name, common gotchas, and where it fits among PHP's other file-inspection functions.

Syntax

filegroup(string $filename): int|false

$filename is the path to the file (or directory) to inspect. On success the function returns the group ID as an integer. On failure it returns false.

A few things worth knowing up front:

• The group ID is a number, not a name. On most systems 0 is the root/wheel group, but the exact mapping is system-specific.
• The result is cached. PHP caches stat() data per file, so if a file's group changes during script execution you may need to call clearstatcache() to see the new value.
• On Windows the concept of a file group does not apply, and filegroup() is not meaningful there.

Basic example

<?php

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

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

Using __FILE__ guarantees the path exists, so the example is reproducible. The output is a number such as:

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

Turning the ID into a group name

A raw number is rarely what you want to show. On systems with the POSIX extension you can resolve it to a readable name with 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";
}

Note: posix_getgrgid() is part of the POSIX extension and is not available on Windows. Always guard the call with function_exists() if your code might run cross-platform.

Handling errors

When the file does not exist or cannot be accessed, filegroup() returns false and emits an E_WARNING. Because false could be confused with 0 (a valid group ID for root), always check with the strict === operator:

<?php

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

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

To suppress the warning when a missing file is an expected case, check existence first with file_exists(), rather than silencing it with the @ operator.

When would I use this?

filegroup() is useful when you need to audit or verify file ownership — for example, confirming that uploaded files or generated cache files belong to the web-server group (often www-data) so the server can read and write them. It is commonly paired with:

• fileowner() — the user ID that owns the file.
• fileperms() — the file's permission bits.
• filetype() — whether it is a file, directory, link, etc.
• stat() — all of the above (and more) in a single call.

Conclusion

filegroup() returns the numeric group ID of a file, or false on failure. Combine it with posix_getgrgid() to display a human-readable group name, always compare the result with === to distinguish failure from a legitimate 0, and remember clearstatcache() when ownership may have changed mid-script. For a fuller picture of a file's metadata, reach for fileowner(), fileperms(), and stat().

Practice