chown()

A Função PHP chown()

A função chown() altera o proprietário de um arquivo ou diretório. Em sistemas Unix-like, cada arquivo possui um usuário e um grupo proprietário; chown() atualiza o usuário. É utilizada principalmente por administradores de servidor e scripts de implantação que precisam que um arquivo pertença a uma conta de sistema específica — por exemplo, transferir um arquivo enviado para o usuário do servidor web para que ele possa ser servido ou rotacionado.

Esta página cobre a sintaxe, os parâmetros, o valor de retorno, as permissões necessárias para seu funcionamento, problemas comuns e exemplos executáveis.

O proprietário é o usuário, não o grupo. Para alterar o grupo proprietário, use chgrp(). Para alterar as permissões de leitura/escrita/execução, use chmod(). Essas três funções são frequentemente confundidas.

Sintaxe

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

• $filename — caminho para o arquivo ou diretório cujo proprietário você deseja alterar.
• $user — o novo proprietário, especificado como uma string de nome de usuário (ex.: "www-data") ou como um ID de usuário numérico (UID, ex.: 33).

Retorna true em caso de sucesso e false em caso de falha.

Parâmetros

Passar uma string de nome de usuário exige que o PHP a resolva para um UID, portanto o usuário deve existir no banco de dados de usuários do sistema. Passar o UID diretamente ignora essa pesquisa.

Valor de retorno

chown() retorna um boolean:

• true — o proprietário foi alterado com sucesso.
• false — a alteração falhou (arquivo ausente, privilégios insuficientes ou o usuário especificado não existe). Um aviso também é emitido.

Sempre verifique o valor de retorno em vez de assumir o sucesso:

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

Quem pode chamar chown()?

Este é o motivo mais comum pelo qual chown() "não funciona":

• No Unix, apenas o superusuário (root) pode alterar o proprietário de um arquivo. Um processo normal, não-root, não pode transferir um arquivo para outro usuário.
• Portanto, em uma configuração típica de hospedagem compartilhada ou PHP-FPM padrão, chown() retornará false a menos que o processo PHP seja executado como root — o que geralmente não deve ocorrer.
• chown() não está disponível no Windows no sentido tradicional e se comporta como uma operação sem efeito lá.

Se você apenas precisa controlar o acesso em vez da propriedade, prefira chmod(), que o proprietário do arquivo pode chamar sem root.

Exemplos

Exemplo 1: Definir o proprietário usando um nome de usuário

Define o proprietário de example.txt para o usuário 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}.";
}

Exemplo 2: Definir o proprietário usando um UID

Se você conhece o ID de usuário numérico, passe-o diretamente. Aqui 1000 é um UID típico para o primeiro usuário não-sistema:

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

Exemplo 3: Ler o proprietário com fileowner()

Após alterar o proprietário, você pode confirmar o resultado. fileowner() retorna o UID, e (em sistemas com a extensão POSIX) posix_getpwuid() converte esse UID em um nome:

<?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() é importante aqui: o PHP armazena em cache os dados de status de arquivo, portanto sem isso você pode ler o proprietário antigo. Veja clearstatcache() para detalhes.

Exemplo 4: Alterar a propriedade de um diretório

chown() também funciona em diretórios, mas não é recursivo — afeta apenas a entrada do diretório em si, não os arquivos dentro dele. Para alterar a propriedade de uma árvore inteira, itere sobre seu conteúdo:

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

Problemas comuns

• Retorna false para processos não-root. Isso é por design — apenas root pode reatribuir propriedade.
• Dados de proprietário em cache. Chame clearstatcache() antes de reler informações de proprietário após uma alteração.
• Links simbólicos são seguidos. chown() altera o destino do link. Para alterar o próprio symlink, use lchown().
• Não é recursivo. Diretórios requerem iteração manual (Exemplo 4).
• open_basedir / disable_functions. Muitos hosts desabilitam chown() por segurança; verifique php.ini se ele falhar silenciosamente.

Funções relacionadas

• chgrp() — altera o grupo proprietário de um arquivo.
• chmod() — altera as permissões de arquivo (leitura/escrita/execução).
• fileowner() — obtém o UID do proprietário de um arquivo.
• filegroup() — obtém o GID do grupo de um arquivo.
• lchown() — altera o proprietário de um link simbólico em si.
• clearstatcache() — limpa os dados de status de arquivo em cache do PHP.

Conclusão

A função chown() altera o proprietário de um arquivo ou diretório, aceitando uma string de nome de usuário ou um UID numérico e retornando um boolean. O ponto principal a lembrar é que alterar a propriedade requer privilégios de superusuário, razão pela qual ela frequentemente retorna false no código web do dia a dia. Quando você precisa apenas controlar o acesso, use chmod(); para alterar o grupo, use chgrp().

Prática