is_executable()

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

is_executable() é uma função built-in do PHP que informa se um arquivo existe e pode ser executado como programa pelo processo atual. Ela retorna true somente quando ambas as condições são satisfeitas; caso contrário, retorna false.

"Executável" aqui significa que o sistema operacional permitiria a execução do arquivo — por exemplo, um shell script, um binário compilado, ou um .exe no Windows. Um arquivo de texto comum ou um arquivo-fonte .php normalmente não é executável, mesmo que o PHP possa lê-lo.

Esta página aborda a sintaxe, o que o valor de retorno realmente significa, como a verificação difere entre sistemas operacionais e as armadilhas (cache, arquivos ausentes, bits de permissão) que costumam causar problemas.

Sintaxe

is_executable(string $filename): bool

Valor de retorno — true se o arquivo existe e é executável, false caso contrário. O PHP também emite um E_WARNING se o caminho for inválido (por exemplo, se um diretório no caminho não puder ser percorrido).

Um Exemplo Básico

A função retorna um booleano, então pode ser usada diretamente em uma condição if. Aqui apontamos para o binário do PHP; em um servidor Linux típico, esse caminho é executável e o primeiro ramo é executado. O caminho exato varia por sistema, por isso o próximo exemplo cria um arquivo que controlamos completamente.

Criando e Testando um Arquivo

A verificação é mais significativa quando você controla os bits de permissão do arquivo. O exemplo abaixo escreve um pequeno shell script, marca-o como executável com chmod() e confirma o resultado:

<?php

$script = sys_get_temp_dir() . '/hello.sh';
file_put_contents($script, "#!/bin/sh\necho hi\n");

// Before chmod: readable but not executable.
var_dump(is_executable($script)); // bool(false)

chmod($script, 0755);             // owner rwx, group/other r-x
clearstatcache();                 // forget the cached result

var_dump(is_executable($script)); // bool(true)

unlink($script);

Duas coisas a observar:

• O arquivo não é executável até que o bit de permissão de execução seja definido, mesmo que já existisse e fosse legível.
• Após alterar as permissões, você deve chamar clearstatcache() (veja abaixo).

Consulte chmod() para entender como o modo octal 0755 mapeia as permissões de proprietário/grupo/outros.

A Armadilha do Cache de Stat

O PHP armazena em cache o resultado das chamadas stat do sistema de arquivos (usadas por is_executable(), is_readable(), is_writable(), file_exists() e similares) por motivos de desempenho. Se você alterar as permissões de um arquivo durante a mesma requisição e depois verificá-lo novamente, poderá obter a resposta desatualizada:

<?php

$file = sys_get_temp_dir() . '/cache-demo';
touch($file);

is_executable($file);   // result is now cached for this path

chmod($file, 0755);
var_dump(is_executable($file)); // may still report the OLD value

clearstatcache();
var_dump(is_executable($file)); // bool(true) — fresh check

unlink($file);

Chame clearstatcache() após qualquer chmod(), chown(), rename() ou unlink() se você pretende testar novamente o mesmo caminho na mesma execução.

Comportamento Entre Sistemas Operacionais

• Linux / macOS — o resultado segue o bit de execução Unix (x) para a classe de usuário/grupo/outros relevante. Um arquivo com modo 0644 não é executável; 0755 é.
• Windows — não há bit de permissão de execução. O PHP infere "executável" a partir da extensão do arquivo: caminhos terminados em .exe, .bat, .cmd ou .com são tratados como executáveis. Antes do PHP 7.4, is_executable() sempre retornava false no Windows, portanto, teste na sua versão alvo.

Por causa dessas diferenças, nunca assuma que um script que retorna true no Linux fará o mesmo no Windows, ou vice-versa.

Quando Usaria Isso?

• Antes de executar um programa externo com exec(), shell_exec() ou proc_open() — verifique se o binário é realmente executável e forneça um erro claro caso não seja, em vez de falhar dentro da chamada.
• Deploy / verificações de saúde — confirme que um script auxiliar (um cron job, um hook de build) tem as permissões corretas após ser copiado ou obtido do controle de versão, onde o bit de execução às vezes é perdido.
• Controle de segurança — combinado com um caminho fixo, recuse executar qualquer coisa que não seja um executável conhecido e com permissões adequadas.

Funções Relacionadas

is_executable() pertence a uma família de verificações de permissão/tipo — escolha a que corresponde à pergunta que você está fazendo:

• is_file() — o caminho é um arquivo regular (não um diretório)?
• is_dir() — o caminho é um diretório?
• is_readable() — o arquivo pode ser lido?
• is_writable() — o arquivo pode ser escrito?
• file_exists() — o caminho existe (arquivo ou diretório)?
• fileperms() — lê os bits de permissão brutos.
• chmod() — altera os bits de permissão de um arquivo.

Conclusão

is_executable() retorna true somente quando um arquivo existe e possui permissão de execução para o processo atual. Lembre-se de três coisas: o resultado é dependente do SO (bit de execução Unix vs. extensão do Windows), é armazenado em cache via stat então chame clearstatcache() após alterar permissões, e é mais útil como guarda antes de executar programas externos.

Prática