UnifiedArchive

https://wapmorgan.github.io/UnifiedArchive/
Admin
UnifiedArchive is a PHP library that provides a unified interface for managing various archive...
Tokens:16,334
Snippets:196
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install New Driver and Check Functions

Source: https://wapmorgan.github.io/UnifiedArchive

Instructions for installing additional archive drivers, such as 'pear/archive_tar', and checking their supported functions. This may involve installing extensions, CLI tools, or PHP libraries.

```bash
#Read installation instructions from
./vendor/bin/cam system:drivers
#install missing drivers, for example pear/archive_tar
composer require pear/archive_tar
#check out driver functions
./vendor/bin/cam system:formats TarByPear

#if needed, install extensions, cli tools and php libraries
#to enable support of other formats
```

--------------------------------

### Install Php-Iso-File Driver

Source: https://wapmorgan.github.io/UnifiedArchive/docs/Drivers.html

Install the Php-Iso-File driver for handling .iso files. Supports only opening and extraction.

```bash
composer require phpclasses/php-iso-file
```

--------------------------------

### Install TarByPear and NelexaZip Drivers

Source: https://wapmorgan.github.io/UnifiedArchive/docs/Drivers.html

In a common case, install TarByPear and NelexaZip drivers. These are pure PHP implementations.

```bash
composer require pear/archive_tar nelexa/zip
```

--------------------------------

### Install PHP Extensions in Docker

Source: https://wapmorgan.github.io/UnifiedArchive/docs/Drivers.html

In Docker or on a VDS, install all necessary PHP extensions and the '7za' utility for the SevenZip driver.

```bash
apt-get install p7zip-full
pecl install zip rar phar bz2 zlib xz
```

--------------------------------

### Install UnifiedArchive and Check Formats

Source: https://wapmorgan.github.io/UnifiedArchive

Installs the UnifiedArchive library using Composer and provides commands to check supported archive formats and functions for specific formats.

```bash
composer require wapmorgan/unified-archive
#Check supported formats with installed drivers
./vendor/bin/cam system:formats
#Check supported functions for zip format
./vendor/bin/cam system:format zip
```

--------------------------------

### Install SplitbrainPhpArchive Driver

Source: https://wapmorgan.github.io/UnifiedArchive/docs/Drivers.html

Install the SplitbrainPhpArchive driver, a pure PHP implementation for various archive formats. It optionally uses zlib and bz2 extensions.

```bash
composer require splitbrain/php-archive
```

--------------------------------

### Install Symfony Process for Multiple Archive Drivers

Source: https://wapmorgan.github.io/UnifiedArchive/docs/Drivers.html

When installing SevenZip and AlchemyZippy simultaneously, specify a Symfony Process version to avoid conflicts.

```bash
composer require symfony/process:~3.4
```

--------------------------------

### Install Archive7z Version 4.0.0

Source: https://wapmorgan.github.io/UnifiedArchive/docs/Drivers.html

Install version 4.0.0 of the 'gemorroj/archive7z' library when using it alongside other archive drivers that might have dependency conflicts.

```bash
composer require gemorroj/archive7z:~4.0
```

--------------------------------

### Install NelexaZip Driver

Source: https://wapmorgan.github.io/UnifiedArchive/docs/Drivers.html

Install the NelexaZip driver, a pure PHP implementation for zip archives. It may optionally use several PHP extensions.

```bash
composer require nelexa/zip
```

--------------------------------

### Install Wapmorgan Cab-Archive Driver

Source: https://wapmorgan.github.io/UnifiedArchive/docs/Drivers.html

Install the Cab-Archive driver for handling .cab files. Extraction is supported on PHP 7.0.22+, 7.1.8+, 7.2.0+.

```bash
composer require wapmorgan/cab-archive
```

--------------------------------

### Install TarByPear Driver

Source: https://wapmorgan.github.io/UnifiedArchive/docs/Drivers.html

Install the TarByPear driver, a pure PHP implementation for tar archives. It optionally uses zlib, bz2, or xz extensions. Note: Does not support updating archives.

```bash
composer require pear/archive_tar
```

--------------------------------

### Configure SevenZip Driver

Source: https://wapmorgan.github.io/UnifiedArchive/docs/Drivers.html

If the '7za' utility is installed, configure the SevenZip driver. This driver uses the 'gemorroj/archive7z' library.

```bash
composer require gemorroj/archive7z
```

--------------------------------

### Define file paths for archiving in UnifiedArchive

Source: https://wapmorgan.github.io/UnifiedArchive/CHANGELOG.html

This example demonstrates the flexible format for specifying files and their desired names within an archive. It shows how to map local file paths to archive paths, including cases where the archive name differs from the local name.

```php
[
    '/var/www/log.txt',                // will be "/var/www/log.txt"
    'log2.txt' => '/var/www/log2.txt', // will be "/log2.txt"
    '/var/www/site',                   // will be "/var/www/site"
    'site2' => '/var/www/site2',       // will be "/site2"
]
```

--------------------------------

### Iterate over archive contents as an array in UnifiedArchive

Source: https://wapmorgan.github.io/UnifiedArchive/CHANGELOG.html

This example shows how to open an archive and iterate through its contents, accessing each file's name and data. It also demonstrates direct access to a file's data using its name as an array key.

```php
$a = \wapmorgan\UnifiedArchive\UnifiedArchive::open(‘tests/archives/fixtures.7z’);
foreach ($a as $file => $data) {
    echo $file.PHP_EOL;
}


$file_data = $a[‘filename’];
```

