chgrp()

Einführung

Auf Unix-ähnlichen Systemen gehört jede Datei einem Benutzer (dem Eigentümer) und einer Gruppe. Die Gruppe ermöglicht es mehreren Konten, über die Gruppenberechtigungsbits der Datei gemeinsam auf dieselbe Datei zuzugreifen. Die Funktion chgrp() in PHP ändert, zu welcher Gruppe eine Datei oder ein Verzeichnis gehört — dieselbe Aufgabe, die der Shell-Befehl chgrp erledigt, aber direkt aus dem Code heraus aufrufbar.

Dies wird am häufigsten benötigt, wenn ein Skript Dateien erstellt, die auch ein Webserver, ein Deployment-Benutzer oder ein Hintergrundprozess lesen oder schreiben muss: Sie setzen die Gruppe so, dass all diese Konten (die zu der gemeinsamen Gruppe gehören) auf die Datei zugreifen können.

Dieser Artikel behandelt die Syntax, Parameter, den Rückgabewert, häufige Fallstricke und ausführbare Beispiele, einschließlich der Änderung eines gesamten Verzeichnisbaums.

chgrp() wirkt nur auf Unix-ähnlichen Systemen (Linux, macOS, BSD). Unter Windows macht es nichts und gibt true zurück. Es ist ein Geschwister von chown() (ändert den Eigentümer) und chmod() (ändert die Berechtigungsbits).

Syntax

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

• $filename — der Pfad zur Datei oder zum Verzeichnis, dessen Gruppe geändert werden soll.
• $group — die neue Gruppe, angegeben entweder als Gruppenname (z. B. "www-data") oder als numerische Gruppen-ID / GID (z. B. 33).

Parameter

Die Angabe einer GID ist praktisch, wenn der Gruppenname auf dem aktuellen Host möglicherweise nicht auflösbar ist, Sie jedoch wissen, dass die numerische ID stabil ist.

Rückgabewerte

chgrp() gibt einen boolean zurück:

• true — die Gruppe wurde erfolgreich geändert (oder die Plattform ist Windows, wo der Aufruf ein No-Op ist).
• false — die Änderung schlug fehl, normalerweise weil dem Prozess die Berechtigung fehlt oder die Gruppe/Datei nicht existiert. Außerdem wird eine Warnung ausgegeben.

Da der Rückgabewert allein nicht verrät, warum es fehlgeschlagen ist, sollten Sie ihn immer explizit prüfen und nicht ignorieren.

Beispiele

Gruppe einer einzelnen Datei ändern

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

Gruppe nach der Änderung auslesen

Um die Änderung zu bestätigen, lesen Sie die Gruppe mit filegroup() aus, die die GID der Datei zurückgibt. Der Cache, den die Stat-Funktionen gemeinsam nutzen, kann unmittelbar nach einer Änderung veraltet sein, daher leeren Sie ihn zuerst mit 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;
}

Gruppe eines gesamten Verzeichnisbaums ändern (rekursiv)

chgrp() arbeitet nicht rekursiv. Um jede Datei unter einem Verzeichnis zu ändern, müssen Sie selbst iterieren. Ein RecursiveDirectoryIterator macht dies kompakt:

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

Häufige Fallstricke

• Berechtigungen. Nur der Dateieigentümer (sofern er Mitglied der Zielgruppe ist) oder der Superuser kann die Gruppe einer Datei ändern. Eine typische Webanfrage, die als www-data läuft, kann Dateien nicht beliebigen Gruppen zuordnen, sodass dies bei Shared-Hosting-Umgebungen oft still fehlschlägt — prüfen Sie daher immer den Rückgabewert.
• Symbolische Links. chgrp() folgt Symlinks und ändert die Gruppe der Zieldatei. Um die Gruppe des Links selbst zu ändern, verwenden Sie das Verhalten der lchown()-Familie (lchgrp ist in PHP nicht verfügbar; verwenden Sie in diesem Fall die OS-Tools direkt auf dem Link-Pfad).
• Veralteter Stat-Cache. PHP cached Datei-Metadaten; nach einem chgrp()-Aufruf sollten Sie clearstatcache() aufrufen, bevor Sie die Gruppe erneut auslesen, sonst sehen Sie möglicherweise den alten Wert.
• Keine Glob-Expansion. chgrp("uploads/*", ...) funktioniert nicht — übergeben Sie einen echten Pfad und iterieren Sie selbst über die Ergebnisse von glob().

Verwandte Funktionen

• chown() — den Eigentümer der Datei ändern.
• chmod() — die Berechtigungsbits ändern.
• filegroup() — die aktuelle Gruppe (GID) einer Datei auslesen.
• clearstatcache() — gecachte Datei-Metadaten zurücksetzen.

Fazit

chgrp() bietet PHP eine direkte Möglichkeit, zu verwalten, welche Gruppe eine Datei oder ein Verzeichnis besitzt — der Schlüssel dazu, mehreren Unix-Konten gemeinsamen Zugriff zu gewähren. Beachten Sie, dass die Funktion ausreichende Berechtigungen benötigt, nicht selbst rekursiert und dass Sie den Stat-Cache leeren sollten, bevor Sie das Ergebnis erneut auslesen. Kombinieren Sie sie mit chown() und chmod(), wenn Sie volle Kontrolle über Eigentümerschaft und Berechtigungen benötigen.

Übung