Download the PHP package ntdash/zipstore without Composer

ZIPStore

A PHP library for generating and streaming virtual ZIP archives on-the-fly without consuming disk space. Perfect for constraint environments where storage is limited.

Table of Contents

• Overview
• Key Features
• Important Limitations
• Requirements
• Installation
• Quick Start
  • Basic Usage
  • Advanced Reading
  • Adding Files with Custom Names
  • Handling Duplicates
  • Stream to Output
• Advanced Features
  • Custom Entry File Handlers
  • Seeking Behavior
• Configuration Options
• Architecture
• Examples
  • Simple File Download Server
  • Backup Logs Files
  • ZIP From Database BLOBs
• License

Overview

ZipStore enables you to add files to a virtual ZIP store and then read from it as if it were a native file resource, using familiar seek() and read() operations. The library generates ZIP file components on-demand while reading file contents live, making it ideal for serving large file downloads with minimal memory and disk overhead.

Call open() at any point to capture a snapshot of the store's current entry list into an independent OpenedStore — a seekable read view over the ZIP data as it stood at that moment. The Store itself remains open: you can keep calling addFile() after open(), and those additions will not affect already-taken snapshots. Calling open() multiple times yields independent OpenedStore instances, each with its own cursor, each reflecting the state of the store at the time of that call.

Key Features

• On-the-fly ZIP generation - Components are created during reading, not upfront
• Minimal storage footprint - Perfect for resource-constrained environments
• Native file interface - Use seek() and read() just like file streams
• UTF-8 support - Proper Unicode filename handling
• Pluggable file handlers - Implement custom ZipStoreEntryFile for non-local filesystem sources
• Performance optimized - Lazy loading and caching of ZIP structures
• Standards compliant - Generates valid ZIP files compatible with standard tools
• Zero cleanup - No manual resource management needed

Important Limitations

ZipStore focuses on stream-friendly ZIP generation and does not support:

• File compression (deflate, bzip2, etc.)
• Encryption
• Files larger than 3.75 GiB per entry
• More than 65,535 entries per archive
• Archive file larger than 4 GiB since there is no support for ZIP64 yet

These limitations are by design to keep the library lightweight and performant. For complex ZIP operations, consider using php-zip extension directly.

Requirements

• PHP ≥ 8.1

Installation

Install via Composer:

Quick Start

Basic Usage

Advanced Reading

Adding Files with Custom Names

Handling Duplicates

Control how duplicate entry names are handled:

Stream to Output

Common pattern for sending ZIP to client. open() snapshots the store at this point — call getSize() on the returned OpenedStore to get the exact byte count before streaming begins:

Advanced Features

Custom Entry File Handlers

By default, ZipStore uses the file system to read file contents. You can provide custom implementations of ZipStoreEntryFile to handle non-filesystem sources like database BLOBs, S3 objects, or in-memory streams.

Registering Custom File Handler

Set your custom file handler globally before creating entries:

Important: The custom class must implement both __serialize() and __unserialize() magic methods for proper serialization support.

Seeking Behavior

The OpenedStore::seek() method supports all fseek() behaviors:

Configuration Options

Store Constructor Options

Architecture

Core Components

• Store - Main interface for adding files and opening archives. Call open() at any point to snapshot the current entry list into an OpenedStore; the Store remains open for further additions.
• OpenedStore - Seekable read view over a point-in-time snapshot of a Store. Each call to Store::open() returns an independent instance with its own cursor position.
• Entry - Represents a single file in the archive
• LocalHeader - ZIP local file header structure
• CentralDirectory - ZIP central directory (file index)
• EndOfCentralDirectory - ZIP End of Central Directory record
• ZipStoreEntryFile - Interface for custom file sources

Examples

Simple File Download Server

Backup Logs Files

ZIP From Database BLOBs

License

This project is licensed under the MIT License - see the LICENSE file for details.