--------------------------------

### Configure AlchemyZippy Driver

Source: https://wapmorgan.github.io/UnifiedArchive/docs/Drivers.html

If 'tar' or 'unzip' utilities are installed, configure the AlchemyZippy driver. This driver uses the 'alchemy/zippy' library.

```bash
composer require alchemy/zippy
```

--------------------------------

### Specify directories for archiving in UnifiedArchive

Source: https://wapmorgan.github.io/UnifiedArchive/CHANGELOG.html

When archiving, you can specify multiple directories to be placed in the root of the archive. This example shows how to include contents of './folder1' and './folder2' at the root, alongside a specific file.

```php
[
    '' => ['./folder1', './folder2'],
    'README.md' => './subfolder/README.md'
] # Archive will have all folder1, folder2 contents in the root and README.md
```

--------------------------------

### Get Archive Information

Source: https://wapmorgan.github.io/UnifiedArchive

Use the 'archive:info' command to retrieve detailed information about a specific archive file.

```bash
./vendor/bin/cam archive:info archive.tar.gz # archive information
```

--------------------------------

### Get Archive Format

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Retrieves the archive's format using a constant from the Formats class.

```php
UnifiedArchive::getFormat()
```

--------------------------------

### UnifiedArchive::canOpen

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Tests if an archive can be opened with the current system and PHP configuration. It checks for format support and whether necessary extensions are installed.

```APIDOC
## UnifiedArchive::canOpen

### Description
Tests if an archive (format is resolved by extension) can be opened with current system and php configuration. If you want to enable specific format support, you need to install an additional program or php extension. List of extensions that should be installed can be obtained by executing built-in `cam`: `./vendor/bin/cam system:formats`. Returns `true` if given archive can be opened and `false` otherwise.

### Method
`UnifiedArchive::canOpen(string $fileName, bool $passwordProtected = false): boolean`
```

--------------------------------

### Get PclZip Interface

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Retrieves a PclzipZipInterface handler for the archive, providing PclZip-like functionality.

```php
UnifiedArchive::getPclZipInterface(): PclzipZipInterface
```

--------------------------------

### Get All Files in Archive

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Returns a list of all files within the archive. An optional filter can be applied using fnmatch.

```php
UnifiedArchive::getFiles(?string $filter = null): string[]
```

--------------------------------

### Check if Archive Can Be Opened

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Tests if an archive can be opened with the current system and PHP configuration. Ensure necessary extensions are installed for specific format support.

```php
UnifiedArchive::canOpen(string $fileName, bool $passwordProtected = false): boolean
```

--------------------------------

### Get Archive Size

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Retrieves the total size of the archive file in bytes.

```php
UnifiedArchive::getSize()
```

--------------------------------

### Get Archive MIME Type

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Retrieves the MIME type of the archive. Returns null if not supported or present.

```php
UnifiedArchive::getMimeType()
```

--------------------------------

### Get Archive Comment

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Retrieves the archive's comment. Returns null if the comment is not supported or not present.

```php
UnifiedArchive::getComment()
```

--------------------------------

### Get File Stream from Archive

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Provides a resource stream for a file within the archive, suitable for reading large files in portions. Throws NonExistentArchiveFileException if the file is not found.

```php
UnifiedArchive::getFileStream(string $fileName): resource
```

--------------------------------

### Get Original Size

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Retrieves the size of all stored files without compression, indicating the space they will occupy after extraction.

```php
UnifiedArchive::getOriginalSize()
```

--------------------------------

### Handle potential naming conflicts in UnifiedArchive archiving

Source: https://wapmorgan.github.io/UnifiedArchive/CHANGELOG.html

This example illustrates a potential naming conflict scenario when archiving files with similar names from different locations. It highlights the new behavior where a specific mapping overrides the default archiving path to prevent data loss or unexpected overwrites.

```php
[
'/var/www/log2.txt' => 'log2.txt',
]
```

--------------------------------

### Get Archive Entry for a File

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Retrieves an ArchiveEntry object containing detailed information about a file. Throws NonExistentArchiveFileException if the file is not found.

```php
UnifiedArchive::getFileData(string $fileName): ArchiveEntry
```

--------------------------------

### Get Compressed Size

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Retrieves the size of all stored files with archive compression applied, useful for measuring compression efficiency.

```php
UnifiedArchive::getCompressedSize()
```

--------------------------------

### Get File Content as String

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Retrieves the entire content of a file within the archive as a raw string. Throws NonExistentArchiveFileException if the file is not found.

```php
UnifiedArchive::getFileContent(string $fileName): string
```

--------------------------------

### Get File Information and Content

Source: https://wapmorgan.github.io/UnifiedArchive/docs/Usage.html

Provides methods to access file metadata, raw content, or a stream for a specific file within the archive. Use getFileData() for metadata, getFileContent() for raw data, and getFileStream() for a stream.

```php
// file meta
$file_data = $archive->getFileData('README.md')); // ArchiveEntry with file information
echo 'Original size is ' . $file_data->uncompressedSize . PHP_EOL;
echo 'Modification datetime is ' . date('r', $file_data->modificationTime) . PHP_EOL;

// raw file content
$file_content = $archive->getFileContent('README.md')); // string

// pass stream to standard output
fpassthru($archive->getFileStream('README.md'));

```

--------------------------------

### List Files in Archive

Source: https://wapmorgan.github.io/UnifiedArchive/docs/Usage.html

