SevenZip 🔧

A PHP package to compress and decompress files using 7zip CLI.

Installation

Install the package via Composer:

composer require verseles/sevenzip

<center>️Star the project to help us reach move devs!️</center>

Usage

Compression

To compress a file or directory:

$sevenZip = new SevenZip();
$sevenZip->format('7z')
         ->source('/path/to/source/file/or/directory')
         ->target('/path/to/archive.7z')
         ->compress();

Compression Options

• Format: You can set the compression format using the format() method. Well known formats include 7z, zip, tar, lz4, lz5, bzip2, and zstd. Your OS needs to support the selected format.
• Compression Level: You can adjust the compression level using the faster(), slower(), mx(), and ultra() methods.
• Custom Flags: You can add custom compression flags using the addFlag() method.
• Progress Callback: You can set a progress callback using the progress() method to monitor the compression progress.
• Tar Before: You can enable option to create a tar archive before compressing using the tarBefore() method. This is useful for preserving file permissions and attributes.

[!WARNING] The format support depends on your system, architecture, etc. You can always use format() method to set your custom format.

Any set format() which starts with tar. will automatically enable tarBefore(). To disable add ->forceTarBefore(false)

Extraction

To extract an archive:

$sevenZip = new SevenZip();
$sevenZip->source('/path/to/archive.7z')
         ->target('/path/to/extract/directory')
         ->extract();

If the extracted file is a single tar archive, it will be extracted and the tar file deleted. To avoid this behavior, add ->autoUntar(false)

Encryption

You can encrypt the compressed archive using a password:

$sevenZip = new SevenZip();
$sevenZip->source('/path/to/source/file/or/directory')
         ->target('/path/to/encrypted_archive.7z')
         ->encrypt('your_password')
         ->compress();

By default, the file names are also encrypted (not possible in zip format). If you want to disable file name encryption, you can use the notEncryptNames() method:

$sevenZip->notEncryptNames();

For ZIP archives, you can specify the encryption method using the setZipEncryptionMethod() method. Available options are 'ZipCrypto' (not secure), ' AES128', 'AES192', or 'AES256'. The default is 'AES256'.

$sevenZip->setZipEncryptionMethod('AES256');

Decryption

To decrypt an encrypted archive during extraction:

$sevenZip = new SevenZip();
$sevenZip->source('/path/to/encrypted_archive.7z')
         ->target('/path/to/extract/directory')
         ->decrypt('your_password')
         ->extract();

Including and Excluding Files

SevenZip allows you to include or exclude specific files when compressing or extracting archives.

Including Files

To include specific files in the archive, use the include method:

$sevenZip->include('*.avg')->compress();

Excluding Files

To exclude specific files from the archive, use the exclude method:

$sevenZip->exclude(['*.md', '*.pdf'])->compress();

Note that you can use both include and exclude methods together to fine-tune the files included in the archive.

You can pass a single file pattern, an array of file patterns or the path to a txt file with a list of patterns inside to the exclude and include methods.

Checking format support

You can check if a specific format or multiple formats are supported by the current 7-Zip installation using the checkSupport method:

$sevenZip = new SevenZip();

// Check if a single format is supported
if ($sevenZip->checkSupport('zip')) {
    echo "ZIP format is supported.";
} else {
    echo "ZIP format is not supported.";
}

// Check if multiple formats are supported
if ($sevenZip->checkSupport(['zip', 'tar', '7z'])) {
    echo "ZIP, TAR, and 7Z formats are supported.";
} else {
    echo "One or more formats are not supported.";
}

TODO / WIP

• [x] Full support for add flags (7z switches)
• [x] Add custom support for gz, xz, etc. by using tar flags
• [x] Use tar to keep original file permissions and other attributes
• [x] Auto untar on extraction
• [x] Filter files by patterns
• [x] Encrypt and decrypt
• [ ] Test files using 7z test command
• [x] Detect supported formats by the OS
• [x] Add built-in binaries for mac and linux
• [x] ~~Use docker for PHPUnit tests~~ not needed with built-in binaries
• [ ] Use native zstd, brotli, and others as fallback for these formats

