posix_getgrnam — Funktion · PHP-Referenz

Signatur

posix_getgrnam(string $name): array|false

Beschreibung

posix_getgrnam() sucht in der Gruppendatenbank des Betriebssystems (typischerweise /etc/group oder ein angebundenes Verzeichnisdienst-Backend wie LDAP/NIS) nach der Gruppe mit dem angegebenen Namen und gibt deren Daten als assoziatives Array zurück.

Das zurückgegebene Array enthält folgende Schlüssel:

name – der Gruppenname
passwd – das (verschlüsselte) Gruppenpasswort, oft leer oder ein Platzhalter (x)
gid – die numerische Gruppen-ID (GID)
members – ein indiziertes Array mit den Benutzernamen aller Mitglieder der Gruppe

Die Funktion ist nützlich, um in Administrations-Skripten oder bei der Berechtigungsprüfung programmatisch die GID einer bekannten Gruppe zu ermitteln oder zu überprüfen, ob ein bestimmter Benutzer Mitglied einer Gruppe ist.

Achtung: Die Funktion steht nur auf POSIX-kompatiblen Systemen (Linux, macOS, BSD) zur Verfügung und ist unter Windows nicht verfügbar. Sie erfordert, dass die POSIX-Erweiterung aktiviert ist.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Der Name der Gruppe, nach der in der Systemdatenbank gesucht werden soll, z. B. `'www-data'` oder `'sudo'`.

Rückgabewert

Typ

array|false

Beschreibung

Gibt ein assoziatives Array mit den Schlüsseln name, passwd, gid und members zurück. Falls keine Gruppe mit dem angegebenen Namen gefunden wird oder ein Fehler auftritt, wird false zurückgegeben.

Beispiele

Gruppeninformationen für 'www-data' abrufen

<?php
$group = posix_getgrnam('www-data');

if ($group === false) {
    echo "Gruppe nicht gefunden.\n";
} else {
    echo "Gruppenname : " . $group['name'] . "\n";
    echo "GID         : " . $group['gid'] . "\n";
    echo "Mitglieder  : " . implode(', ', $group['members']) . "\n";
}

Gruppenname : www-data GID : 33 Mitglieder : www-data

Prüfen, ob ein Benutzer Mitglied einer bestimmten Gruppe ist

<?php
function isUserInGroup(string $username, string $groupname): bool {
    $group = posix_getgrnam($groupname);
    if ($group === false) {
        return false;
    }
    return in_array($username, $group['members'], true);
}

$user  = 'deploy';
$group = 'sudo';

if (isUserInGroup($user, $group)) {
    echo "Benutzer '{$user}' ist Mitglied der Gruppe '{$group}'.\n";
} else {
    echo "Benutzer '{$user}' ist KEIN Mitglied der Gruppe '{$group}'.\n";
}

Benutzer 'deploy' ist KEIN Mitglied der Gruppe 'sudo'.

// Wichtig · Fallstricke

Plattformabhängigkeit: Die Funktion ist ausschließlich auf POSIX-kompatiblen Systemen verfügbar. Unter Windows ist sie nicht vorhanden; ein Aufruf führt zu einem schwerwiegenden Fehler, wenn die POSIX-Erweiterung nicht geladen ist. Nutze function_exists('posix_getgrnam') zur Absicherung in portablem Code.

Sicherheit: Werte aus dem zurückgegebenen Array (insbesondere members) sollten vor der Weiterverwendung in HTML-Ausgaben mit htmlspecialchars() bereinigt werden, um XSS zu vermeiden. Das Feld passwd enthält unter modernen Systemen in der Regel nur einen Platzhalter und sollte nicht ausgewertet werden.

Das Gegenstück zur Suche per Name ist posix_getgrgid(), das eine Gruppe anhand ihrer numerischen GID sucht.

Siehe auch

posix_getgrgid posix_getpwnam posix_getpwuid posix_getgroups posix_getgid