Retrieves a list of files within the archive, optionally filtered by a glob pattern. Can also be iterated directly to get filenames. Checks for the existence of a specific file.

```php
foreach($archive->getFiles() as $filename) { // ['file', 'file2', 'file3', ...] ... }
   
foreach($archive->getFiles('*.txt') as $filename) { // ['README.txt', 'doc.txt', ...] ... }
   
foreach ($archive as $filename) { ... }
   
if ($archive->hasFile('README.md')) { ... }

```

--------------------------------

### Show Help and List Commands

Source: https://wapmorgan.github.io/UnifiedArchive

Launch the console program with the 'list' command to display available commands and help information.

```bash
./vendor/bin/cam list # help
```

--------------------------------

### Create Archive from Files

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Creates an archive with the specified files or directories. Supports various path mapping strategies and compression levels. Throws exceptions for errors like file existence or empty lists.

```php
UnifiedArchive::create(
    array|string $files,
    string $archiveName,
    int $compressionLevel = BasicFormat::COMPRESSION_AVERAGE,
    ?string $password = null,
    ?callable $fileProgressCallable = null
): int
```

--------------------------------

### Open Archive with UnifiedArchive

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Opens an archive, returning a UnifiedArchive instance. Supports password-protected archives and ability-based driver selection. Throws exceptions on failure.

```php
UnifiedArchive::open(
    string $fileName,
    int[] $abilities = [],
    ?string $password = null
): UnifiedArchive|null
```

--------------------------------

### Archive Files with Different Configurations

Source: https://wapmorgan.github.io/UnifiedArchive/CHANGELOG.html

Demonstrates various ways to use `archiveFiles()` to archive single files, entire directories, or a custom list of files and directories with specified archive names.

```php
  // 1. one file
  $archive->archiveFiles('/var/www/site/abc.log', 'archive.zip'); // => stored as 'abc.log'
  // 2. directory
  $archive->archiveFiles('/var/www/site/runtime/logs', 'archive.zip'); // => directory content stored in archive root
  // 3. list
  $archive->archiveFiles([
        '/var/www/site/abc.log' => 'abc.log', // stored as 'abc.log'
        '/var/www/site/abc.log', // stored as '/var/www/site/abc.log'
        '/var/www/site/runtime/logs' => 'logs', // directory content stored in 'logs' dir
        '/var/www/site/runtime/logs', // stored as '/var/www/site/runtime/logs'
  ], 'archive.zip');
```

--------------------------------

### Extract Archive Files

Source: https://wapmorgan.github.io/UnifiedArchive

Demonstrates how to open an archive file (e.g., zip, rar, tar.bz2) using UnifiedArchive and extract its contents to a specified directory. Includes a check for sufficient disk space before extraction.

```php
use \wapmorgan\UnifiedArchive\UnifiedArchive;
$output_dir = '/var/www/extracted';
# Extraction
$archive = UnifiedArchive::open('archive.zip'); // archive.rar, archive.tar.bz2
if (disk_free_space($output_dir) < $archive->getOriginalSize()) {
    throw new \RuntimeException('No needed space available. Need ' . ($archive->getOriginalSize() - disk_free_space($output_dir)) . ' byte(s) more');
}
$extracted = $archive->extract($output_dir);
echo 'Number of extracted files' . $extracted.PHP_EOL;
```

--------------------------------

### Create Archive

Source: https://wapmorgan.github.io/UnifiedArchive

Shows how to create a new archive file (e.g., zip) using UnifiedArchive. It takes an array mapping filenames to their source paths or a folder path for archiving.

```php
UnifiedArchive::create([
    'README.md' => '/default/path/to/README.md',
    '' => '/folder/with/content/',
], 'archive.zip');
```

--------------------------------

### UnifiedArchive Method Aliases (PHP)

Source: https://wapmorgan.github.io/UnifiedArchive/CHANGELOG.html

Demonstrates the new method names for checking archive capabilities and retrieving archive format. Old methods are deprecated but still functional.

```php
UnifiedArchive::canOpenType -> Formats::canOpen
```

```php
UnifiedArchive::canOpenArchive -> UnifiedArchive::canOpen
```

```php
UnifiedArchive::canCreateType -> Formats::canCreate
```

```php
UnifiedArchive->getArchiveType -> UnifiedArchive->getArchiveFormat
```

--------------------------------

### Extract and Delete Files with Path Expansion

Source: https://wapmorgan.github.io/UnifiedArchive/CHANGELOG.html

Shows how to use `extractFiles()` and `deleteFiles()` with the `$expandFilesList` argument set to `true` to expand directory paths.

```php
  $archive->extractFiles(__DIR__, 'src/', true);
  $archive->deleteFiles('tests/', true);
```

--------------------------------

### Check Archive Format Support (PHP)

Source: https://wapmorgan.github.io/UnifiedArchive/CHANGELOG.html

Utilize the `Formats` class to check capabilities of different archive formats. Use `canOpen` to verify if a format can be opened, `canCreate` for creation support, `canAppend` for adding files, `canUpdate` for removing members, and `canEncrypt` for encrypted archive compatibility.

```php
Formats::canOpen()
```

```php
Formats::canCreate()
```

```php
Formats::canAppend()
```

```php
Formats::canUpdate()
```

```php
Formats::canEncrypt()
```

--------------------------------

### Create Archive to String

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Creates an archive from the given files or directories and returns the archive content as a string. Allows specifying archive format, compression level, and password.

