chgrp()

Introduzione

Nei sistemi Unix-like ogni file appartiene a un utente (il proprietario) e a un gruppo. Il gruppo consente a più account di condividere l'accesso allo stesso file tramite i bit di permesso del gruppo. La funzione chgrp() in PHP cambia il gruppo a cui appartiene un file o una directory — lo stesso compito che svolge il comando shell chgrp, ma richiamabile dal codice.

Questo è necessario soprattutto quando uno script crea file che un server web, un utente di deployment o un worker in background deve leggere o scrivere: si imposta il gruppo in modo che tutti quegli account (che appartengono a quel gruppo condiviso) possano accedere al file.

Questo articolo tratta la sintassi, i parametri, il valore restituito, le problematiche comuni ed esempi pratici, incluso come cambiare il gruppo di un intero albero di directory.

chgrp() ha effetto solo sui sistemi Unix-like (Linux, macOS, BSD). Su Windows non fa nulla e restituisce true. È correlata a chown() (cambia il proprietario) e chmod() (cambia i bit di permesso).

Sintassi

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

• $filename — il percorso del file o della directory di cui si vuole cambiare il gruppo.
• $group — il nuovo gruppo, specificato come nome del gruppo (es. "www-data") oppure come ID numerico del gruppo / GID (es. 33).

Parametri

Passare un GID è utile quando il nome del gruppo potrebbe non essere risolto sull'host corrente ma si sa che l'ID numerico è stabile.

Valori restituiti

chgrp() restituisce un valore boolean:

• true — il gruppo è stato cambiato con successo (o la piattaforma è Windows, dove la chiamata non produce effetti).
• false — il cambiamento non è riuscito, di solito perché il processo non ha i permessi necessari oppure il gruppo o il file non esiste. Viene emesso anche un avviso.

Poiché il valore restituito da solo non indica il motivo del fallimento, è sempre consigliabile verificarlo esplicitamente anziché ignorarlo.

Esempi

Cambiare il gruppo di un singolo file

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

Leggere il gruppo dopo averlo cambiato

Per confermare la modifica, è possibile consultare il gruppo con filegroup(), che restituisce il GID del file. La cache condivisa dalle funzioni stat può essere non aggiornata subito dopo una modifica, quindi è necessario azzerarla prima 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;
}

Cambiare il gruppo di un intero albero di directory (ricorsivo)

chgrp() non opera in modo ricorsivo, quindi per cambiare il gruppo di ogni file all'interno di una directory è necessario iterare manualmente. Un RecursiveDirectoryIterator rende questo processo conciso:

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

Problematiche comuni

• Permessi. Solo il proprietario del file (quando è membro del gruppo di destinazione) o il superutente possono cambiare il gruppo di un file. Una tipica richiesta web in esecuzione come www-data non può riassegnare file a gruppi arbitrari, quindi questo spesso fallisce silenziosamente negli ambienti di hosting condiviso — verificare sempre il valore restituito.
• Link simbolici. chgrp() segue i symlink e cambia il gruppo del file di destinazione. Per cambiare il gruppo del link stesso, è necessario utilizzare il comportamento della famiglia lchown() (lchgrp non è disponibile in PHP, quindi per operare sul percorso del link è necessario utilizzare gli strumenti del sistema operativo sottostante).
• Cache stat non aggiornata. PHP memorizza nella cache i metadati dei file; dopo chgrp() chiamare clearstatcache() prima di rileggere il gruppo, altrimenti si potrebbe vedere il vecchio valore.
• Nessuna espansione glob. chgrp("uploads/*", ...) non funziona — passare un percorso reale e iterare sui risultati di glob() manualmente.

Funzioni correlate

• chown() — cambia il proprietario del file.
• chmod() — cambia i bit di permesso.
• filegroup() — legge il gruppo corrente di un file (GID).
• clearstatcache() — azzera i metadati del file memorizzati nella cache.

Conclusione

chgrp() offre a PHP un modo diretto per gestire quale gruppo possiede un file o una directory — la chiave per consentire a più account Unix di condividere l'accesso. Tenere presente che richiede privilegi sufficienti, non opera in modo ricorsivo autonomamente e che è necessario azzerare la cache stat prima di rileggere il risultato. Abbinarla a chown() e chmod() quando si ha bisogno del controllo completo su proprietà e permessi.

Esercitazione