chgrp()

Введение

В Unix-подобных системах каждый файл принадлежит пользователю (владельцу) и группе. Группа позволяет нескольким учётным записям совместно использовать один файл через биты группового доступа. Функция chgrp() в PHP изменяет группу файла или директории — ту же задачу, что выполняет команда оболочки chgrp, но вызываемую из кода.

Это чаще всего требуется, когда скрипт создаёт файлы, к которым должны также иметь доступ веб-сервер, пользователь деплоя или фоновый воркер: вы задаёте группу, чтобы все эти учётные записи (входящие в данную общую группу) могли работать с файлом.

В статье рассматриваются синтаксис, параметры, возвращаемое значение, типичные подводные камни и запускаемые примеры, в том числе как изменить группу для целого дерева директорий.

chgrp() работает только на Unix-подобных системах (Linux, macOS, BSD). На Windows она ничего не делает и возвращает true. Это функция-«сестра» chown() (меняет владельца) и chmod() (меняет биты прав доступа).

Синтаксис

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

• $filename — путь к файлу или директории, для которых меняется группа.
• $group — новая группа, задаётся либо как имя группы (например, "www-data"), либо как числовой идентификатор группы / GID (например, 33).

Параметры

Передача GID удобна в тех случаях, когда имя группы может не разрешиться на текущем хосте, но числовой идентификатор гарантированно стабилен.

Возвращаемые значения

chgrp() возвращает boolean:

• true — группа успешно изменена (или платформа — Windows, где вызов является холостым).
• false — изменение не выполнено, как правило из-за недостаточных прав или отсутствия группы/файла. При этом также выдаётся предупреждение.

Поскольку возвращаемое значение само по себе не говорит о причине ошибки, всегда проверяйте его явно, а не игнорируйте.

Примеры

Изменение группы одного файла

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

Чтение группы после её изменения

Чтобы убедиться в успешном изменении, получите группу с помощью filegroup(), которая возвращает GID файла. Кеш, который используют функции stat, может устареть сразу после изменения, поэтому предварительно очистите его с помощью 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;
}

Изменение группы для всего дерева директорий (рекурсивно)

chgrp() не работает рекурсивно, поэтому для изменения каждого файла внутри директории нужно итерироваться вручную. RecursiveDirectoryIterator делает это лаконичным:

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

Типичные подводные камни

• Права доступа. Изменить группу файла может только его владелец (при условии, что он входит в целевую группу) или суперпользователь. Типичный веб-запрос, выполняющийся от имени www-data, не может произвольно переназначать группы файлов, поэтому в среде shared-хостинга это часто завершается неудачей без видимых признаков — всегда проверяйте возвращаемое значение.
• Символические ссылки. chgrp() следует по символическим ссылкам и изменяет группу целевого файла. Чтобы изменить группу самой ссылки, используйте поведение семейства lchown() (lchgrp в PHP недоступна, поэтому при необходимости работайте с путём ссылки средствами ОС).
• Устаревший кеш stat. PHP кеширует метаданные файлов; после вызова chgrp() вызовите clearstatcache() перед повторным чтением группы, иначе может отображаться старое значение.
• Без раскрытия glob. chgrp("uploads/*", ...) не работает — передавайте реальный путь и самостоятельно перебирайте совпадения из glob().

Связанные функции

• chown() — изменить владельца файла.
• chmod() — изменить биты прав доступа.
• filegroup() — получить текущую группу файла (GID).
• clearstatcache() — сбросить кеш метаданных файла.

Заключение

chgrp() предоставляет PHP прямой способ управлять тем, какая группа владеет файлом или директорией — что является ключом к совместному доступу нескольких Unix-учётных записей. Помните, что функция требует достаточных привилегий, не выполняет рекурсию самостоятельно и что перед повторным чтением результата необходимо очищать кеш stat. Используйте её вместе с chown() и chmod(), когда требуется полный контроль над владением и правами доступа.

Практика