```php
UnifiedArchive::createInString(
    array|string $fileOrFiles,
    string $archiveFormat,
    int $compressionLevel = BasicDriver::COMPRESSION_AVERAGE,
    ?string $password = null,
    ?callable $fileProgressCallable = null
)
```

--------------------------------

### UnifiedArchive::open

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Opens an archive and returns an instance of UnifiedArchive. Supports password-protected archives and ability-based driver selection.

```APIDOC
## UnifiedArchive::open

### Description
Opens an archive and returns instance of `UnifiedArchive`. If you provide `$password`, it will be used to open encrypted archive. If you provide `$abilities`, it will be used to determine driver for format, that supports ALL of passed abilities. In case of failure (file is not readable or format is not supported or recognized), an `InvalidArgumentException` or `UnsupportedArchiveException` will be thrown.

### Method
`UnifiedArchive::open(string $fileName, int[] $abilities = [], ?string $password = null): UnifiedArchive|null`
```

--------------------------------

### UnifiedArchive::create

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Creates an archive with the given files and saves it to disk. Supports various file path mappings and compression levels.

```APIDOC
## UnifiedArchive::create

### Description
Creates an archive with given `$files` list and saves on disk. `$files` is an array of files or directories. If file/directory passed with numeric key (e.g `['file', 'directory']`), then file/directory will have it’s full (not relative) path in an archive. If passed with string keys, then there’s path replacement. Example:
    * `'/var/www/original/name.log',` - file **/var/www/original/name.log** will be store with its original name;
    * `'/var/www/site/runtime/logs',` - directory contents will be stored as **/var/www/site/runtime/logs** , with its original name;
    * `'insideArchiveName.log' => '/var/www/original/name.log',` - file **/var/www/original/name.log** will be stored as **insideArchiveName.log** in archive root;
    * `'insideArchiveDir' => '/var/www/site/runtime/logs',` - directory contents will be stored in **insideArchiveDir** dir inside archive;
    * `'' => ['/home/user1/docs', '/home/user2/docs'],` - directories **user1** and **user2** docs contents will be merged and stored in archive root;
In case of success, number of stored files will be returned.
Creates an archive with all content from given directory and saves archive to `$archiveName` (format is resolved by extension). All files have relative path in the archive. By `$compressionLevel` you can adjust compression level for files. By `$password` you can set password for an archive. If case of success, `true` is returned.
Available values for compression:
    * `BasicFormat::COMPRESSION_NONE`
    * `BasicFormat::COMPRESSION_WEAK`
    * `BasicFormat::COMPRESSION_AVERAGE`
    * `BasicFormat::COMPRESSION_STRONG`
    * `BasicFormat::COMPRESSION_MAXIMUM`

### Parameters
#### Path Parameters
- **files** (array|string) - Required - List of files or directories to archive.
- **archiveName** (string) - Required - The name of the archive file to create.
- **compressionLevel** (int) - Optional - The compression level for the archive. Defaults to `BasicFormat::COMPRESSION_AVERAGE`.
- **password** (string) - Optional - Password for the archive.
- **fileProgressCallable** (callable) - Optional - A callable function to report file progress.

### Throws
- `UnsupportedOperationException`
- `FileAlreadyExistsException`
- `EmptyFileListException`
- `ArchiveCreationException`
```

--------------------------------

### Create New Archive

Source: https://wapmorgan.github.io/UnifiedArchive

Use the 'archive:create' command to create a new archive from a directory of files. Supports compression options like '--compression=maximum'.

```bash
./vendor/bin/cam archive:create --compression=maximum archive2.tar.gz ./OUTPUT/partners # archive creation from files
```

--------------------------------

### Driver Support Matrix Output

Source: https://wapmorgan.github.io/UnifiedArchive/docs/Drivers.html

This output from `./vendor/bin/cam system:formats` shows the compatibility of different archive drivers with various formats. The symbols indicate supported operations like open, extract, and create.

```text
+-----------------+------------+------+------+------+-------+--------+--------+--------+-----------+-----+-----+-----+------+-----+-----+-----+-----+-----+-----+-----+------+-------+
| driver / format | zip        | rar  | gz   | bz2  | xz    | tar    | tgz    | tbz2   | 7z        | cab | iso | arj | uefi | gpt | mbr | msi | dmg | rpm | deb | udf | txz  | tar.z |
+-----------------+------------+------+------+------+-------+--------+--------+--------+-----------+-----+-----+-----+------+-----+-----+-----+-----+-----+-----+-----+------+-------+
| Zip             | oOtxsadTcC |      |      |      |       |        |        |        |           |     |     |     |      |     |     |     |     |     |     |     |      |       |
| Rar             |            | oOxs |      |      |       |        |        |        |           |     |     |     |      |     |     |     |     |     |     |     |      |       |
| Gzip            |            |      | oxsc |      |       |        |        |        |           |     |     |     |      |     |     |     |     |     |     |     |      |       |
| Bzip            |            |      |      | oxsc |       |        |        |        |           |     |     |     |      |     |     |     |     |     |     |     |      |       |
| Lzma            |            |      |      |      | oxsc  |        |        |        |           |     |     |     |      |     |     |     |     |     |     |     |      |       |
| TarByPhar       | oxsadc     |      |      |      |       | oxsadc | oxsadc | oxsadc |           |     |     |     |      |     |     |     |     |     |     |     |      |       |
| SevenZip        | oOxadcC    |      |      |      |       | oxadc  |        |        | oOtxadTcC | ox  | ox  | ox  | ox   | ox  | ox  | ox  | ox  | ox  | ox  | ox  |      |       |
| AlchemyZippy    |            |      |      |      |       |        |        |        |           |     |     |     |      |     |     |     |     |     |     |     |      |       |
| NelexaZip       | oOxad      |      |      |      |       |        |        |        |           |     |     |     |      |     |     |     |     |     |     |     |      |       |
| TarByPear       |            |      |      |      |       | oxac   | oxac   | oxac   |           |     | ox  |     |      |     |     |     |     |     |     |     | oxac |       |
| Iso             |            |      |      |      |       |        |        |        |           |     |     |     |      |     |     |     |     |     |     |     |      |       |
| Cab             |            |      |      |      |       |        |        |        |           | ox  |     |     |      |     |     |     |     |     |     |     |      |       |
+-----------------+------------+------+------+------+-------+--------+--------+--------+-----------+-----+-----+-----+------+-----+-----+-----+-----+-----+-----+-----+------+-------+
```

