tarBinary.php
Table of Contents
Functions
- tarBinary() : string|null
- The system `tar` this library is willing to use, or null.
- tarBinaryIsUsable() : bool
- Whether a candidate is an executable GNU tar.
Functions
tarBinary()
The system `tar` this library is willing to use, or null.
tarBinary([bool $refresh = false ]) : string|null
PharData writes tar archives in pure PHP, and on anything but a toy tree it is not viable:
measured against GNU tar on the same 96 MB / 7 554-file directory, producing the same 17 MB
archive, it took 317 seconds against 1.63 — and the gap widens with size, because it
writes the tar and then reads the whole thing back to compress it. It also refuses any path
component longer than 100 bytes, the ustar limit, which a single file of a stock WordPress
plugin set is enough to hit.
So the work is handed to the system binary when one is there. Which one matters:
- GNU tar stores names as raw bytes, exactly as
PharDatadoes. Verified on a tree of accented, CJK, quoted and spaced names, plus a symlink and an empty directory: the entry lists are identical. - bsdtar, which is what macOS ships as
/usr/bin/tar, converts filenames to Unicode NFD.été.txtbecomese´te´.txtinside the archive. An archive written on a Mac and restored on a server would carry different names than the originals — for a site with accented media, different URLs. Speed is not worth that, and a Mac is a development machine rather than a backup target. - BusyBox tar is a reduced implementation whose fidelity has not been measured here.
Hence the rule: the binary is used when it identifies itself as GNU tar, and PharData
carries the rest. Slower and identical beats faster and subtly different.
OIHANA_TAR_BINARY overrides the search: a path to use one in particular, or an empty value
to force the PharData path — which is how the test suite exercises both engines on the
same fixtures.
Parameters
- $refresh : bool = false
-
Whether to look again instead of reusing the previous answer.
Tags
Return values
string|null —The binary to run, or null when the archive is to be built in PHP.
tarBinaryIsUsable()
Whether a candidate is an executable GNU tar.
tarBinaryIsUsable(string $candidate) : bool
Asked by running it rather than by trusting its name: /usr/bin/tar is GNU tar on Linux and
bsdtar on macOS, and the two do not treat filenames the same way.
Parameters
- $candidate : string
-
The path to test.
Tags
Return values
bool —True when the binary runs and identifies itself as GNU tar.