fileowner()

A função fileowner() é uma função PHP integrada que retorna o proprietário de um arquivo como um ID de usuário (UID) numérico — o mesmo UID que o sistema operacional armazena nos metadados do arquivo. É o equivalente PHP de visualizar a coluna de proprietário em ls -l. Esta página explica a sintaxe, os valores de retorno, o problema comum de resultados em cache desatualizados e como converter o UID numérico em um nome de usuário legível.

Sintaxe

fileowner(string $filename): int|false

• $filename — o caminho para o arquivo (ou diretório) a ser inspecionado. Pode ser relativo ou absoluto.
• Retorna o ID de usuário do proprietário como um int em caso de sucesso, ou false em caso de falha (por exemplo, se o arquivo não existir ou o script não tiver permissão para ler seus metadados).

Como um UID válido pode ser 0 (o usuário root em sistemas Unix), sempre compare o resultado com o operador estrito === false em vez de uma verificação de veracidade simples — caso contrário, um arquivo perfeitamente válido pertencente ao root pareceria um erro.

Exemplo básico

<?php

$filename = __FILE__; // inspect the running script itself

$owner_id = fileowner($filename);

if ($owner_id === false) {
    echo "Failed to get the owner of the file.";
} else {
    echo "The owner of '$filename' has user ID $owner_id.";
}

Uma saída possível é:

The owner of '/var/www/example.php' has user ID 33.

O número exato depende de qual conta do sistema operacional criou ou possui o arquivo (por exemplo, 33 é o usuário padrão www-data em muitos sistemas Debian/Ubuntu).

Convertendo o UID em nome de usuário

Um número simples raramente é o que você deseja mostrar a um usuário. Em sistemas do tipo Unix com a extensão POSIX habilitada, passe o UID para posix_getpwuid() para consultar os detalhes da conta:

<?php

$uid = fileowner(__FILE__);

if ($uid !== false && function_exists('posix_getpwuid')) {
    $info = posix_getpwuid($uid);
    echo "Owner: {$info['name']} (UID {$uid})";
} else {
    echo "Owner UID: " . var_export($uid, true);
}

Isso imprime algo como Owner: www-data (UID 33). A extensão POSIX não está disponível no Windows, portanto, proteja a chamada com function_exists() conforme mostrado.

Atenção aos resultados em cache

PHP armazena em cache os resultados de funções baseadas em stat (fileowner(), fileperms(), filegroup(), filesize() e semelhantes) por desempenho. Se o proprietário do arquivo mudar durante a mesma execução do script — por exemplo, após chamar chown() — fileowner() pode retornar o valor antigo. Limpe o cache primeiro com clearstatcache():

<?php

$file = 'report.txt';

chown($file, 'nobody');     // change ownership
clearstatcache();           // discard the stale stat cache
$uid = fileowner($file);    // now reflects the new owner

Observações e armadilhas

• Windows: o conceito de proprietário POSIX numérico não se aplica bem às ACLs do Windows. fileowner() normalmente retorna 0, portanto, não confie nela para lógica de permissão no Windows.
• false vs. 0: 0 é o root (um proprietário real); false significa que a chamada falhou. Use ===.
• Precisa de mais do que o proprietário? stat() retorna o array completo de metadados (tamanho, modo, proprietário, grupo, timestamps) em uma única chamada, o que é mais econômico do que chamar várias funções file*() separadamente.
• Verifique o acesso primeiro: se você só precisa saber se pode ler um arquivo, is_readable() é a ferramenta certa — fileowner() responde a uma pergunta diferente.

Conclusão

fileowner() é uma função pequena, mas útil, para ler o proprietário numérico de um arquivo em PHP. Compare o resultado com === false, lembre-se de que 0 é um proprietário válido (root), chame clearstatcache() após alterar a propriedade e use posix_getpwuid() quando precisar do nome de usuário legível. No Windows, o resultado não é significativo, portanto, reserve a lógica baseada em proprietário para sistemas do tipo Unix.

Prática