--------------------------------

### Open Archive with Specific Abilities in UnifiedArchive

Source: https://wapmorgan.github.io/UnifiedArchive/CHANGELOG.html

Use this to open an archive and specify the required abilities for the driver, such as content streaming and appending. If abilities are not specified, default open or open encrypted checks are used.

```php
use wapmorgan\UnifiedArchive\Abilities;
use wapmorgan\UnifiedArchive\Drivers\Basic\BasicDriver;

# opens an array with driver, that supports content streaming and appending
$archive = \wapmorgan\UnifiedArchive\UnifiedArchive::open('archive.7z', [Abilities::STREAM_CONTENT, Abilities::APPEND]);
# if not specified, uses OPEN or OPEN_ENCRYPTED check, if password passed

```

--------------------------------

### Add Files or Directories to Archive

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Packs one or more files or directories into the archive. The format of `$fileOrFilesList` is detailed in the `UnifiedArchive::create` method. Throws various exceptions on error, returning the number of packed files on success.

```php
UnifiedArchive::add(array|string $fileOrFilesList): int|false
```

--------------------------------

### UnifiedArchive::add()

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Packs one or more files or directories into the archive. The syntax for `$fileOrFilesList` is described in the `UnifiedArchive::create` method documentation. Throws an `
Exception` on error, such as file already existing or an empty list. Returns the number of packed files on success.

```APIDOC
## UnifiedArchive::add(array|string $fileOrFilesList)

### Description
Packs given `$fileOrFilesList` into archive. `$fileOrFilesList` is a string or an array of files or directories. Syntax of `$fileOrFilesList` is described in `UnifiedArchive::create` method. If any error occurred (such as file already exists, files list is empty, …), an `\Exception` is throwing. In case of success, number of packed files will be returned.

### Method
POST (conceptual, for modification)

### Endpoint
N/A (Method call on an instance)

### Parameters
#### Query Parameters
- **fileOrFilesList** (array|string) - Required - A string or an array of file/directory paths to add to the archive.

### Response
#### Success Response
- **packedCount** (int|false) - The number of files successfully packed, or false on failure.

### Throws
- `EmptyFileListException`
- `UnsupportedOperationException`
- `ArchiveModificationException`
```

--------------------------------

### Open Archive with Automatic Format Detection

Source: https://wapmorgan.github.io/UnifiedArchive/docs/Usage.html

Opens an archive file by automatically detecting its format from the filename or content. Returns a UnifiedArchive object on success or null on failure. Supports password protection and ability specification.

```php
 require 'vendor/autoload.php';
 use wapmorgan\UnifiedArchive\Abilities;
 use wapmorgan\UnifiedArchive\UnifiedArchive;

 $archive = UnifiedArchive::open('filename.rar');
 // or
 $archive = UnifiedArchive::open('filename.zip', null, 'password');
 // or
 $archive = UnifiedArchive::open('filename.tar', [
     Abilities::EXTRACT_CONTENT,
     Abilities::STREAM_CONTENT,
     Abilities::APPEND,
 ]);
 // or
 $archive = UnifiedArchive::open('filename.7z', null, 'password');

```

--------------------------------

### UnifiedArchive::createInString

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Creates an archive with the given files and returns the archive content as a string.

```APIDOC
## UnifiedArchive::createInString

### Description
Creates an archive with given `$fileOrFiles` list and returns as string. `$fileOrFiles` is an array of files or directories.

### Parameters
#### Path Parameters
- **fileOrFiles** (array|string) - Required - List of files or directories to archive.
- **archiveFormat** (string) - Required - The format of the archive (e.g., 'zip', 'tar').
- **compressionLevel** (int) - Optional - The compression level for the archive. Defaults to `BasicDriver::COMPRESSION_AVERAGE`.
- **password** (string) - Optional - Password for the archive.
- **fileProgressCallable** (callable) - Optional - A callable function to report file progress.
```

--------------------------------

### List Files in Archive

Source: https://wapmorgan.github.io/UnifiedArchive

Employ the 'files:list' command to view the contents of an archive. Use '-l' for a detailed list or 'files:table' for a table format.

```bash
./vendor/bin/cam files:list -l archive.tar.gz # files list (or files:table for table)
```

--------------------------------

### Create New Archive

Source: https://wapmorgan.github.io/UnifiedArchive/docs/Usage.html

Creates a new archive file from specified files and directories. Supports creating archives from single items, multiple items, or complex configurations defining archive names and paths.

