lchgrp()

La fonction PHP lchgrp() modifie la propriété de groupe du lien symbolique lui-même, et non du fichier vers lequel pointe le lien. Cette page explique son fonctionnement, en quoi elle diffère de chgrp(), les paramètres qu'elle accepte, ce qu'elle renvoie, ainsi que les règles de permissions et de plateforme qui déterminent si l'appel réussit.

Qu'est-ce que la fonction lchgrp() ?

Un lien symbolique (symlink) est un petit fichier qui pointe vers un autre chemin. La plupart des fonctions du système de fichiers « suivent » le lien et opèrent sur la cible. lchgrp() fait exception : le préfixe l signifie qu'elle agit sur le nœud du lien, laissant le groupe de la cible intact.

Cela est important lorsque le lien et sa cible appartiennent à des groupes différents, ou lorsque vous souhaitez gérer les permissions sur le lien sans modifier le fichier qu'il référence. Pour l'équivalent du propriétaire, voir lchown() ; pour la version qui suit la cible, voir chgrp().

Syntaxe

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

La fonction renvoie true en cas de succès et false en cas d'échec. En cas d'échec, PHP émet également un E_WARNING.

Comment utiliser lchgrp()

Passez le chemin du lien et le groupe cible, puis vérifiez le résultat booléen :

<?php

$link  = __DIR__ . '/data-current'; // a symlink, e.g. -> data-2026
$group = 'staff';

if (lchgrp($link, $group)) {
    echo "Link group changed to {$group}.";
} else {
    echo 'Could not change the link group.';
}

Comme lchgrp() cible le lien, le groupe du fichier data-2026 ne change pas — seul le lien symbolique data-current est modifié.

lchgrp() vs chgrp()

Les deux fonctions partagent la même signature mais diffèrent sur ce qu'elles modifient :

<?php

// Acts on the LINK only:
lchgrp('/var/www/current', 'www-data');

// Follows the link and acts on the TARGET file/directory:
chgrp('/var/www/current', 'www-data');

Utilisez lchgrp() lorsque vous avez spécifiquement besoin de modifier les métadonnées du lien symbolique et que vous souhaitez laisser la propriété de la cible telle quelle.

Valeur de retour, permissions et plateformes

Un retour true indique que la modification a été appliquée. Plusieurs conditions font que la fonction renvoie false (avec un avertissement) :

• Permissions. Seul le propriétaire du lien (ou le superutilisateur) peut modifier son groupe, et l'utilisateur doit être membre du groupe cible. Sur la plupart des systèmes, cela signifie que le script a effectivement besoin des droits root.
• Le chemin doit être un lien symbolique. Si $filename est un fichier ordinaire ou n'existe pas, l'appel échoue.
• Windows. La propriété de groupe est un concept POSIX, donc lchgrp() n'est pas significativement prise en charge sur Windows.

Les échecs étant fréquents dans les environnements partagés, utilisez toujours une condition sur la valeur de retour plutôt que de supposer le succès. Pour inspecter un lien avant de le modifier, is_link() et readlink() sont des fonctions complémentaires utiles.

<?php

$link = '/var/www/current';

if (!is_link($link)) {
    echo "{$link} is not a symbolic link.";
} elseif (lchgrp($link, 'www-data')) {
    echo 'Group updated.';
} else {
    echo 'Update failed — check ownership and group membership.';
}

Conclusion

lchgrp() modifie le groupe d'un lien symbolique sans le suivre jusqu'à la cible — l'équivalent symlink-aware de chgrp() et l'équivalent de groupe de lchown(). Elle renvoie true ou false, requiert la propriété appropriée et l'appartenance au groupe, et n'a aucun effet sur Windows. Vérifiez toujours sa valeur de retour et confirmez que le chemin est un lien avec is_link() avant de vous fier au résultat.

Practice