guest-one/php-tar-streamer

TarStreamer — stream-based tar processor

1.3.0 2025-09-15 19:02 UTC

Requires

• php: ^7.4|^8.0|^8.1|^8.2|^8.3|^8.4

Requires (Dev)

• phpunit/phpunit: 9.6.26

Suggests

• ext-bz2: For tar.bz2
• ext-xz: For tar.xz
• ext-zlib: For tar.gz

MIT

• Eugene Popov

• stream
• pack
• extract
• archive
• tar
• unpack

README

This library was created to solve folowing problems:

• Working with very large (gigabytes) tar archives on limited RAM.
• Processing archives coming via unix pipes.

Usage

Installing:

composer require guest-one/php-tar-streamer

Creating new .tar.gz:

$out = gzopen("output.tar.gz", "wb9");
$tar = new \GO\Tar\TarStreamer($out);

// Adding existing empty folder as "some_dir"
$tar->addExistingFile("some_dir", "/tmp");

// Adding existing file as "some_dir/file.php"
$tar->addExistingFile("some_dir/file.php", __FILE__);

// Adding end-of-archive marker
$tar->addEndOfArchive();
fclose($out);

Extracting .tar.gz coming from STDIN and displaying to STDERR:

$in  = gzopen("php://stdin", "rb");
$out = fopen("php://stderr", "wt");

$tar = new \GO\Tar\TarStreamer($in);

while (null !== $header = $tar->readHeader()) {
    fwrite($out, $header->readHeader(). ":". PHP_EOL);
    $handle = $tar->getDataStream();
    while (!feof($handle)) {
        $data = fread($handle, 80);
        fwrite($out, "  ". base64_encode($data). PHP_EOL);
    }
}

Compare to other packages

See details in examples.

TL/DR: PharData is fast, but uses RAM. TarStreamer is fast and preserves RAM.

$ ./run.sh

PEAR Tar test:
(pear/archive_tar)
PHP=8.3.6
      z10mb.bin in 81921 reads
     z100mb.bin in 819201 reads
      r10mb.bin in 81921 reads
     r100mb.bin in 819201 reads
time:   0.83106184005737
memory: 2097152

PharData test:
(builtin class)
PHP=8.3.6
     r100mb.bin in 819200 reads
      r10mb.bin in 81920 reads
     z100mb.bin in 819200 reads
      z10mb.bin in 81920 reads
time:   0.4350152015686
memory: 10485760

Splitbrain PHPArchive\Tar test:
(splitbrain/php-archive)
PHP=8.3.6
      z10mb.bin in 81921 reads
     z100mb.bin in 819201 reads
      r10mb.bin in 81921 reads
     r100mb.bin in 819201 reads
time:   0.63708090782166
memory: 2097152

TarStreamer test:
(this package)
PHP=8.3.6
      z10mb.bin in 81920 reads
     z100mb.bin in 819200 reads
      r10mb.bin in 81920 reads
     r100mb.bin in 819200 reads
time:   0.31204700469971
memory: 2097152

Limitations

• The only supprted version of tar is "ustar"
• Only "directory", "file" and "symlink" entry types are fully supported
• Package is not tested properly on non-Linux environments