README

Tony Kinghorn / Western Cliffs of Mingulay / CC BY-SA 2.0

Overview

Mingulay is a PHP library for parsing file information out of Zip files. It searches for the End of Central Directory Record, parses out the data, and then uses this to retrieve the Central Directory Records which contain the metadata of the files in the Zip.

What's in a name?

Mingulay is an island in the Hebrides, an archipelago off the west coast of my home country of Scotland, and so it seemed a fitting pick as this library was developed as a contribution towards the fantastic Archipelago project (GitHub).

Installation

Mingulay can be installed via Composer: composer require digitaldogsbody/mingulay or alternatively you can clone the repo or download a zip from the releases page and include the contents of src/ in your project.

Documentation

Some basic autogenerated PHPDoc documentation is available on GitHub pages: https://digitaldogsbody.github.io/mingulay/. This is automatically updated every time a commit is made to the main branch, and so should always be up-to-date with the latest code.

Versioning

Mingulay follows Semantic Versioning practices. Until release 1.0.0, the interfaces and functionality should be considered unstable and likely to change.

Usage

Mingulay requires an object that implements the Mingulay\SeekerInterface interface. A LocalFileSeeker implementation is provided for working with Zip files on disk.

$seeker = new \Mingulay\Seeker\LocalFileSeeker("test/fixtures/single-file.zip");
$zip_info = new \Mingulay\ZipRangeReader($seeker);
var_dump($zip_info->files);

array(1) {
  'README.md'=>
  array(6) {
    ["file_name"]=>
    string(9) "README.md"
    ["offset"]=>
    int(0)
    ["compressed_size"]=>
    int(43)
    ["uncompressed_size"]=>
    int(43)
    ["CRC32"]=>
    string(8) "C6E036CC"
    ["comment"]=>
    string(0) ""
  }
}

Pointers to retrieve individual decompressed files can be acquired with the getStream() function:

$seeker = new \Mingulay\Seeker\LocalFileSeeker("test/fixtures/multiple-files.zip");
$zip_info = new \Mingulay\ZipRangeReader($seeker);
$fp = $zip_info->getStream("LICENSE");
$local_fp = fopen("/tmp/example", "wb");
while(!feof($fp)) {
    fwrite($local_fp, fread($fp, 2048));
}
fclose($local_fp);
fclose($fp);

Acknowledgements and thanks

• The Webrecorder team's wabac.js. The initial inspiration for this library was an implementation of their Zip Range Reader class in PHP.
• Jonatan Männchen's ZipStream-PHP library.
• Diego, Allison, Albert, the rest of the METRO crew, and all the Archipelago Community for the discussions, ideas and support.

License

AGPL-3