Oihana PHP

tar

Table of Contents

Functions

assertTar()  : bool
Validates that a file is a tar archive (compressed or uncompressed).
hasTarExtension()  : bool
Checks if a file has a tar-related extension.
hasTarMimeType()  : bool
Checks if a file has a tar-related extension.
tar()  : string
Creates a tar archive from one or more files and/or directories.
tarDirectory()  : string
Creates a tar archive from a directory with specified compression.
tarFileInfo()  : array{is_valid: bool, extension: string, mime_type: string|null, compression: string|null, file_count: int|null, total_size: int|null}
Retrieves detailed information about a tar archive file.
tarIsCompressed()  : bool
Checks if a given tar file is compressed.
untar()  : true|array<string|int, string>
Extracts a tar archive file into a specified output directory.
validateTarStructure()  : bool
Validates the internal structure of a tar file.

Functions

assertTar()

Validates that a file is a tar archive (compressed or uncompressed).

assertTar(string $filePath[, bool $strictMode = false ]) : bool
Parameters
$filePath : string

Path to the file to validate.

$strictMode : bool = false

If true, performs deep validation using file contents. If false, only checks extension and basic MIME type.

Tags
throws
FileException

If the file does not exist or cannot be read.

example

Basic validation using file extension and MIME type:

$isValid = isTarFile('/path/to/archive.tar');

Strict validation with file content inspection:

$isValid = isTarFile('/path/to/archive.tar.gz', true);

Validation failure for non-tar file:

$isValid = isTarFile('/path/to/image.jpg');
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
bool —

True if the file is a valid tar archive, false otherwise.

hasTarExtension()

Checks if a file has a tar-related extension.

hasTarExtension(string $filePath[, array<string|int, string> $tarExtensions = [FileExtension::TAR, FileExtension::TGZ, FileExtension::GZ, FileExtension::TAR_GZ, FileExtension::TAR_BZ2, FileExtension::BZ2] ]) : bool
Parameters
$filePath : string

Path to the file.

$tarExtensions : array<string|int, string> = [FileExtension::TAR, FileExtension::TGZ, FileExtension::GZ, FileExtension::TAR_GZ, FileExtension::TAR_BZ2, FileExtension::BZ2]

Optional list of valid tar-related extensions. Defaults to common tar and compressed tar extensions:

  • .tar
  • .tgz
  • .gz
  • .tar.gz
  • .tar.bz2
  • .bz2
Tags
author

Marc Alcaraz (ekameleon)

since
1.0.0
example

Check a simple tar file:

var_dump(hasTarExtension('/path/to/archive.tar')); // bool(true)

Check a gzipped tar file:

var_dump(hasTarExtension('/path/to/archive.tar.gz')); // bool(true)

Check a file with .tgz extension:

var_dump(hasTarExtension('/path/to/archive.tgz')); // bool(true)

Check a file with unsupported extension:

var_dump(hasTarExtension('/path/to/archive.zip')); // bool(false)

Check a file with double extension .tar.bz2:

var_dump(hasTarExtension('/path/to/archive.tar.bz2')); // bool(true)
Return values
bool —

True if the file has a recognized tar extension.

hasTarMimeType()

Checks if a file has a tar-related extension.

hasTarMimeType(string $filePath[, array<string|int, string> $mimeTypes = ['application/x-tar', 'application/tar', 'application/gzip', 'application/x-gzip', 'application/x-bzip2', 'application/bzip2', 'application/x-compressed-tar'] ]) : bool

This function inspects the MIME type of the given file against a list of valid tar-related MIME types to determine if the file is a tar archive.

Parameters
$filePath : string

Path to the file.

$mimeTypes : array<string|int, string> = ['application/x-tar', 'application/tar', 'application/gzip', 'application/x-gzip', 'application/x-bzip2', 'application/bzip2', 'application/x-compressed-tar']

Optional list of valid tar MIME types. Defaults to common tar and compressed tar types:

  • 'application/x-tar'
  • 'application/tar'
  • 'application/gzip'
  • 'application/x-gzip'
  • 'application/x-bzip2'
  • 'application/bzip2'
  • 'application/x-compressed-tar'
Tags
author

Marc Alcaraz (ekameleon)

since
1.0.0
example

Check if a .tar.gz file is a tar archive:

$result = hasTarMimeType('/path/to/archive.tar.gz');
var_dump($result); // bool(true) or bool(false)

Check a file with a custom list of MIME types:

