is_writeable()

O que a Função is_writable() Faz

A função is_writable() é uma função interna do PHP que verifica se um determinado caminho existe e pode ser gravado pelo processo atual. Ela funciona tanto para arquivos quanto para diretórios. Retorna true quando o caminho existe e é gravável, e false caso contrário — incluindo quando o caminho não existe.

Esta página aborda a sintaxe, o valor de retorno, usos práticos comuns e as armadilhas (cache, links simbólicos, root e a grafia obsoleta is_writeable()) que costumam confundir as pessoas.

is_writeable() vs is_writable()

is_writeable() (com o e extra) é um alias antigo de is_writable(). Foi descontinuado no PHP 5.0.0 e removido no PHP 8.0.0, onde chamá-lo agora gera um Error fatal. Sempre use a grafia canônica is_writable() em código moderno.

Sintaxe

is_writable(string $filename): bool

Valor de retorno: true se $filename existir e for gravável; caso contrário, false. Um caminho inexistente retorna false em vez de gerar um erro.

Exemplo Básico

A função retorna um booleano, portanto encaixa diretamente em uma condição if. Aqui a mensagem depende de o processo que executa o script ter permissão de escrita em /path/to/file.

Um Padrão de Escrita Seguro

O uso mais comum é proteger uma operação de escrita para que seu script falhe graciosamente em vez de travar com um aviso de permissão:

<?php

$logFile = __DIR__ . '/app.log';

if (is_writable($logFile)) {
    file_put_contents($logFile, "Started at " . date('c') . "\n", FILE_APPEND);
    echo "Log entry written.";
} else {
    echo "Cannot write to $logFile — check permissions.";
}

Note que is_writable() verifica um caminho existente. Se o arquivo ainda não existir, normalmente você deve testar o diretório que o conterá, pois criar um novo arquivo requer permissão de escrita no diretório pai:

<?php

$target = __DIR__ . '/cache/data.json';

if (is_writable(dirname($target))) {
    file_put_contents($target, '{}');
    echo "File created.";
} else {
    echo "The cache directory is not writable.";
}

Pontos de Atenção

• Os resultados são armazenados em cache. O PHP armazena metadados do sistema de arquivos via stat cache. Se você alterar permissões durante um script (por exemplo com chmod()) e verificar o mesmo caminho novamente, chame clearstatcache() primeiro para obter um resultado atualizado.
• Ele testa o dono do processo, não o seu login. Um caminho gravável no seu terminal pode não ser gravável para o usuário do servidor web (www-data, nginx, etc.) que realmente executa o PHP.
• Executando como root. O superusuário pode gravar quase em qualquer lugar, portanto is_writable() pode retornar true mesmo em arquivos marcados como somente leitura. Não confie nele como limite de segurança.
• Links simbólicos são seguidos. A verificação se aplica ao alvo de um link simbólico, não ao próprio link.
• Condições de corrida (TOCTOU). Um caminho pode se tornar não gravável entre a verificação e a escrita real. Para escritas críticas, tente a operação e trate a falha em vez de depender apenas da verificação.

<?php

chmod('/tmp/example.txt', 0644);
var_dump(is_writable('/tmp/example.txt')); // may show stale value
clearstatcache();                          // refresh the stat cache
var_dump(is_writable('/tmp/example.txt')); // now reflects the new permissions

Funções Relacionadas

• is_readable() — verifica se um caminho pode ser lido.
• file_exists() — verifica apenas se um caminho existe.
• is_file() e is_dir() — distinguem arquivos de diretórios.
• chmod() — altera as permissões de um caminho.
• file_put_contents() e fwrite() — as operações de escrita que você normalmente protege com is_writable().

Conclusão

is_writable() permite verificar, antes de gravar, se um arquivo ou diretório pode ser gravado pelo processo atual — retornando false para caminhos inexistentes em vez de lançar uma exceção. Lembre-se de verificar o diretório pai ao criar novos arquivos, de chamar clearstatcache() após alterar permissões no meio do script, e de usar a grafia canônica, já que is_writeable() foi removido no PHP 8.

Prática