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.
• This package is not tested properly on non-Linux environments.