```php
# archive all folder content (with original full name)
UnifiedArchive::create('/var/log', 'Archive.zip');

# archive one file (with original full name)
UnifiedArchive::create('/var/log/syslog', 'Archive.zip');

# archive few files / folders
UnifiedArchive::create([$directory, $file, $file2, ...], 'Archive.zip');

```

```php
UnifiedArchive::create([
   '/var/www/original/name.log',           // file **/var/www/original/name.log** will be store with its original name
   '/var/www/site/runtime/logs',           // directory contents will be stored as '/var/www/site/runtime/logs', with its original name
   'insideArchiveName.log' => '/var/www/original/name.log',   // file /var/www/original/name.log will be stored as insideArchiveName.log in archive root
   'insideArchiveDir' => '/var/www/site/runtime/logs',        // directory contents will be stored in insideArchiveDir dir inside archive
   '' => ['/home/user1/docs', '/home/user2/docs'],            // directories user1 and user2 docs contents will be merged and stored in archive root
], 'archive.zip');

```

--------------------------------

### Adjust Compression Level for New Archives (PHP)

Source: https://wapmorgan.github.io/UnifiedArchive/CHANGELOG.html

Set the compression level when creating new archives using `archiveFiles`, `archiveFile`, or `archiveDirectory`. Defaults to `BasicDriver::COMPRESSION_AVERAGE`. Supports zip and gzip formats.

```php
UnifiedArchive::archiveFiles($fileOrFiles, $archiveName, $compressionLevel = BasicDriver::COMPRESSION_AVERAGE)
```

```php
UnifiedArchive::archiveFile($file, $archiveName, $compressionLevel = BasicDriver::COMPRESSION_AVERAGE)
```

```php
UnifiedArchive::archiveDirectory($file, $archiveName, $compressionLevel = BasicDriver::COMPRESSION_AVERAGE)
```

--------------------------------

### UnifiedArchive::can

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Checks if the current driver supports a specific ability for the archive.

```APIDOC
## UnifiedArchive::can

### Description
Checks if current driver supports ability for archive.

### Method
`UnifiedArchive::can(int $ability): boolean`
```

--------------------------------

### Check Driver Ability

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Verifies if the current driver supports a specific ability for the archive.

```php
UnifiedArchive::can(int $ability): boolean
```

--------------------------------

### Extract Specific Files or Directories

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Extracts specified files or directories to an output folder. Supports expanding directories into a list of files with `$expandFilesList`. Returns the number of extracted files or false on failure. Throws EmptyFileListException or ArchiveExtractionException.

```php
UnifiedArchive::extract(
    string $outputFolder,
    array $files,
    boolean $expandFilesList = false
): int|false
```

--------------------------------

### Formats::can

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Checks if any driver supports a specific ability for a given archive format.

```APIDOC
## Formats::can

### Description
Check if any driver supports passed ability for passed format.

### Method
static bool can(string $format, int $ability)

### Parameters
#### Arguments
- `$format` (string) - The `Formats` constant representing the archive format.
- `$ability` (int) - An integer representing the ability to check (e.g., `Abilities::OPEN`).

### Result
`boolean` - True if the format supports the ability, false otherwise.
```

--------------------------------

### Add File from String Content (PHP)

Source: https://wapmorgan.github.io/UnifiedArchive/CHANGELOG.html

Appends a file to an archive using its content provided as a string. The first argument is the desired name of the file within the archive, and the second is the file's content.

```php
UnifiedArchive->addFileFromString(string $inArchiveName, string $content)
```

--------------------------------

### Formats::canOpen, Formats::canStream, Formats::canCreate, Formats::canAppend, Formats::canUpdate, Formats::canEncrypt

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Tests if an archive format supports specific operations like opening, streaming, creating, appending, updating, or encrypted creation by any available driver.

```APIDOC
## Formats::canOpen, Formats::canStream, Formats::canCreate, Formats::canAppend, Formats::canUpdate, Formats::canEncrypt

### Description
Tests if an archive format can be opened/created/appended (`add`)/updated (`delete`)/created encrypted by any driver with current system and php configuration.

### Method
static bool canOpen(string $format)
static bool canStream(string $format)
static bool canCreate(string $format)
static bool canAppend(string $format)
static bool canUpdate(string $format)
static bool canEncrypt(string $format)

### Parameters
#### Arguments
- `$format` (string) - The `Formats` constant representing the archive format.

### Result
`boolean` - True if the format supports the specified capability, false otherwise.
```

--------------------------------

### UnifiedArchive::getPclZipInterface

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Returns a PclzipZipInterface handler for an archive, providing PclZip functions with a PclZip-like interface.

```APIDOC
## UnifiedArchive::getPclZipInterface

### Description
Returns a `PclzipZipInterface` handler for an archive. It provides all PclZip functions in PclZip-like interface for an archive.

### Method
`UnifiedArchive::getPclZipInterface(): PclzipZipInterface`
```

--------------------------------

### Open Password-Protected Archives (PHP)

Source: https://wapmorgan.github.io/UnifiedArchive/CHANGELOG.html

Use the `$password` argument when opening archives encrypted with a password. Currently supports zip, rar, and 7z formats.

```php
UnifiedArchive::open($fileName, $password = null)
```

--------------------------------

### UnifiedArchive::getFormat()

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Retrieves the format of the archive. The format is returned as one of the predefined Formats constants.

```APIDOC
## UnifiedArchive::getFormat()

### Description
Returns format of archive as one of `Formats` constants.

### Method
GET (conceptual)

### Endpoint
N/A (Method call on an instance)

### Parameters
None

### Response
#### Success Response
- **format** (string) - The format of the archive (e.g., 'ZIP', 'TAR').
```

