PHP Toolkit

Zip

Read and write ZIP archives without libzip or ZipArchive. Stored entries are pure PHP; Deflate entries use PHP's zlib functions. Entries stream one at a time, while ZIP metadata such as the central directory is still held in memory.

composer require wp-php-toolkit/zip

Common PHP ZIP workflows rely on the ZipArchive extension or shelling out to zip. Those are awkward in hosts without libzip, WebAssembly builds, and code paths that need to stream archive data through toolkit byte streams.

The Zip component reads and writes Stored and Deflate archives without ZipArchive. The decoder is pull-based for entry bodies, but ZipFilesystem indexes the central directory in memory and currently rejects archives whose central directory exceeds 2 MB. The encoder accepts any ByteWriteStream as a sink and writes one entry at a time.

Read a file out of a ZIP

ZipFilesystem implements this toolkit's Filesystem interface, so once you wrap the byte reader you can call get_contents(), ls(), and is_dir() just like the other read backends.

Try this: after Run, add a second append_file() call before $enc->close() for a notes.md entry, then call print_r( $zip->ls( '/' ) ) at the end. The directory listing reflects the new entry without re-reading the file.

Build an EPUB from scratch

An EPUB follows one strict ZIP rule: write the mimetype entry first and store it without compression. Deflate the rest of the archive normally.

XML, ) as $name => $body ) { $enc->append_file( new FileEntry( array( 'path' => $name, 'compression_method' => ZipDecoder::COMPRESSION_DEFLATE, 'body_reader' => new MemoryPipe( $body ), ) ) ); } $enc->close(); $out->close_writing(); $zip = ZipFilesystem::create( FileReadStream::from_path( $path ) ); printf( "mimetype: %s\n", $zip->get_contents( 'mimetype' ) ); printf( "size on disk: %d bytes\n", filesize( $path ) );

Stream a large entry without buffering it

Calling get_contents() on a 500 MB CSV inside a ZIP would eat 500 MB of RAM. Use open_read_stream() instead and inflate-as-you-go.

Repack: modify one file, copy the rest

Updating one file in a ZIP without rewriting the others is impossible at the format level — the central directory points at byte offsets. The pragmatic answer is repack: stream the source archive into a new one, swapping the file you care about.

Defend against zip-slip

A malicious archive can name an entry ../../etc/passwd and trick a naive extractor into clobbering files outside the destination. ZipDecoder::sanitize_path() normalizes slashes and strips leading traversal segments before exposing the path. Treat it as one layer of defense; still extract through a chrooted filesystem target.

Pipe ZIP entries into an InMemoryFilesystem

Real-world recipe: take an uploaded plugin ZIP, expand it into an InMemoryFilesystem so you can validate, edit, or scan it before it ever touches disk. Three components compose into something you couldn't build with ZipArchive alone.

When to use which type

UseFor
ZipFilesystem::create()Reading. You want get_contents(), ls(), is_dir() over a ZIP. The most common case.
ZipEncoderWriting. Stream entries into any ByteWriteStream sink. Required when format rules matter (EPUB, .docx).
ZipDecoderLow-level read access to the central directory and individual entry headers. Most code reaches for ZipFilesystem instead.
open_read_stream() on a ZipFilesystemInflating a single large entry without buffering it whole in memory.
copy_between_filesystems()Moving entries from a ZIP into another filesystem (memory, local, SQLite).

Pitfalls

See also