chgrp()

Introduction

Sur les systèmes de type Unix, chaque fichier appartient à un utilisateur (le propriétaire) et à un groupe. Le groupe permet à plusieurs comptes de partager l'accès au même fichier via les bits de permission de groupe du fichier. La fonction chgrp() en PHP modifie le groupe auquel appartient un fichier ou un répertoire — le même rôle que la commande shell chgrp, mais appelable depuis votre code.

Cela est le plus souvent nécessaire lorsqu'un script crée des fichiers qu'un serveur web, un utilisateur de déploiement ou un processus en arrière-plan doit également lire ou écrire : vous définissez le groupe afin que tous ces comptes (qui appartiennent à ce groupe partagé) puissent accéder au fichier.

Cet article couvre la syntaxe, les paramètres, la valeur de retour, les pièges courants et des exemples exécutables, y compris comment modifier tout un arbre de répertoires.

chgrp() n'a d'effet que sur les systèmes de type Unix (Linux, macOS, BSD). Sur Windows, elle ne fait rien et retourne true. Elle est parente de chown() (modifie le propriétaire) et chmod() (modifie les bits de permission).

Syntaxe

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

• $filename — le chemin vers le fichier ou le répertoire dont le groupe sera modifié.
• $group — le nouveau groupe, fourni soit sous forme de nom de groupe (p. ex. "www-data") soit sous forme d'identifiant numérique de groupe / GID (p. ex. 33).

Paramètres

Passer un GID est pratique lorsque le nom du groupe ne peut pas être résolu sur l'hôte actuel mais que vous savez que l'identifiant numérique est stable.

Valeurs de retour

chgrp() retourne un boolean :

• true — le groupe a été modifié avec succès (ou la plateforme est Windows, où l'appel est sans effet).
• false — la modification a échoué, généralement parce que le processus n'a pas les permissions nécessaires ou que le groupe/fichier n'existe pas. Un avertissement est également émis.

La valeur de retour seule ne vous indique pas pourquoi la modification a échoué, vérifiez-la toujours explicitement plutôt que de l'ignorer.

Exemples

Modifier le groupe d'un seul fichier

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

Lire le groupe après l'avoir modifié

Pour confirmer la modification, récupérez le groupe avec filegroup(), qui retourne le GID du fichier. Le cache partagé par les fonctions stat peut être obsolète juste après une modification, donc videz-le d'abord avec 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;
}

Modifier le groupe de tout un arbre de répertoires (récursif)

chgrp() ne parcourt pas les sous-répertoires, donc pour modifier chaque fichier sous un répertoire, vous devez itérer vous-même. Un RecursiveDirectoryIterator rend cela concis :

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

Pièges courants

• Permissions. Seul le propriétaire du fichier (lorsqu'il est membre du groupe cible) ou le superutilisateur peut modifier le groupe d'un fichier. Une requête web typique s'exécutant en tant que www-data ne peut pas réattribuer des fichiers à des groupes arbitraires, ce qui échoue souvent silencieusement en hébergement mutualisé — vérifiez toujours la valeur de retour.
• Liens symboliques. chgrp() suit les liens symboliques et modifie le groupe du fichier cible. Pour modifier le groupe du lien lui-même, utilisez le comportement de la famille lchown() (lchgrp n'est pas disponible en PHP, donc opérez sur le chemin du lien avec les outils du système d'exploitation sous-jacent si nécessaire).
• Cache stat obsolète. PHP met en cache les métadonnées des fichiers ; après chgrp(), appelez clearstatcache() avant de relire le groupe, sinon vous pourriez voir l'ancienne valeur.
• Pas d'expansion de glob. chgrp("uploads/*", ...) ne fonctionne pas — passez un chemin réel et parcourez les correspondances de glob() vous-même.

Fonctions associées

• chown() — modifier le propriétaire du fichier.
• chmod() — modifier les bits de permission.
• filegroup() — lire le groupe actuel d'un fichier (GID).
• clearstatcache() — réinitialiser les métadonnées de fichier en cache.

Conclusion

chgrp() offre à PHP un moyen direct de gérer le groupe propriétaire d'un fichier ou d'un répertoire — la clé pour permettre à plusieurs comptes Unix de partager l'accès. N'oubliez pas qu'elle nécessite des privilèges suffisants, ne parcourt pas les sous-répertoires seule, et que vous devez vider le cache stat avant de relire le résultat. Combinez-la avec chown() et chmod() lorsque vous avez besoin d'un contrôle total sur la propriété et les permissions.

Pratique