README

UnifiedArchive - unified interface to all popular archive formats (zip # 7z # rar # gz # bz2 # xz # cab # tar # tar.gz # tar.bz2 # tar.x # tar.Z # iso-9660) for listing, reading, extracting and creation + built-in console archive manager.

Contents:

1. Preamble
2. Installation
3. Reading of archive
   1. Archive modification
   2. Archive creation
4. Formats support
5. API
   1. UnifiedArchive
   2. ArchiveEntry
6. Built-in console archive manager
7. Changelog

Preamble

If on your site there is a possibility of uploading of archives and you would like to add functionality of their automatic unpacking and viewing with no dependency on format of the archive, you can use this library.

Installation

Composer package: wapmorgan/unified-archive [1]

{
    "require": {
        "wapmorgan/unified-archive": "~0.1.2"
    }
}

Reading of archive

1. Import a class

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

2. At the beginning, try to open the file with automatic detection of a format by name. In case of successful recognition a UnifiedArchive object will be returned. In case of failure - null

   $archive = UnifiedArchive::open('filename.rar');
   // or
   $archive = UnifiedArchive::open('filename.zip');
   // or
   $archive = UnifiedArchive::open('filename.7z');
   // or
   $archive = UnifiedArchive::open('filename.gz');
   // or
   $archive = UnifiedArchive::open('filename.bz2');
   // or
   $archive = UnifiedArchive::open('filename.xz');
   // or
   $archive = UnifiedArchive::open('filename.cab');
   // or
   $archive = UnifiedArchive::open('filename.tar');
   // or
   $archive = UnifiedArchive::open('filename.tar.gz');
   // or
   $archive = UnifiedArchive::open('filename.tar.bz2');
   // or
   $archive = UnifiedArchive::open('filename.tar.xz');
   // or
   $archive = UnifiedArchive::open('filename.tar.Z');
   // or
   $archive = UnifiedArchive::open('filename.iso');

3. Further, read the list of files of archive (note: this function returns only names of files)

   var_dump($archive->getFileNames()); // array with files list

4. Further, check that specific file is in archive.

   var_dump($archive->isFileExists('README.md')); // boolean

5. Further, you can get additional information about concrete file by getFileData() method

   var_dump($archive->getFileData('README.md')); // ArchiveEntry with file information

6. Further, you can get raw file contents by getFileContent() method

   var_dump($archive->getFileContent('README.md')); // string

7. Further, you can unpack any internal catalog or the whole archive with files on a disk. The extractFiles() method is engaged in it. In case of success, it returns number of the extracted files, in case of failure - false. Initial and final symbol of division of catalogs are very important! Don't forget them.

   $archive->extractFiles($outputFolder, $archiveFiles);
   
   // to unpack all contents of archive
   $archive->extractFiles('output');
   
   // to unpack specific files from archive
   $archive->extractFiles('output', ['README.md', 'composer.json']);
   
   // to unpack the src catalog in archive in the sources catalog on a disk
   $archive->extractFiles('output', '/src/', true);
   
   // to unpack the bookmarks catalog in archive in the sources catalog on a
   // disk
   $archive->extractFiles('output', '/bookmarks/', true);

Archive modification

1. Deletion files from archive

   // To delete a single file from an archive
   $archive->deleteFiles('README.md');
   
   // To delete multiple files from an archive
   $archive->deleteFiles(['README.md', 'MANIFEST.MF']);
   
   // To delete directories from archive
   $archive->deleteFiles('/src/', true);

   In case of success the number of successfully deleted files will be returned.

2. Addition files to archive

   // To add completely the catalog with all attached files and subdirectories (all directory contents will be stored in archive root)
   $archive->addFiles('/var/log');
   
   // To add one file (will be stored as one file "syslog")
   $archive->addFiles('/var/log/syslog');
   
   // To add some files or catalogs (all catalogs structure in paths will be kept)
   $archive->addFiles([$directory, $file, $file2, ...]);

Archive creation

To pack completely the catalog with all attached files and subdirectories in new archive:

UnifiedArchive::archiveFiles('/var/log', 'Archive.zip');

// To pack one file
UnifiedArchive::archiveFiles('/var/log/syslog', 'Archive.zip');

// To pack some files or catalogs
UnifiedArchive::archiveFiles([$directory, $file, $file2, ...], 'Archive.zip');

Also, there is extended syntax for addFiles() and archiveFiles():

UnifiedArchive::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');

Formats support

API

UnifiedArchive

Static Methods

• Archive opening:

• Archive creation. These methods create archive with one file, directory contents or with custom files list.

Object methods

• Archive information methods:

• Archive content information methods:

• Archive modification methods:

Notes:

public function extractFiles($outputFolder, $node = '/'): integer

Unpacks any of internal catalogs archive with full preservation of structure of catalogs in the catalog on a hard disk. Returns number of extracted files.

public function deleteFiles($fileOrFiles): integer

Updates existing archive by removing files from it. Returns number of deleted files.

public function addFiles($fileOrFiles): integer

Updates existing archive by adding new files. Returns total number of files after addition.

static public function archiveFiles($fileOrFiles, $aname, $simulation = false): integer | boolean | array

Archives files transferred in the first argument. Returns number of the archived files in case of success, in case of failure - false. If as the third argument is true, then the real archiving doesn't happen, and the result contains the list of the files chosen for an archiving, their number and total size.

ArchiveEntry

The class representing a file from archive as result of a call to getFileData(). It contains fields with file information:

Built-in console archive manager

UnifiedArchive is distributed with a unified console program to manipulate popular archive formats. This script is stored in vendor/bin/cam.

It supports all formats that UnifiedArchive does and can be used to manipulate archives without other software. To check your configuration and check formats support launch it with -f flag in console:

$ php vendor/bin/cam -f

Full usage help

USAGE: cam (-l|--list)  ARCHIVE
       cam (-t|--table) ARCHIVE
       cam (-i|--info)  ARCHIVE
       cam (-e|--extract) [--output=DIR] [--replace=(all|ask|none|time|size)] [--flat=(file|path)] [--exclude=PATTERN] ARCHIVE [FILES_IN_ARCHIVE...]
       cam (-p|--print)   ARCHIVE FILES_IN_ARCHIVE...
       cam (-d|--details) ARCHIVE FILES_IN_ARCHIVE...
       cam (-x|--delete)  ARCHIVE FILES_IN_ARCHIVE...
       cam (-a|--add)     ARCHIVE FILES_ON_DISK...
       cam (-c|--create)  ARCHIVE FILES_ON_DISK...
       cam (-f|--formats)

ACTIONS:
      -l(--list)    List files
      -t(--table)   List files in table
      -i(--info)    Summary about archive

      -e(--extract) Extract from archive

      -p(--print)   Print files' content
      -d(--details) Details about files
      -x(--delete)  Delete files

      -a(--add)     Add to archive
      -c(--create)  Create new archive

Changelog

To see all changes in library go to CHANGELOG file.