$customTypes = ['application/x-tar', 'application/x-custom-tar'];
$result = hasTarMimeType('/path/to/custom.tar', $customTypes);

Check a non-existent file (returns false):

$result = hasTarMimeType('/path/to/missing.tar');
var_dump($result); // bool(false)
Return values
bool —

True if the file exists and its MIME type matches one of the given tar MIME types.

tar()

Creates a tar archive from one or more files and/or directories.

tar(string|array<string|int, string> $paths[, string|null $outputPath = null ][, string|null $compression = CompressionType::GZIP ][, string|null $preserveRoot = null ]) : string

This function supports adding multiple paths (files or directories) to a tar archive, with optional compression (gzip, bzip2, or none). It can preserve the root directory structure inside the archive, and generates a unique temporary archive if no output path is specified.

Empty directories are preserved in the archive.

Parameters
$paths : string|array<string|int, string>

Absolute path(s) to file(s) or directory(ies) to include in the archive.

$outputPath : string|null = null

Optional full path to the final archive file to create. If null, an automatic unique filename with timestamp is generated in the system temp directory.

$compression : string|null = CompressionType::GZIP

Compression type to use on the tar archive. Supported values are defined in CompressionType, defaults to CompressionType::GZIP.

$preserveRoot : string|null = null

If set, paths inside the archive will be stored relative to this directory, allowing to preserve directory structure when extracting. Must be an absolute path.

Tags
throws
FileException

If any of the provided paths does not exist or is invalid.

throws
UnsupportedCompressionException

If the requested compression type is not supported by the system.

throws
DirectoryException

If the temporary directory cannot be created or accessed.

throws
RuntimeException

If no files are added to the archive or if an error occurs during creation, including inability to rename temporary files.

see
CompressionType
example

Archive a single file, auto-named, gzip compressed (default):

$tarPath = tar('/var/www/html/index.php');

Archive a directory with bzip2 compression:

$tarPath = tar('/var/www/html', '/tmp/site.tar.bz2', CompressionType::BZIP2);

Archive multiple files with no compression:

$tarPath = tar
(
   ['/etc/hosts', '/etc/hostname'],
   '/tmp/config.tar',
   CompressionType::NONE
);

Archive directory with root preserved (relative paths):

$tarPath = tar
(
    '/var/www/html/project',
    '/tmp/project.tar.gz',
    CompressionType::GZIP,
    '/var/www/html'
);
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
string —

Returns the full path to the created tar archive file.

tarDirectory()

Creates a tar archive from a directory with specified compression.

tarDirectory(string $directory[, string|null $compression = CompressionType::GZIP ][, string|null $outputPath = null ][, array<string|int, mixed> $options = [] ]) : string

This function creates a compressed (or uncompressed) tar archive from the given directory. It supports filtering files by exclude patterns, by a callback filter function, and adding optional metadata saved as .metadata.json inside the archive.

If no filters or metadata are provided, it simply creates the archive directly from the directory. Otherwise, it copies filtered files to a temporary directory and archives from there.

Parameters
$directory : string

The source directory to archive.

$compression : string|null = CompressionType::GZIP

Compression type (e.g. gzip, bzip2, none). Default is gzip compression.

$outputPath : string|null = null

Optional output archive path. If null, defaults to directory name plus extension based on compression.

$options : array<string|int, mixed> = []

Additional options:

  • exclude => string[] list of glob patterns or file names to exclude
  • filter => callable|null a function (string $filepath): bool
  • metadata => array<string, string> extra metadata to embed in .metadata.json
Tags
throws
DirectoryException

If the source directory does not exist or is inaccessible.

throws
FileException

If there are issues writing files or archives.

throws
UnsupportedCompressionException

If an unsupported compression type is specified.

throws
RuntimeException

If no files match filtering criteria.

example 
// Create a gzip compressed tar archive from directory /var/www/html
$archive = tarDirectory('/var/www/html');
echo $archive; // /var/www/html.tar.gz

// Create a bz2 compressed archive, excluding .git and node_modules folders
$archive = tarDirectory(
    '/var/www/html',
    CompressionType::BZIP2,
    null,
    [
        TarOption::EXCLUDE => ['.git', 'node_modules'],
    ]
);

// Create an archive with a custom filter callback and add metadata
$archive = tarDirectory(
    '/var/www/html',
    CompressionType::NONE,
    '/backups/html_backup.tar',
    [
        TarOption::FILTER => function(string $filePath): bool {
            // Only include PHP files
            return str_ends_with($filePath, '.php');
        },
        TarOption::METADATA => [
            'createdBy' => 'admin',
            'description' => 'Backup of PHP source files',
        ],
    ]
);
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
string —

