zip_read()

⚠️ Aviso de API Legada: A função zip_read() e as funções zip procedurais relacionadas foram removidas no PHP 8.0. Elas exigem a extensão PECL ext-zip e estão disponíveis apenas no PHP 7.4 e versões anteriores. Para aplicações PHP modernas, recomenda-se a classe ZipArchive.

A função zip_read() lê a próxima entrada (um único arquivo ou registro de diretório) de um arquivo zip aberto. Ela faz parte da API zip procedural legada do PHP, onde você percorre um arquivo uma entrada por vez: abre o arquivo com zip_open(), chama zip_read() repetidamente para avançar pelas entradas e, em seguida, fecha-o com zip_close().

Cada chamada bem-sucedida retorna um recurso de entrada zip — um identificador que você passa para as funções zip_entry_* para inspecionar ou ler essa entrada. Quando não há mais entradas, zip_read() retorna false, encerrando o loop. Em caso de falha, retorna o número de um código de erro.

Sintaxe

A sintaxe da função zip_read() é a seguinte:

Sintaxe da função zip_read() em PHP

resource|int|false zip_read(resource $zip)

$zip é o recurso de arquivo retornado por zip_open(). O valor de retorno é um dos seguintes:

• um recurso de entrada zip — há uma entrada a processar;
• false — o fim do arquivo foi atingido;
• um código de erro inteiro — algo deu errado ao ler o arquivo.

Por que iterar com zip_read()?

A API procedural é um cursor de avanço único: não existe uma chamada "listar todas as entradas". Você lê uma entrada, faz algo com ela (obtém seu nome e tamanhos, ou extrai seu conteúdo) e então solicita a próxima. Isso mantém o uso de memória baixo, pois apenas uma entrada está no escopo por vez, mas também significa que você não pode saltar para uma entrada arbitrária — é necessário percorrer desde o início.

Exemplos de Uso

Exemplo: Listando as Entradas em um Arquivo Zip

Este loop abre um arquivo e imprime metadados de cada entrada que ele contém:

Lendo as Entradas em um Arquivo Zip em 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);

O código abre example.zip com zip_open(), depois faz um loop enquanto zip_read() continua retornando recursos de entrada. Para cada entrada, imprime o nome com zip_entry_name(), o tamanho armazenado com zip_entry_compressedsize() e o tamanho original com zip_entry_filesize(). Por fim, zip_close() libera o arquivo.

Exemplo: Lendo o Conteúdo de uma Entrada

zip_read() apenas posiciona você em uma entrada; para ler os bytes reais, você deve abrir a entrada com zip_entry_open() e extrair dados com 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);
}

Armadilhas Comuns

• Valor verdadeiro do loop. while ($entry = zip_read($zip)) funciona porque um recurso válido é verdadeiro e false encerra o loop. Mas um código de erro inteiro também é retornado em caso de falha — verifique is_resource($zip) após zip_open() para nunca iterar sobre um identificador inválido.
• Só é possível avançar. Não há como retroceder. Para processar o arquivo novamente, reabra-o com zip_open().
• Removido no PHP 8. Essas funções foram excluídas no PHP 8.0. O código que precisa rodar no PHP moderno deve usar a classe orientada a objetos ZipArchive.

Alternativa Moderna: ZipArchive

No PHP 8 e versões posteriores, itere por um arquivo com a classe ZipArchive. Ela também oferece acesso aleatório por índice, o que zip_read() não permite:

$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();
}

Consulte a visão geral da extensão Zip do PHP para a API completa do ZipArchive.

Conclusão

zip_read() avança um cursor de avanço único pelas entradas de um arquivo zip aberto com zip_open(), retornando um recurso de entrada zip a cada vez e false ao final. É o núcleo do loop procedural legado de leitura de zip, combinado com as funções zip_entry_* para inspecionar e extrair cada entrada. Como essa API foi removida no PHP 8.0, prefira ZipArchive para qualquer código destinado a versões atuais do PHP.

Prática