--------------------------------

### Add File from String Content

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Adds a file to the archive using its name and content provided as a string. Returns true on success. Throws ArchiveModificationException on failure.

```php
UnifiedArchive::addFileFromString(
    string $inArchiveName,
    string $content
): boolean
```

--------------------------------

### Extract All Archive Content

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Extracts all files from the archive to a specified output folder, overwriting existing files. Returns the number of extracted files or throws ArchiveExtractionException.

```php
UnifiedArchive::extract(string $outputFolder): int
```

--------------------------------

### UnifiedArchive::extract() (all files)

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Extracts all files from the archive to the specified output folder, overwriting existing files. Returns the number of extracted files upon success. Throws `ArchiveExtractionException` on failure.

```APIDOC
## UnifiedArchive::extract(string $outputFolder)

### Description
Extracts all archive content with full paths to output folder and rewriting existing files. In case of success, number of extracted files is returned.

### Method
POST (conceptual, for modification)

### Endpoint
N/A (Method call on an instance)

### Parameters
#### Query Parameters
- **outputFolder** (string) - Required - The directory where files should be extracted.

### Response
#### Success Response
- **extractedCount** (int) - The number of files successfully extracted.

### Throws
- `ArchiveExtractionException`
```

--------------------------------

### Add Files to Archive

Source: https://wapmorgan.github.io/UnifiedArchive/docs/Usage.html

Adds files or directories to an existing archive. Can add individual files, entire directories recursively, or multiple items at once. The structure of added directories is preserved.

```php
// Add a catalog with all contents with full paths
 $archive->add('/var/log/');

 // To add one file (will be stored as one file "/var/log/syslog")
 $archive->add('/var/log/syslog');

 // To add some files or catalogs (all catalogs structure in paths will be kept)
 $archive->add([$directory, $file, $file2, ...]);

```

--------------------------------

### UnifiedArchive::getFiles()

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Retrieves a list of all files stored in the archive. An optional filter can be provided to match filenames using `fnmatch()`.

```APIDOC
## UnifiedArchive::getFiles(?string $filter = null)

### Description
Returns full list of files stored in an archive. If `$filter` is passed, will return only matched by `fnmatch()` files.

### Method
GET (conceptual)

### Endpoint
N/A (Method call on an instance)

### Parameters
#### Query Parameters
- **filter** (string|null) - Optional. A filter string to match filenames using `fnmatch()`.

### Response
#### Success Response
- **files** (string[]) - An array of filenames matching the filter (or all files if no filter is provided).
```

--------------------------------

### UnifiedArchive::extract() (specific files)

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Extracts specified files or directories to the output folder. Supports expanding directory lists into individual files using the `$expandFilesList` parameter. Returns the number of extracted files or false on failure. Throws `EmptyFileListException` or `ArchiveExtractionException`.

```APIDOC
## UnifiedArchive::extract(string $outputFolder, array $files, boolean $expandFilesList = false)

### Description
Extracts given files or directories to output folder. If directories is passed, you need to use `$expandFilesList` feature that will expand directory names to all nested files (e.g `dir` will be expanded to `dir/file1, dir/file2, dir/subdir/file3`). In case of success, number of extracted files is returned.

### Method
POST (conceptual, for modification)

### Endpoint
N/A (Method call on an instance)

### Parameters
#### Query Parameters
- **outputFolder** (string) - Required - The directory where files should be extracted.
- **files** (array) - Required - An array of filenames or directory names to extract.
- **expandFilesList** (boolean) - Optional, defaults to false - If true, directory names in the `$files` array will be expanded to include all nested files.

### Response
#### Success Response
- **extractedCount** (int|false) - The number of files successfully extracted, or false on failure.

### Throws
- `EmptyFileListException`
- `ArchiveExtractionException`
```

--------------------------------

### UnifiedArchive::addFileFromString()

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Adds a file to the archive from a string content. Returns true on success. Throws `ArchiveModificationException` on failure.

```APIDOC
## UnifiedArchive::addFileFromString(string $inArchiveName, string $content)

### Description
Packs file in an archive. If case of success, `true` is returned.

### Method
POST (conceptual, for modification)

### Endpoint
N/A (Method call on an instance)

### Parameters
#### Query Parameters
- **inArchiveName** (string) - Required - The desired name of the file within the archive.
- **content** (string) - Required - The content of the file as a string.

### Response
#### Success Response
- **success** (boolean) - True if the file was added successfully.

### Throws
- `ArchiveModificationException`
```

--------------------------------

### Extract Archive Contents

Source: https://wapmorgan.github.io/UnifiedArchive/docs/Usage.html

Extracts all or specific files and directories from the archive to a specified location on disk. Can extract entire archives, selected files, or specific directories recursively.

```php
// to unpack all contents of archive to "output" folder
 $archive->extract(__DIR__ . '/output');

 // to unpack specific files (README.md and composer.json) from archive to "output" folder
 $archive->extract(__DIR__ . '/output', ['README.md', 'composer.json']);

 // to unpack the "src" catalog with all content from archive into the "sources" catalog on a disk
 $archive->extract(__DIR__ . '/output', 'src/', true);

```

--------------------------------

### Formats::getFormatMimeType

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Retrieves the MIME type associated with a given archive format. Returns null if the format is not recognized.

