is_readable()

A função is_readable() informa se o PHP consegue ler um determinado arquivo ou diretório antes de você tentar abri-lo. Ela verifica se o caminho existe e se o processo atual tem permissão de leitura. Chamá-la antecipadamente permite que você falhe de forma controlada em vez de acionar um aviso em tempo de execução do fopen() ou do file_get_contents().

Este capítulo aborda a sintaxe, o valor de retorno, um exemplo executável, as armadilhas mais comuns (cache, permissões, condições de corrida) e como is_readable() se relaciona com as outras funções de sistema de arquivos do PHP.

Sintaxe

is_readable(string $filename): bool

is_readable() também funciona em diretórios: retorna true quando o diretório pode ser aberto e listado.

Exemplo básico

A função retorna um boolean, por isso se encaixa naturalmente dentro de uma condição if: você ramifica dependendo de se o arquivo pode ser lido sem nunca precisar abri-lo.

Um exemplo completo e executável

O exemplo acima aponta para um caminho que pode não existir. Aqui está uma versão que você pode executar em qualquer lugar — ela cria um arquivo, verifica-o e depois verifica um caminho que não existe:

<?php

// Create a temp file we know is readable.
$file = tempnam(sys_get_temp_dir(), 'demo');
file_put_contents($file, 'hello');

var_dump(is_readable($file));            // bool(true)
var_dump(is_readable('/no/such/file'));  // bool(false)

unlink($file); // clean up

A primeira chamada retorna true porque o arquivo existe e acabamos de criá-lo com nossas próprias permissões; a segunda retorna false porque o caminho simplesmente não existe.

Protegendo uma leitura de arquivo

O uso típico no mundo real é como uma guarda antes da leitura, para que um arquivo ausente ou ilegível não emita um aviso:

<?php

$path = 'config.json';

if (!is_readable($path)) {
    // Handle the problem your way: log, default, or throw.
    throw new RuntimeException("Cannot read config file: $path");
}

$config = json_decode(file_get_contents($path), true);

Armadilhas comuns

• Os resultados são armazenados em cache. O PHP armazena em cache informações de stat por requisição. Se você alterar as permissões de um arquivo durante a mesma execução do script, chame clearstatcache() antes de verificar novamente, ou poderá ver uma resposta desatualizada.
• true não é uma garantia. As permissões podem mudar entre a verificação e a leitura real (uma condição de corrida time-of-check to time-of-use). Para código crítico, tente simplesmente realizar a leitura e trate o erro, em vez de depender apenas de is_readable().
• Retorna false para caminhos inexistentes — sem emitir aviso. Assim, is_readable() também serve como verificação de "isso existe e posso lê-lo". Para testar a existência independentemente das permissões, use file_exists().
• As permissões são avaliadas para o usuário do servidor web (geralmente www-data), não para o usuário do seu shell, quando o script é executado em um servidor web.

Funções relacionadas

• is_writable() — a contraparte para permissão de escrita.
• is_file() — verifica se o caminho é um arquivo regular (não um diretório).
• file_exists() — verifica a existência, ignorando a permissão de leitura.
• fopen() e file_get_contents() — as funções que você normalmente protege com is_readable().

Conclusão

is_readable() é uma forma leve e sem efeitos colaterais de verificar se um caminho existe e pode ser lido antes de você abri-lo. Use-a como guarda para falhar de forma controlada, lembre-se de que seus resultados são armazenados em cache dentro de uma requisição e, para código crítico de segurança, tente a leitura e trate os erros em vez de confiar apenas na verificação.

Prática