TarOption uses ConstantsTrait
Enumeration of the option keys accepted by the `oihana\files\archive\tar` helpers.
The keys serve two functions, and each one reads only its own:
- untar() reads self::ALLOW_UNSAFE_LINKS, self::DRY_RUN, self::KEEP_PERMISSIONS, self::MAX_EXTRACTED_SIZE and self::OVERWRITE.
- tarDirectory() reads self::EXCLUDE, self::FILTER and self::METADATA.
A key the called function does not read is ignored rather than refused.
Tags
Table of Contents
Constants
- ALLOW_UNSAFE_LINKS : string = 'allowUnsafeLinks'
- Whether to restore a link whose target leaves the output directory.
- DRY_RUN : string = 'dryRun'
- Return the list of entries instead of extracting them.
- EXCLUDE : string = 'exclude'
- List of glob patterns or file names to exclude from the archive.
- FILTER : string = 'filter'
- Filter the files and directories to archive.
- KEEP_PERMISSIONS : string = 'keepPermissions'
- Whether to restore the Unix permissions the archive recorded.
- MAX_EXTRACTED_SIZE : string = 'maxExtractedSize'
- Maximum total uncompressed size in bytes accepted during extraction.
- METADATA : string = 'metadata'
- Additional metadata to embed in the archive as `.metadata.json`.
- OVERWRITE : string = 'overwrite'
- Whether an existing target file may be overwritten.
Constants
ALLOW_UNSAFE_LINKS
Whether to restore a link whose target leaves the output directory.
public
string
ALLOW_UNSAFE_LINKS
= 'allowUnsafeLinks'
untar() refuses, by default, to extract an archive holding
a link whose target is absolute or climbs out of the output directory: a link is the one
entry whose content is itself a path, and creating one hands every entry written after it a
way out. Set this to true only for an archive you answer for — your own backup, typically,
whose links were absolute on the disk it was taken from.
It does not lift the other refusal: an archive read by PharData, where there is no GNU tar
to read it with, is refused whenever it holds a link at all, since that engine cannot
restore one — it writes an empty file in its place.
Default: false.
DRY_RUN
Return the list of entries instead of extracting them.
public
string
DRY_RUN
= 'dryRun'
untar() then writes nothing and returns the names of the file entries the archive holds, directory entries excluded. The guards still run, so a dry run reports an archive that could not be extracted by throwing rather than by listing it.
Default: false.
EXCLUDE
List of glob patterns or file names to exclude from the archive.
public
string
EXCLUDE
= 'exclude'
Read by tarDirectory() and forwarded to shouldExcludeFile(), which matches each pattern against both the full path and the base name.
Default: [] — nothing is excluded.
FILTER
Filter the files and directories to archive.
public
string
FILTER
= 'filter'
A callable function ( string $filePath ): bool returning true to include the item, read
by tarDirectory(). Applied after self::EXCLUDE, so a
path already excluded never reaches it.
Default: null — everything that survived the exclusions is archived.
KEEP_PERMISSIONS
Whether to restore the Unix permissions the archive recorded.
public
string
KEEP_PERMISSIONS
= 'keepPermissions'
untar() then applies each entry's stored mode to what it extracted. Best-effort: a mode that cannot be applied, on a file the caller does not own, is left as it is rather than failing the extraction.
Default: false — the extracted files take the usual default mode.
MAX_EXTRACTED_SIZE
Maximum total uncompressed size in bytes accepted during extraction.
public
string
MAX_EXTRACTED_SIZE
= 'maxExtractedSize'
When set to a positive integer, untar() runs a pre-scan of the archive and throws RuntimeException if the sum of the entries' uncompressed sizes exceeds this limit, before any file is written to disk. This guards against decompression-bomb attacks (small archive expanding to gigabytes).
Default: null — no limit.
METADATA
Additional metadata to embed in the archive as `.metadata.json`.
public
string
METADATA
= 'metadata'
Read by tarDirectory(). Embedding metadata also makes the
archive non-empty, so a directory where no file matched the filters still produces one,
holding .metadata.json alone.
Default: [] — no metadata file is written.
OVERWRITE
Whether an existing target file may be overwritten.
public
string
OVERWRITE
= 'overwrite'
Read by untar(): when false, the archive is listed first
and the extraction is refused, before anything is written, if one of its entries already
exists in the output directory. It says nothing about the archive being written, which
tar() replaces when the path it was given already holds one.
Default: true.