```APIDOC
## Formats::getFormatMimeType

### Description
Returns mime type for passed format. Returns `null` if not found.

### Method
static string|null getFormatMimeType(string $format)

### Parameters
#### Arguments
- `$format` (string) - The `Formats` constant representing the archive format.

### Result
`?string` - The MIME type of the format, or `null` if not found.
```

--------------------------------

### Extract Archive Contents

Source: https://wapmorgan.github.io/UnifiedArchive

The 'archive:extract' command is used to extract all contents of an archive to a specified output directory.

```bash
./vendor/bin/cam archive:extract archive.tar.gz ./OUTPUT/ # extraction all archive
```

--------------------------------

### UnifiedArchive::getFileContent()

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Retrieves the entire content of a file within the archive as a raw string. Throws `NonExistentArchiveFileException` if the file is not found.

```APIDOC
## UnifiedArchive::getFileContent(string $fileName)

### Description
Returns content of in-archive file as raw string. If file is not in archive, `NonExistentArchiveFileException` is thrown.

### Method
GET (conceptual)

### Endpoint
N/A (Method call on an instance)

### Parameters
#### Query Parameters
- **fileName** (string) - Required - The name of the file to get the content of.

### Response
#### Success Response
- **content** (string) - The raw string content of the file.
```

--------------------------------

### UnifiedArchive::getSize()

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Retrieves the total size of the archive file in bytes.

```APIDOC
## UnifiedArchive::getSize()

### Description
Returns size of archive file in bytes.

### Method
GET (conceptual)

### Endpoint
N/A (Method call on an instance)

### Parameters
None

### Response
#### Success Response
- **size** (int) - The size of the archive file in bytes.
```

--------------------------------

### Count Files in Archive

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Returns the total number of files stored within the archive.

```php
UnifiedArchive::countFiles()
```

--------------------------------

### UnifiedArchive::delete()

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Deletes specified files or directories from the archive. Supports deleting individual files/directories or lists of them. `$expandFilesList` can be used to expand directory names to all nested files. Returns the number of deleted files on success. Throws `EmptyFileListException`, `UnsupportedOperationException`, or `ArchiveModificationException` on error.

```APIDOC
## UnifiedArchive::delete(string|array $fileOrFiles, $expandFilesList = false)

### Description
Deletes passed `$fileOrFiles` from archive. `$fileOrFiles` is a string with file/directory name or an array of files or directories. In case of success, number of deleted files will be returned.

### Method
DELETE (conceptual)

### Endpoint
N/A (Method call on an instance)

### Parameters
#### Query Parameters
- **fileOrFiles** (string|array) - Required - The name of the file/directory or an array of names to delete.
- **expandFilesList** (boolean) - Optional - If true, directory names will be expanded to include all nested files for deletion.

### Response
#### Success Response
- **deletedCount** (int|false) - The number of files successfully deleted, or false on failure.

### Throws
- `EmptyFileListException`
- `UnsupportedOperationException`
- `ArchiveModificationException`
```

--------------------------------

### UnifiedArchive::getCompressedSize()

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Retrieves the compressed size of all files stored within the archive in bytes. This can help measure the effectiveness of the archive's compression.

```APIDOC
## UnifiedArchive::getCompressedSize()

### Description
Returns size of all stored files in archive with archive compression in bytes. This can be used to measure efficiency of format compression.

### Method
GET (conceptual)

### Endpoint
N/A (Method call on an instance)

### Parameters
None

### Response
#### Success Response
- **compressedSize** (int) - The compressed size of all files in the archive in bytes.
```

--------------------------------

### UnifiedArchive::getComment()

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Retrieves the comment associated with the archive. Returns null if the comment is not supported or not present.

```APIDOC
## UnifiedArchive::getComment()

### Description
Returns comment of archive or null (if not supported nor present).

### Method
GET (conceptual)

### Endpoint
N/A (Method call on an instance)

### Parameters
None

### Response
#### Success Response
- **comment** (?string) - The archive comment, or null if not available.
```

--------------------------------

### Check if File Exists in Archive

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Verifies if a specific file is present in the archive.

```php
UnifiedArchive::hasFile(string $fileName): boolean
```

--------------------------------

### UnifiedArchive::getOriginalSize()

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Retrieves the uncompressed size of all files stored within the archive in bytes. This indicates the storage space the extracted files will occupy.

```APIDOC
## UnifiedArchive::getOriginalSize()

### Description
Returns size of all stored files in archive without compression in bytes. This can be used to measure size that extracted files will use.

### Method
GET (conceptual)

### Endpoint
N/A (Method call on an instance)

### Parameters
None

### Response
#### Success Response
- **originalSize** (int) - The uncompressed size of all files in the archive in bytes.
```

--------------------------------

### UnifiedArchive::getFileData()

Source: https://wapmorgan.github.io/UnifiedArchive/docs/API.html

Retrieves an ArchiveEntry object containing detailed information about a specific file within the archive. Throws `NonExistentArchiveFileException` if the file is not found.

```APIDOC
## UnifiedArchive::getFileData(string $fileName)

### Description
Returns `ArchiveEntry` that contains all specific information about file stored in archive and described later in the document. If file is not in archive, `NonExistentArchiveFileException` is thrown.

### Method
GET (conceptual)

### Endpoint
N/A (Method call on an instance)

### Parameters
#### Query Parameters
- **fileName** (string) - Required - The name of the file to retrieve data for.

### Response
#### Success Response
- **archiveEntry** (ArchiveEntry) - An object containing detailed information about the file.
```
Tokens:
Raw