Contributing

Contributions are welcome! If you'd like to contribute to this project, please follow these steps:

1. Fork the repository
2. Create a new branch for your feature or bug fix
3. Make your changes and commit them with descriptive commit messages
4. Push your changes to your forked repository
5. Submit a pull request to the main repository

Please ensure that your code follows the project's coding style and conventions. Also, include appropriate tests for your changes.

Testing

To run the tests, execute the following command:

composer test

Documentation / API

Here is the Documentation / API section of the README, updated with missing public methods and ordered alphabetically:

Documentation / API

addFlag(string $flag, $value = null): static

Adds a compression flag.

Parameters

• $flag: The compression flag to be added.
• $value (optional): The value for the flag.

Returns: The current instance of the SevenZip class.

Example

$sevenZip->addFlag('mfb', 64);

checkSupport(string|array $extensions): bool

Checks if the given extension(s) are supported by the current 7-Zip installation.

Parameters

• $extensions: The extension or an array of extensions to check.

Returns: Returns true if all the given extensions are supported, false otherwise.

Example

$sevenZip = new SevenZip();

// Check if a single format is supported
$isZipSupported = $sevenZip->checkSupport('zip');

// Check if multiple formats are supported
$areFormatsSupported = $sevenZip->checkSupport(['zip', 'tar', '7z']);

compress(): string

Compresses a file or directory.

Returns: the command output on success.

Throws

• InvalidArgumentException: If target path, or source path is not set.

Example

$sevenZip->compress();

copy(): static

Configures no compression (copy only) settings based on the specified format.

Returns: The current instance for method chaining.

decrypt(string $password): self

Decrypts the data using the provided password.

Parameters

• $password: The password to decrypt the data.

Returns: The current instance of this class.

encrypt(string $password): self

Encrypts the data using the provided password.

Parameters

• $password: The password to encrypt the data.

Returns: The current instance of this class.

extract(): string

Extracts an archive.

Returns: the command output on success.

Throws

• InvalidArgumentException: If format, archive path, or extract path is not set.

Example

$sevenZip->extract();

faster(): static

Sets the compression level to faster.

Returns: The current instance of the SevenZip class.

deleteSourceAfterExtract(bool $delete = true): self

Sets whether to delete the source archive after successful extraction.

Parameters

• $delete: Whether to delete the source archive after extraction. Default is true.

Returns: The current instance of the SevenZip class.

Example

$sevenZip->deleteSourceAfterExtract();

fileInfo(): string

Retrieves information about the specified archive file.

Returns: The file information output from the 7-Zip command.

Throws

• InvalidArgumentException: If the archive path is not set.

Example

$info = $sevenZip->fileInfo();

fileList(): string

Lists the contents of the specified archive file.

Returns: The file list output from the 7-Zip command.

Throws

• InvalidArgumentException: If the archive path is not set.

Example

$list = $sevenZip->fileList();

flagrize(array $flagsAndValues): array

Formats flags and values into an array of strings suitable for passing to 7-Zip commands.

Parameters

• $flagsAndValues: An associative array of flags and their corresponding values. If the value is null, the flag will be added without an equal sign.

Returns: An array of formatted flag strings.

Example

$formattedFlags = $sevenZip->flagrize(['m0' => 'lzma2', 'mx' => 9]);
// Output: ['-m0=lzma2', '-mx=9']

format(string $format): static

Sets the archive format.

Parameters

• $format: The compression format to be used.

Returns: The current instance of the SevenZip class.

Example

$sevenZip->format('7z');

getCustomFlags(): array

Gets the custom compression flags.

Returns: The custom compression flags that have been added.

getEncryptNames(): ?bool

Gets whether or not file names are encrypted.

Returns: Whether or not file names are encrypted, or null if not set.

getFormat(): string

Gets the archive format.

Returns: The compression format to be used.

getInfo()

Returns information about 7-Zip, formats, codecs, and hashers.

Returns: The output from the 7-Zip command.

getLastProgress(): int

Gets the last reported progress.

Returns: The last reported progress percentage.

getPassword(): ?string

Gets the password used for encryption or decryption.

Returns: The pa