zip_read()

⚠️ Avviso API Legacy: La funzione zip_read() e le relative funzioni zip procedurali sono state rimosse in PHP 8.0. Richiedono l'estensione PECL ext-zip e sono disponibili solo in PHP 7.4 e versioni precedenti. Per le applicazioni PHP moderne si consiglia la classe ZipArchive.

La funzione zip_read() legge la voce successiva (un singolo file o record di directory) da un archivio zip aperto. Fa parte dell'API zip procedurale legacy di PHP, in cui si percorre un archivio una voce alla volta: si apre l'archivio con zip_open(), si chiama zip_read() ripetutamente per avanzare tra le voci, quindi si chiude con zip_close().

Ogni chiamata riuscita restituisce una risorsa zip entry — un handle che si passa alle funzioni zip_entry_* per ispezionare o leggere quella voce. Quando non ci sono altre voci, zip_read() restituisce false, che è ciò che termina il ciclo. In caso di errore restituisce invece il numero di un codice di errore.

Sintassi

La sintassi della funzione zip_read() è la seguente:

Sintassi della funzione zip_read() in PHP

resource|int|false zip_read(resource $zip)

$zip è la risorsa archivio restituita da zip_open(). Il valore restituito è uno dei seguenti:

• una risorsa zip entry — c'è una voce da elaborare;
• false — è stata raggiunta la fine dell'archivio;
• un codice di errore intero — si è verificato un problema durante la lettura dell'archivio.

Perché iterare con zip_read()?

L'API procedurale è un cursore solo in avanti: non esiste una chiamata "elenca tutte le voci". Si legge una voce, si esegue un'operazione con essa (si ottengono il nome e le dimensioni, o si estrae il contenuto), poi si chiede la successiva. Questo mantiene basso l'uso della memoria perché una sola voce è in scope alla volta, ma significa anche che non è possibile saltare a una voce arbitraria — bisogna percorrere dall'inizio.

Esempi d'uso

Esempio: Elenco delle voci in un archivio Zip

Questo ciclo apre un archivio e stampa i metadati di ogni voce che contiene:

Lettura delle voci in un archivio Zip in PHP

$zip = zip_open("example.zip");
if (!is_resource($zip)) {
    throw new RuntimeException("Failed to open zip archive (error code: $zip)");
}
while ($zip_entry = zip_read($zip)) {
    echo "Name: " . zip_entry_name($zip_entry) . "\n";
    echo "Compressed Size: " . zip_entry_compressedsize($zip_entry) . "\n";
    echo "Uncompressed Size: " . zip_entry_filesize($zip_entry) . "\n";
}
zip_close($zip);

Il codice apre example.zip con zip_open(), quindi esegue un ciclo finché zip_read() continua a restituire risorse entry. Per ogni voce stampa il nome con zip_entry_name(), la dimensione compressa con zip_entry_compressedsize() e la dimensione originale con zip_entry_filesize(). Infine zip_close() rilascia l'archivio.

Esempio: Lettura del contenuto di una voce

zip_read() posiziona soltanto il cursore su una voce; per leggere i byte effettivi è necessario aprire la voce con zip_entry_open() e recuperare i dati con zip_entry_read():

$zip = zip_open("example.zip");
if (is_resource($zip)) {
    while ($entry = zip_read($zip)) {
        if (zip_entry_open($zip, $entry, "r")) {
            $contents = zip_entry_read($entry, zip_entry_filesize($entry));
            echo zip_entry_name($entry) . ":\n" . $contents . "\n";
            zip_entry_close($entry);
        }
    }
    zip_close($zip);
}

Problemi comuni

• Veridicità del ciclo. while ($entry = zip_read($zip)) funziona perché una risorsa valida è truthy e false termina il ciclo. Tuttavia anche un codice di errore intero viene restituito in caso di errore — verificare is_resource($zip) dopo zip_open() per non iterare mai su un handle non valido.
• Si può leggere solo in avanti. Non esiste un rewind. Per elaborare di nuovo l'archivio, riaprirlo con zip_open().
• Rimosso in PHP 8. Queste funzioni sono state eliminate in PHP 8.0. Il codice che deve girare su PHP moderno dovrebbe usare invece la classe orientata agli oggetti ZipArchive.

Alternativa moderna: ZipArchive

Con PHP 8 e versioni successive, è possibile iterare un archivio usando la classe ZipArchive. Fornisce anche accesso casuale per indice, cosa che zip_read() non può fare:

$zip = new ZipArchive();
if ($zip->open("example.zip") === true) {
    for ($i = 0; $i < $zip->numFiles; $i++) {
        $stat = $zip->statIndex($i);
        echo "Name: {$stat['name']}\n";
        echo "Compressed Size: {$stat['comp_size']}\n";
        echo "Uncompressed Size: {$stat['size']}\n";
    }
    $zip->close();
}

Consulta la panoramica dell'estensione PHP Zip per l'API completa di ZipArchive.

Conclusione

zip_read() avanza un cursore solo in avanti attraverso le voci di un archivio zip aperto con zip_open(), restituendo una risorsa zip entry ogni volta e false alla fine. È il cuore del ciclo procedurale legacy di lettura zip, abbinato alle funzioni zip_entry_* per ispezionare ed estrarre ogni voce. Poiché questa API è stata rimossa in PHP 8.0, per qualsiasi codice destinato alle versioni attuali di PHP è preferibile usare ZipArchive.

Esercizio