is_resource()

Introdução

is_resource() é uma função PHP nativa que verifica se uma variável contém um recurso. Um recurso é um tipo especial do PHP que age como um identificador para algo que existe fora do próprio PHP — um arquivo aberto, uma conexão com banco de dados, um socket de rede ou uma imagem sendo construída na memória. Você não pode inspecionar o valor de um recurso diretamente como faz com uma string ou um array; só pode passá-lo para as funções que sabem como usá-lo (fread(), fclose(), e assim por diante).

is_resource() retorna true quando a variável é um recurso aberto e false para qualquer outro tipo, incluindo um recurso que já foi fechado. Esta página aborda a sintaxe, o comportamento em tempo de execução, a importante mudança do PHP 8 que você precisa conhecer e como ela se relaciona com as demais funções de verificação de tipo.

Sintaxe

is_resource(mixed $value): bool

Recebe um único argumento — a variável que você deseja testar — e retorna um boolean. Nunca lança exceções e nunca modifica seu argumento, portanto é seguro chamá-la com qualquer valor.

Exemplo de Uso

Um identificador de arquivo retornado por fopen() é o recurso mais comum que você encontrará:

<?php
$handle = fopen("php://temp", "r"); // a real, open resource
$text   = "hello";                  // a plain string

var_dump(is_resource($handle)); // bool(true)
var_dump(is_resource($text));   // bool(false)

fclose($handle);
?>

Use var_dump() em vez de echo aqui: um true é exibido como 1, mas um false é exibido como uma string vazia, o que pode ser facilmente mal interpretado. var_dump() imprime o tipo e o valor de forma inequívoca.

Um recurso fechado deixa de ser um recurso

Esta é a armadilha que confunde as pessoas. Depois de fechar um handle, is_resource() retorna false para ele — ele não permanece true. Isso torna a função um guarda conveniente contra o uso de um handle duas vezes:

<?php
$handle = fopen("php://temp", "w");
var_dump(is_resource($handle)); // bool(true)

fclose($handle);
var_dump(is_resource($handle)); // bool(false) — already closed
?>

Usar is_resource() como guarda antes de um fwrite() ou de um segundo fclose() evita os avisos "supplied resource is not a valid stream resource".

A mudança do PHP 8: muitos recursos agora são objetos

No PHP 8.0, um grande número de extensões nativas foi migrado de recursos para objetos opacos. Handles do Curl, imagens GD e vários outros antigos recursos agora são objetos, portanto is_resource() retorna false para eles, mesmo que conceitualmente se comportem da mesma forma:

<?php
$ch = curl_init();          // PHP 7: a resource — PHP 8: a CurlHandle object
var_dump(is_resource($ch)); // bool(false) on PHP 8+
var_dump(is_object($ch));   // bool(true)  on PHP 8+
?>

Se você mantém código que roda tanto no PHP 7 quanto no PHP 8, não presuma que um handle do curl ou GD é um recurso. Verifique o tipo específico que você espera, ou aceite ambos com is_resource($x) || is_object($x).

Descobrindo qual tipo de recurso você tem

Quando is_resource() é true, get_resource_type() informa qual é o tipo — "stream" para arquivos, "curl" no PHP 7, "gd" para imagens, e assim por diante:

<?php
$handle = fopen("php://temp", "r");
echo get_resource_type($handle), "\n"; // stream
fclose($handle);
?>

Quando devo usá-la?

• Guardas defensivos. Antes de chamar fread(), fwrite() ou fclose() em um valor que você mesmo não criou, confirme que ainda é um recurso aberto.
• Funções que aceitam "um handle ou um caminho". Um helper pode receber tanto uma string com o nome do arquivo quanto um handle já aberto; is_resource() permite ramificar com base no que foi recebido.
• Lógica de limpeza. Em um bloco finally ou destrutor, if (is_resource($h)) fclose($h); evita fechar um handle duas vezes.

Funções relacionadas

is_resource() faz parte da família de predicados de verificação de tipo do PHP. Para outros tipos, use is_object(), is_array() ou is_string(). Se você quiser o nome do tipo como string em vez de um teste boolean, use gettype(), que retorna "resource" (ou "resource (closed)") para handles.

Conclusão

is_resource() confirma que uma variável é um handle aberto para um recurso externo, retornando false para handles fechados e para qualquer outro tipo. O ponto mais importante a lembrar no PHP moderno é que, desde o PHP 8, muitos antigos recursos — entre eles handles do curl e GD — são objetos, portanto use is_object() (ou verifique ambos) quando seu código for direcionado ao PHP 8+.

Prática