filegroup()

La función filegroup() devuelve el ID de grupo del grupo propietario de un archivo. En sistemas similares a Unix, cada archivo pertenece a un usuario y a un grupo; filegroup() te indica el ID numérico de ese grupo. Este capítulo cubre su sintaxis, valor de retorno, cómo convertir el ID numérico en un nombre de grupo, errores comunes y dónde encaja entre las demás funciones de inspección de archivos de PHP.

Sintaxis

filegroup(string $filename): int|false

$filename es la ruta al archivo (o directorio) a inspeccionar. En caso de éxito, la función devuelve el ID de grupo como un entero. En caso de fallo, devuelve false.

Algunas cosas que conviene saber de antemano:

• El ID de grupo es un número, no un nombre. En la mayoría de los sistemas 0 corresponde al grupo root/wheel, pero la asignación exacta es específica del sistema.
• El resultado se almacena en caché. PHP guarda en caché los datos de stat() por archivo, por lo que si el grupo de un archivo cambia durante la ejecución del script, puede ser necesario llamar a clearstatcache() para ver el nuevo valor.
• En Windows el concepto de grupo de archivos no aplica, y filegroup() no tiene sentido allí.

Ejemplo básico

<?php

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

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

Usar __FILE__ garantiza que la ruta existe, por lo que el ejemplo es reproducible. La salida es un número como:

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

Convertir el ID en un nombre de grupo

Un número sin procesar rara vez es lo que deseas mostrar. En sistemas con la extensión POSIX puedes resolverlo a un nombre legible con 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";
}

Nota: posix_getgrgid() forma parte de la extensión POSIX y no está disponible en Windows. Siempre protege la llamada con function_exists() si tu código puede ejecutarse en múltiples plataformas.

Manejo de errores

Cuando el archivo no existe o no se puede acceder a él, filegroup() devuelve false y emite un E_WARNING. Dado que false podría confundirse con 0 (un ID de grupo válido para root), comprueba siempre con el operador estricto ===:

<?php

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

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

Para suprimir la advertencia cuando un archivo faltante es un caso esperado, comprueba primero su existencia con file_exists(), en lugar de silenciarlo con el operador @.

¿Cuándo usaría esto?

filegroup() es útil cuando necesitas auditar o verificar la propiedad de archivos — por ejemplo, confirmar que los archivos subidos o los archivos de caché generados pertenecen al grupo del servidor web (a menudo www-data) para que el servidor pueda leerlos y escribirlos. Se combina habitualmente con:

• fileowner() — el ID de usuario propietario del archivo.
• fileperms() — los bits de permisos del archivo.
• filetype() — si es un archivo, directorio, enlace, etc.
• stat() — todo lo anterior (y más) en una sola llamada.

Conclusión

filegroup() devuelve el ID de grupo numérico de un archivo, o false en caso de fallo. Combínala con posix_getgrgid() para mostrar un nombre de grupo legible, compara siempre el resultado con === para distinguir el fallo de un 0 legítimo, y recuerda usar clearstatcache() cuando la propiedad pueda haber cambiado durante la ejecución del script. Para obtener una imagen más completa de los metadatos de un archivo, recurre a fileowner(), fileperms() y stat().

Práctica