Returns the full path to the created archive file.

tarFileInfo()

Retrieves detailed information about a tar archive file.

tarFileInfo(string $filePath[, bool $strictMode = false ]) : array{is_valid: bool, extension: string, mime_type: string|null, compression: string|null, file_count: int|null, total_size: int|null}

This function inspects the given tar file to determine its validity, compression type, MIME type, number of contained files, and total size of the contents.

It uses the PharData class to count files and calculate total size when the tar is valid.

Parameters
$filePath : string

Absolute path to the tar archive file to inspect.

$strictMode : bool = false

When true, enables strict validation of the tar file structure via assertTar(). Default is false for a more lenient check.

Tags
throws
FileException

If the provided file does not exist or is not accessible.

see
assertTar()
example 
$info = tarFileInfo( '/archives/sample.tar' );
print_r( $info );

$info = tarFileInfo( '/archives/compressed.tar.gz' );
echo $info['compression']; // 'gzip'

$info = tarFileInfo( '/bad/path.tar' );
var_dump( $info['isValid'] ); // false

// Strict mode
$info = tarFileInfo( '/archives/sample.tar' , true );
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
array{is_valid: bool, extension: string, mime_type: string|null, compression: string|null, file_count: int|null, total_size: int|null} —

Returns an associative array with:

  • isValid: Whether the tar file is valid according to assertTar().
  • extension: File extension (lowercase) extracted from the path.
  • mimeType: MIME type detected via finfo.
  • compression: Compression type detected (gzip, bzip2, or none).
  • fileCount: Number of files inside the tar (if valid), otherwise null.
  • totalSize: Sum of sizes (in bytes) of all files inside (if valid), otherwise null.

tarIsCompressed()

Checks if a given tar file is compressed.

tarIsCompressed(string $tarFile) : bool

This function determines whether the file name indicates a compressed tar archive based on common compressed tar extensions such as .tar.gz, .tgz, .tar.bz2, or .tbz2.

Note: This function only inspects the file name extension, not the actual file contents.

Parameters
$tarFile : string

The path or filename of the tar archive.

Tags
example 
var_dump( tarIsCompressed( 'archive.tar.gz'   ) ); // true
var_dump( tarIsCompressed( 'archive.tgz'      ) ); // true
var_dump( tarIsCompressed( 'archive.tar.bz2'  ) ); // true
var_dump( tarIsCompressed( 'archive.tbz2'     ) ); // true
var_dump( tarIsCompressed( 'archive.tar'      ) ); // false
var_dump( tarIsCompressed( 'archive.zip'      ) ); // false
var_dump( tarIsCompressed( 'README.md'        ) ); // false
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
bool —

True if the file is recognized as a compressed tar archive, false otherwise.

untar()

Extracts a tar archive file into a specified output directory.

untar(string $tarFile, string $outputPath[, array{dryRun?: bool, keepPermissions?: bool, overwrite?: bool} $options = [] ]) : true|array<string|int, string>

This function supports regular and compressed tar files (.tar, .tar.gz, .tar.bz2). It can perform a dry run to preview extracted files, optionally preserve file permissions, and control overwriting of existing files.

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
Return values
true|array<string|int, string> —

Returns true on successful extraction, or an array of file paths (relative to archive root) if dryRun is enabled.

validateTarStructure()

Validates the internal structure of a tar file.

validateTarStructure(string $filePath) : bool

This function checks whether the given file is a valid, readable tar archive. It uses the PharData class to attempt parsing the archive and iterates over a few entries to confirm structural integrity.

Note: Compressed tar files (e.g., .tar.gz, .tar.bz2) are not supported directly. Decompress them before using this function.

Parameters
$filePath : string

Path to the tar file.

Tags
example 
var_dump( validateTarStructure( '/path/to/archive.tar'     ) ); // true or false
var_dump( validateTarStructure( '/path/to/invalid.tar'     ) ); // false
var_dump( validateTarStructure( '/path/to/archive.tar.gz'  ) ); // false (must decompress first)
var_dump( validateTarStructure( '/path/to/not_a_tar.txt'   ) ); // false
var_dump( validateTarStructure( '/nonexistent/file.tar'    ) ); // false
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
bool —

True if the file has a valid tar structure, false otherwise.


        

        
    




    

    

                                

                

                            
    

        On this page

        
    


                

                            

            

    

        

            
Search results