chgrp()

Introducción

En los sistemas similares a Unix, cada archivo pertenece a un usuario (el propietario) y a un grupo. El grupo permite que varias cuentas compartan el acceso al mismo archivo a través de los bits de permisos de grupo. La función chgrp() en PHP cambia a qué grupo pertenece un archivo o directorio — la misma tarea que realiza el comando shell chgrp, pero invocable desde tu código.

Esto es necesario con mayor frecuencia cuando un script crea archivos que un servidor web, un usuario de despliegue o un proceso en segundo plano también deben leer o escribir: se establece el grupo para que todas esas cuentas (que pertenecen a ese grupo compartido) puedan acceder al archivo.

Este artículo cubre la sintaxis, los parámetros, el valor de retorno, los errores comunes y ejemplos ejecutables, incluyendo cómo cambiar un árbol de directorios completo.

chgrp() solo tiene efecto en sistemas similares a Unix (Linux, macOS, BSD). En Windows no hace nada y devuelve true. Es una función hermana de chown() (cambia el propietario) y chmod() (cambia los bits de permisos).

Sintaxis

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

• $filename — la ruta al archivo o directorio cuyo grupo se cambiará.
• $group — el nuevo grupo, indicado ya sea como nombre de grupo (p. ej. "www-data") o como ID de grupo numérico / GID (p. ej. 33).

Parámetros

Pasar un GID es útil cuando el nombre del grupo podría no resolverse en el host actual, pero se sabe que el ID numérico es estable.

Valores de Retorno

chgrp() devuelve un boolean:

• true — el grupo se cambió correctamente (o la plataforma es Windows, donde la llamada no tiene efecto).
• false — el cambio falló, generalmente porque el proceso no tiene permisos o el grupo/archivo no existe. También se emite una advertencia.

Como el valor de retorno por sí solo no indica por qué falló, verifícalo siempre de forma explícita en lugar de ignorarlo.

Ejemplos

Cambiar el grupo de un solo archivo

<?php

$filename = "/path/to/file.txt";
$group    = "www-data";

if (chgrp($filename, $group)) {
    echo "Group ownership changed to {$group}.";
} else {
    echo "Failed to change group ownership.";
}

Leer el grupo después de cambiarlo

Para confirmar el cambio, consulta el grupo con filegroup(), que devuelve el GID del archivo. La caché que comparten las funciones stat puede estar desactualizada justo después de un cambio, así que primero límpiala con clearstatcache():

<?php

$filename = "/path/to/file.txt";

chgrp($filename, "www-data");

clearstatcache();           // forget any cached stat info for the file
$gid = filegroup($filename); // numeric group ID

// On systems with the POSIX extension you can turn the GID into a name:
if (function_exists("posix_getgrgid")) {
    $info = posix_getgrgid($gid);
    echo "File now belongs to group: " . $info["name"];
} else {
    echo "File now belongs to GID: " . $gid;
}

Cambiar el grupo de un árbol de directorios completo (recursivo)

chgrp() no recursa, así que para cambiar cada archivo dentro de un directorio debes iterar tú mismo. Un RecursiveDirectoryIterator hace esto de forma concisa:

<?php

function chgrpRecursive(string $path, string|int $group): bool
{
    $ok = chgrp($path, $group);

    if (is_dir($path)) {
        $items = new RecursiveIteratorIterator(
            new RecursiveDirectoryIterator($path, FilesystemIterator::SKIP_DOTS),
            RecursiveIteratorIterator::SELF_FIRST
        );

        foreach ($items as $item) {
            $ok = chgrp($item->getPathname(), $group) && $ok;
        }
    }

    return $ok;
}

if (chgrpRecursive("/var/www/uploads", "www-data")) {
    echo "Whole tree updated.";
} else {
    echo "At least one path could not be changed.";
}

Errores Comunes

• Permisos. Solo el propietario del archivo (cuando es miembro del grupo destino) o el superusuario pueden cambiar el grupo de un archivo. Una solicitud web típica que se ejecuta como www-data no puede reasignar archivos a grupos arbitrarios, por lo que esto suele fallar silenciosamente en el hosting compartido — verifica siempre el valor de retorno.
• Enlaces simbólicos. chgrp() sigue los symlinks y cambia el grupo del archivo destino. Para cambiar el grupo del enlace en sí, usa el comportamiento de la familia lchown() (lchgrp no está disponible en PHP, así que opera en la ruta del enlace con las herramientas del sistema operativo cuando sea necesario).
• Caché stat desactualizada. PHP almacena en caché los metadatos de los archivos; después de chgrp(), llama a clearstatcache() antes de volver a leer el grupo, o podrías ver el valor antiguo.
• Sin expansión de glob. chgrp("uploads/*", ...) no funciona — pasa una ruta real, e itera manualmente sobre las coincidencias de glob().

Funciones Relacionadas

• chown() — cambia el propietario del archivo.
• chmod() — cambia los bits de permisos.
• filegroup() — lee el grupo actual de un archivo (GID).
• clearstatcache() — restablece los metadatos de archivo en caché.

Conclusión

chgrp() le da a PHP una forma directa de gestionar qué grupo es propietario de un archivo o directorio — la clave para que múltiples cuentas Unix compartan el acceso. Recuerda que necesita privilegios suficientes, no recursa por sí sola, y que debes limpiar la caché stat antes de leer el resultado. Combínala con chown() y chmod() cuando necesites control total sobre la propiedad y los permisos.

Práctica