is_writable()

A função PHP is_writable() informa, antes de tentar escrever, se o processo atual tem permissão para gravar em um determinado arquivo ou diretório. Esta página aborda sua sintaxe, valor de retorno, o comportamento de cache que costuma surpreender desenvolvedores e os padrões práticos para usá-la com segurança.

O que é a Função is_writable()?

is_writable() é uma função PHP integrada que retorna true se o arquivo (ou diretório) informado existe e é gravável pelo usuário sob o qual o processo PHP está sendo executado, e false caso contrário. A função aceita um argumento e não realiza nenhuma gravação — apenas informa a permissão.

A verificação é baseada no ID de usuário efetivo do processo em execução (por exemplo, www-data no Apache/Nginx-FPM), não no usuário proprietário do script. Um arquivo que você consegue editar no seu editor pode ainda ser reportado como não gravável para o servidor web.

is_writable() possui um alias, is_writeable() (com um e extra); os dois são idênticos.

Sintaxe

is_writable(string $filename): bool

Retorna true em caso de sucesso, false se o caminho não for gravável ou não existir.

Como Usar a Função is_writable()

O padrão típico é "verificar antes de agir" — confirmar que um arquivo é gravável antes de tentar abri-lo para escrita, para que você possa falhar com uma mensagem clara em vez de receber um aviso em tempo de execução.

Como o sandbox do executor cria data.txt, o exemplo acima imprime The file 'data.txt' is writable.

Um exemplo completo e executável

Este script autocontido cria um arquivo, verifica-o e só grava quando a verificação é bem-sucedida:

<?php

$file = 'log.txt';

// Create the file so the example is reproducible.
file_put_contents($file, "first line\n");

if (is_writable($file)) {
    file_put_contents($file, "second line\n", FILE_APPEND);
    echo "Wrote to $file:\n";
    echo file_get_contents($file);
} else {
    echo "Cannot write to $file.";
}

Saída:

Wrote to log.txt:
first line
second line

Verificando um diretório

is_writable() também funciona em diretórios. Esta é a verificação correta antes de criar um novo arquivo: você não pode testar o arquivo (ele ainda não existe), portanto testa a pasta que irá contê-lo.

<?php

$dir = __DIR__; // the directory this script lives in

if (is_writable($dir)) {
    echo "New files can be created in: $dir";
} else {
    echo "Directory is read-only: $dir";
}

Armadilhas Comuns

• Não lança exceção — emite aviso. Se $filename for inválido de uma forma que o PHP não consegue resolver (por exemplo, uma violação de open_basedir), o PHP pode emitir um E_WARNING. O valor de retorno ainda será false. Use @ para suprimir apenas como último recurso.
• Os resultados podem ser armazenados em cache. O PHP mantém um cache de stat. Se as permissões de um arquivo mudarem durante a mesma execução do script, is_writable() pode retornar um resultado desatualizado. Chame clearstatcache() antes de verificar novamente para forçar o PHP a reler o sistema de arquivos.
• false é ambíguo. Um resultado false significa "não gravável ou não existe." Se precisar distinguir os dois casos, combine com file_exists().
• Condição de corrida TOCTOU. Entre a verificação com is_writable() e a gravação efetiva, as permissões do arquivo podem mudar. Para código crítico, não confie apenas na verificação — trate também a falha da própria operação de escrita.

Quando você altera permissões durante o script e verifica novamente, limpe o cache primeiro:

<?php

$file = 'config.ini';
file_put_contents($file, "data\n");

var_dump(is_writable($file)); // bool(true)

chmod($file, 0444);  // make it read-only
clearstatcache();    // force PHP to re-read the filesystem
var_dump(is_writable($file)); // bool(false)

Saída:

bool(true)
bool(false)

Funções Relacionadas

• is_readable() — o equivalente para verificar permissão de leitura.
• file_exists() — verifica a existência sem checar permissões.
• is_file() — confirma se um caminho é um arquivo regular.
• fopen() / fwrite() — abrir e gravar em arquivos após a verificação.
• chmod() — altera os bits de permissão de um arquivo.

Conclusão

is_writable() permite que seu script confirme o acesso de escrita antecipadamente e falhe graciosamente em vez de disparar avisos em tempo de execução. Lembre-se das três peculiaridades: ela reflete as permissões do usuário do processo, false também significa "inexistente" e seus resultados são armazenados em cache até que você chame clearstatcache(). Combine-a com o tratamento de erros da gravação real para um código de arquivo robusto.

Prática