clue/tar-react

Streaming parser to extract tarballs with ReactPHP.

v0.2.0 2019-09-09 18:32 UTC

Requires

• php: >=5.3
• react/stream: ^1.0 || ^0.7

Requires (Dev)

• clue/hexdump: ~0.2.0
• phpunit/phpunit: ^7.0 || ^6.0 || ^5.0 || ^4.8.35
• react/event-loop: ^1.0 || ^0.5 || ^0.4 || ^0.3

MIT

• Christian Lück

• parser
• decoder
• async
• extract
• archive
• tar
• reactphp
• unpack
• tarball
• untar

README

Streaming parser to extract tarballs with ReactPHP.

The TAR file format is a common archive format to store several files in a single archive file (commonly referred to as "tarball" with a .tar extension). This lightweight library provides an efficient implementation to extract tarballs in a streaming fashion, processing one chunk at a time in memory without having to rely on disk I/O.

Table of Contents

• Quickstart example
• Install
• Tests
• License
• More

Note: This project is in beta stage! Feel free to report any issues you encounter.

Quickstart example

Once installed, you can use the following code to pipe a readable tar stream into the TarDecoder which emits "entry" events for each individual file:

<?php

require __DIR__ . '/vendor/autoload.php';

$stream = new React\Stream\ReadableResourceStream(fopen('archive.tar', 'r'));

$decoder = new Clue\React\Tar\TarDecoder();

$decoder->on('entry', function (array $header, React\Stream\ReadableStreamInterface $file) {
    echo 'File ' . $header['filename'];
    echo ' (' . $header['size'] . ' bytes):' . PHP_EOL;

    $file->on('data', function ($chunk) {
        echo $chunk;
    });
});

$stream->pipe($decoder);

See also the examples.

Install

The recommended way to install this library is through Composer. New to Composer?

While in beta, this project does not currently follow SemVer. This will install the latest supported version:

composer require clue/tar-react:^0.2

See also the CHANGELOG for details about version upgrades.

This project aims to run on any platform and thus does not require any PHP extensions and supports running on legacy PHP 5.3 through current PHP 8+. It's highly recommended to use the latest supported PHP version for this project.

Tests

To run the test suite, you first need to clone this repo and then install all dependencies through Composer:

composer install

To run the test suite, go to the project root and run:

vendor/bin/phpunit

License

This project is released under the permissive MIT license.

Did you know that I offer custom development services and issuing invoices for sponsorships of releases and for contributions? Contact me (@clue) for details.

More

• If you want to learn more about processing streams of data, refer to the documentation of the underlying react/stream component.

• If you want to process compressed tarballs (.tar.gz and .tgz file extension), you may want to use clue/reactphp-zlib on the compressed input stream before passing the decompressed stream to the tar decoder.