is_resource()

Introduzione

is_resource() è una funzione built-in di PHP che verifica se una variabile contiene una risorsa. Una risorsa è un tipo speciale di PHP che funge da handle verso qualcosa che vive al di fuori di PHP stesso — un file aperto, una connessione a un database, un socket di rete o un'immagine in fase di costruzione in memoria. Non è possibile ispezionare direttamente il valore di una risorsa come si farebbe con una string o un array; la si può solo passare alle funzioni che sanno come utilizzarla (fread(), fclose() e così via).

is_resource() restituisce true quando la variabile è una risorsa aperta e false per qualsiasi altro tipo, inclusa una risorsa che è già stata chiusa. Questa pagina tratta la sintassi, il comportamento a runtime, l'importante modifica introdotta in PHP 8 che è necessario conoscere e il suo rapporto con le altre funzioni di controllo del tipo.

Sintassi

is_resource(mixed $value): bool

Accetta un singolo argomento — la variabile da testare — e restituisce un boolean. Non genera mai eccezioni e non modifica mai il suo argomento, quindi è sicura da chiamare su qualsiasi valore.

Esempio d'uso

Un handle di file restituito da fopen() è la risorsa più comune che si incontra:

<?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);
?>

Usare var_dump() anziché echo è consigliato: un true con echo viene visualizzato come 1, ma un false viene visualizzato come stringa vuota, il che è facile da fraintendere. var_dump() stampa il tipo e il valore in modo inequivocabile.

Una risorsa chiusa non è più una risorsa

Questo è l'errore più comune. Una volta chiuso un handle, is_resource() restituisce false per esso — non rimane true. Questo rende la funzione un comodo controllo preventivo per evitare di usare un handle due volte:

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

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

Proteggere con is_resource() prima di un fwrite() o di un secondo fclose() previene gli avvisi "supplied resource is not a valid stream resource".

La modifica di PHP 8: molte risorse sono ora oggetti

In PHP 8.0, molte estensioni built-in sono state migrate dalle risorse agli oggetti opachi. Gli handle Curl, le immagini GD e varie altre ex-risorse sono ora oggetti, quindi is_resource() restituisce false per loro anche se si comportano concettualmente allo stesso modo:

<?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 si mantiene codice che gira sia su PHP 7 che su PHP 8, non dare per scontato che un handle curl o GD sia una risorsa. Verificare il tipo specifico atteso, oppure accettare entrambi con is_resource($x) || is_object($x).

Scoprire che tipo di risorsa si ha

Quando is_resource() è true, get_resource_type() indica di che tipo si tratta — "stream" per i file, "curl" su PHP 7, "gd" per le immagini, e così via:

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

Quando si usa?

• Controlli preventivi. Prima di chiamare fread(), fwrite() o fclose() su un valore non creato direttamente, confermare che sia ancora una risorsa aperta.
• Funzioni che accettano "un handle o un percorso". Un helper potrebbe accettare sia una string con il nome del file sia un handle già aperto; is_resource() consente di distinguere i due casi.
• Logica di pulizia. In un blocco finally o in un distruttore, if (is_resource($h)) fclose($h); evita di chiudere un handle due volte.

Funzioni correlate

is_resource() fa parte della famiglia di predicati di controllo del tipo di PHP. Per altri tipi, usare is_object(), is_array() o is_string(). Se si vuole il nome del tipo come string anziché un test boolean, usare gettype(), che restituisce "resource" (o "resource (closed)") per gli handle.

Conclusione

is_resource() verifica che una variabile sia un handle aperto verso una risorsa esterna, restituendo false per gli handle chiusi e per qualsiasi altro tipo. La cosa più importante da ricordare nel PHP moderno è che a partire da PHP 8 molte ex-risorse — tra cui gli handle curl e GD — sono oggetti, quindi è necessario testare con is_object() (o verificare entrambi) quando il codice è destinato a PHP 8+.

Esercitazione