chown()

Функция PHP chown()

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

На этой странице описаны синтаксис, параметры, возвращаемое значение, необходимые привилегии, типичные подводные камни и практические примеры.

Владелец — это пользователь, а не группа. Чтобы изменить группу-владельца, используйте chgrp(). Чтобы изменить права доступа на чтение/запись/выполнение, используйте chmod(). Эти три функции часто путают между собой.

Синтаксис

chown(string $filename, string|int $user): bool

• $filename — путь к файлу или каталогу, владельца которого нужно изменить.
• $user — новый владелец: string с именем пользователя (например, "www-data") или числовой идентификатор пользователя (UID, например, 33).

Функция возвращает true при успехе и false при ошибке.

Параметры

При передаче string PHP преобразует имя пользователя в UID, поэтому пользователь должен существовать в системной базе данных пользователей. Передача UID напрямую позволяет пропустить это преобразование.

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

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

• true — владелец успешно изменён.
• false — изменение не удалось (файл не найден, недостаточно привилегий или указанный пользователь не существует). Дополнительно генерируется предупреждение.

Всегда проверяйте возвращаемое значение, не полагаясь на успех:

<?php
if (chown("example.txt", "www-data")) {
    echo "Owner changed successfully.";
} else {
    echo "Could not change owner.";
}

Кто может вызывать chown()?

Это наиболее распространённая причина того, что chown() «не работает»:

• В Unix только суперпользователь (root) может изменить владельца файла. Обычный процесс без прав root не может передать файл другому пользователю.
• Поэтому в типичной среде shared-хостинга или стандартной конфигурации PHP-FPM функция chown() будет возвращать false, если PHP-процесс не запущен от root — что, как правило, нежелательно.
• chown() недоступна в Windows в традиционном понимании и там является пустой операцией.

Если вам нужно только управлять доступом, а не владением, предпочтите chmod() — её может вызывать владелец файла без прав root.

Примеры

Пример 1: Установка владельца по имени пользователя

Назначим владельцем файла example.txt пользователя www-data:

<?php
$file = "example.txt";

if (chown($file, "www-data")) {
    echo "Owner of {$file} set to www-data.";
} else {
    echo "Failed to change owner of {$file}.";
}

Пример 2: Установка владельца по UID

Если вы знаете числовой идентификатор пользователя, передайте его напрямую. Здесь 1000 — типичный UID первого непривилегированного пользователя:

<?php
chown("example.txt", 1000);

Пример 3: Чтение владельца с помощью fileowner()

После изменения владельца можно проверить результат. fileowner() возвращает UID, а функция posix_getpwuid() (при наличии расширения POSIX) преобразует этот UID в имя:

<?php
$file = "example.txt";

chown($file, "www-data");
clearstatcache(); // owner info is cached — clear it before re-reading

$uid  = fileowner($file);            // e.g. 33
$info = posix_getpwuid($uid);        // ["name" => "www-data", ...]

echo "Owner UID: {$uid}\n";
echo "Owner name: {$info['name']}\n";

clearstatcache() здесь важна: PHP кэширует данные о состоянии файлов, и без её вызова можно прочитать старого владельца. Подробнее см. clearstatcache().

Пример 4: Изменение владельца каталога

chown() работает и с каталогами, но не является рекурсивной — она затрагивает только сам каталог, а не файлы внутри него. Чтобы изменить владельца всего дерева, нужно обойти его содержимое вручную:

<?php
$dir = "/var/www/uploads";

chown($dir, "www-data"); // the directory only

foreach (new DirectoryIterator($dir) as $item) {
    if (!$item->isDot()) {
        chown($item->getPathname(), "www-data");
    }
}

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

• Возвращает false для непривилегированных процессов. Это предусмотрено по дизайну — только root может переназначать владельца.
• Кэширование данных о владельце. Вызывайте clearstatcache() перед повторным чтением информации о владельце после изменения.
• Символические ссылки разыменовываются. chown() изменяет владельца цели ссылки. Чтобы изменить саму символическую ссылку, используйте lchown().
• Отсутствие рекурсии. Для каталогов требуется ручной обход (Пример 4).
• open_basedir / disable_functions. Многие хостинг-провайдеры отключают chown() из соображений безопасности; проверьте php.ini, если функция молча не срабатывает.

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

• chgrp() — изменить группу-владельца файла.
• chmod() — изменить права доступа к файлу (чтение/запись/выполнение).
• fileowner() — получить UID владельца файла.
• filegroup() — получить GID группы файла.
• lchown() — изменить владельца символической ссылки как таковой.
• clearstatcache() — очистить кэш данных о состоянии файлов PHP.

Заключение

Функция chown() изменяет владельца файла или каталога, принимая в качестве аргумента string с именем пользователя или числовой UID и возвращая boolean. Главное, что следует помнить: изменение владельца требует привилегий суперпользователя, именно поэтому функция так часто возвращает false в обычном веб-коде. Когда достаточно просто управлять доступом, используйте chmod(); чтобы изменить группу — chgrp().

Практика