untar()

Extracts a tar archive file into a specified output directory.

Parameters

$tarFile : string

Path to the tar archive file to extract.

$outputPath : string

Path to the directory where files will be extracted. The directory will be created if it does not exist.

$options : array{dryRun?: bool, keepPermissions?: bool, overwrite?: bool} = []

Optional flags:

• dryRun: If true, the function does not extract files but returns the list of files that would be extracted. Default: false.
• keepPermissions: If true, preserves the original file permissions from the archive. Default: false.
• overwrite: If false, prevents overwriting existing files during extraction. Extraction will fail if a file already exists. Default: true.

Tags

throws

FileException

If the provided tar file is invalid or inaccessible.

throws

DirectoryException

If the output directory cannot be created or is not writable.

throws

RuntimeException

For extraction errors such as:

• Path traversal attempts detected inside archive entries.
• Attempt to overwrite existing files when overwrite is disabled.
• Other errors during decompression or extraction.

throws

Exception

Propagates unexpected exceptions during extraction wrapped as RuntimeException.

example

// Basic extraction
untar( '/path/to/archive.tar' , '/output/dir' );

// Extraction with options
untar( '/path/to/archive.tar.gz' , '/output/dir' , [
'overwrite'        => false,
'keepPermissions'  => true
]);

// Dry-run: preview contents without extracting
$files = untar( '/path/to/archive.tar' , '/output/dir' , [ 'dryRun' => true ] );
print_r( $files );

// Prevent overwriting, will throw RuntimeException if file exists
untar( '/path/to/archive.tar' , '/output/dir' , [ 'overwrite' => false ] );

author

Marc Alcaraz (ekameleon)

since

1.0.0