Home » File Formats » Archive_Tar » Manual

Archive_Tar::Archive_Tar()

Archive_Tar::Archive_Tar() – constructor

Synopsis

void Archive_Tar ( string $tarname , mixed $compress = null )

Description

The constructor declares a new Archive_Tar object, identifying it by the name of the tar file.

Parameter

• string $tarname - the name of the tar archive to work with
• mixed $compress - if TRUE, indicates that the archive is compressed (using gzip). if NULL the archive is not compressed, if 'gz' or 'bz2', indicates that the archive is compressed with gzip or bz2. For compatibility reason the boolean value TRUE means 'gz'.

Archive_Tar::add()

Archive_Tar::add() – add files or directories

Synopsis

boolean add ( mixed $filelist )

Description

This method adds files and directories to an existing archive. If the archive does not exist, it attempts to create it. The files and directories listed are added at the end of the archive, even if a file with the same name is already archived.

Parameter

• mixed $filelist - an array of filenames and directory names, or a single string with names separated by a single blank space. For each directory added in the archive, the files and sub-directories are also added.

Return value

boolean - Returns TRUE on success, FALSE on failure.

Throws

Note

This function can not be called statically.

Example

Add files to a compressed archive

<?php
$tar_object = new Archive_Tar("tarname.tar.gz", true);
$v_list[0]="dev/file.txt";
$v_list[1]="dev/data/";
$v_list[2]="log/file.log";
$tar_object->add($v_list);
?>

Archive_Tar::addModify()

Archive_Tar::addModify() – add files or directories

Synopsis

boolean addModify ( mixed $filelist , string $add_dir , string $remove_dir = '' )

Description

This methods add files and directories listed in filelist at the end of the existing archive.

If the archive does not exists it attempts to create it. If a file or directory is already in the archive it will only be added at the end of the archive. There is no update of the existing archived file or directory. However while extracting the archive, the last file will replace the first one. This results in a none optimization of the archive size. If a file or directory does not exists, it is ignored.

Parameter

• mixed $filelist - an array of filenames and directory names, or a single string with names separated by a single blank space.
• string $add_dir - a string which contains a path to be added to the memorized path of each element in the list.
• string $remove_dir - a string which contains a path to be removed from the memorized path of each element in the list, when relevant. The path indicated in add_dir will be added at the beginning of the memorized path of each file/directory listed. However it can be set to empty ''. The adding of a path is done after the removing of path. The path add/remove ability enables the user to prepare an archive for extraction in a different path than the original path.

Return value

boolean - Returns TRUE on success, FALSE on failure.

Throws

Note

This function can not be called statically.

Example

Add files to a compressed archive in a new directory

<?php
$tar_object = new Archive_Tar("tarname.tar");
$v_list[0]="dev/file.txt";
$v_list[1]="dev/data/";
$v_list[2]="log/file.log";
$tar_object->addModify($v_list, "install");
// files are stored in the archive as :
//   install/file.txt
//   install/data
//   install/data/file1.txt
//   install/data/... all the files and sub-dirs of data/
//   install/file.log
?>

Add files to a compressed archive moving to a new directory

<?php
$tar_object = new Archive_Tar("tarname.tar");
$v_list[0]="dev/file.txt";
$v_list[1]="dev/data/";
$v_list[2]="log/file.log";
$tar_object->addModify($v_list, "install", "dev");
// files are stored in the archive as :
//   install/file.txt
//   install/data
//   install/data/file1.txt
//   install/data/...         all the files and sub-dirs of data/
//   install/log/file.log
?>

Add files to a compressed archive moving to a new directory (especially for Windows)

<?php
$tar_object = new Archive_Tar("tarname.tar");
$v_list[0]="d:\\dev\\file.txt";
$v_list[1]="d:\\dev\\data\\";
$v_list[2]="d:\\log\\file.log";
$tar_object->addModify($v_list, "install/temp", "d:\\dev");
// files are stored in the archive as :
//   install/temp/file.txt
//   install/temp/data
//   install/temp/data/file1.txt
//   install/temp/data/...         all the files and sub-dirs of data/
//   install/temp/log/file.log
?>

On Windows system, Windows path format can be used. However if the files are using a Windows path, the $remove_dir parameter must also be in Windows path format. The $add_dir parameter can be in Windows or Unix path format.

Archive_Tar::create()

Archive_Tar::create() – create archive file

Synopsis

boolean create ( mixed $filelist )

Description

This method creates the archive file and adds the listed files or directories.

If a file with the same tar name exists and is writable, it is replaced by the new tar archive (it is not an 'add', but a 'create'). If a file exists and is write-protected or is a folder, the method raises a PEAR_Error.

Parameter

• mixed $filelist - an array of filenames and directory names, or a single string with names separated by a single blank space. For each directory added in the archive, the files and sub-directories are also added.

Return value

boolean - Returns TRUE on success, FALSE on failure.

Throws

Note

This function can not be called statically.

Example

Creating an archive

<?php
$tar_object = new Archive_Tar("myArchive.tar");

// print errors
$tar_object->setErrorHandling(PEAR_ERROR_PRINT);  

// Archive content
$v_list[0]="file.txt";
// the slash is optional
$v_list[1]="data/"; 
$v_list[2]="file.log";

// create the archive
$tar_object->create($v_list);
?>

Creating a compressed archive, use a string as create() argument

<?php
$tar_object = new Archive_Tar("tarname.tgz", true);
$tar_object->setErrorHandling(PEAR_ERROR_PRINT);
$tar_object->create("file.txt data/ file.log");
?>

Archive_Tar::createModify()

Archive_Tar::createModify() – create a new archive

Synopsis

boolean createModify ( array $filelist , string $add_dir , string $remove_dir = '' )

Description

This method creates the archive file and adds the listed files or directories.

If the file already exists and is writable, it is replaced by the new tar. It is a 'create' and not a 'add'. If the file exists and is read-only or is a directory, it is not replaced.

Parameter

• mixed $filelist - an array of filenames and directory names, or a single string with names separated by a single blank space.
• string $add_dir - contains a path to be added to the memorized path of each element in the list.
• string $remove_dir - contains a path to be removed from the memorized path of each element in the list, when relevant. Default is an empty string.

Return value

boolean - Returns TRUE on success, FALSE on failure.

Throws

Note

This function can not be called statically.

Example

Create a new compressed archive in a new directory

<?php
$tar_object = new Archive_Tar("tarname.tgz", true);
$tar_object->setErrorHandling(PEAR_ERROR_PRINT);
$v_list[0]="dev/file.txt";
$v_list[1]="dev/data/";
$v_list[2]="log/file.log";
$tar_object->createModify($v_list, "install", "dev");
// files are stored in the archive as :
//   install/file.txt
//   install/data
//   install/data/file1.txt
//   install/data/... all the files and sub-dirs of data/
//   install/log/file.log
?>

Create a new compressed archive in a new directory (especially for Windows)

<?php
$tar_object = new Archive_Tar("tarname.tgz", true);
$tar_object->setErrorHandling(PEAR_ERROR_PRINT);
$v_list[0]="c:\\dev\\file.txt";
$v_list[1]="c:\\dev\\data\\";
$v_list[2]="c:\\log\\file.log";
$tar_object->createModify($v_list, "install/temp", "c:\\dev");
// files are stored in the archive as :
//   install/temp/file.txt
//   install/temp/data
//   install/temp/data/file1.txt
//   install/temp/data/... all the files and sub-dirs of data/
//   install/temp/log/file.log
?>

Archive_Tar::extract()

Archive_Tar::extract() – extract files

Synopsis

boolean extract ( string $path )

Description

Extracts the files from the archive into the given path.

While extracting a file: If the file already exists it is replaced without looking for last modification date. If the file already exists and is write protected, the extraction is aborted. If a directory with the same name already exists, the extraction is aborted.

However the result can be a partial extraction that may need to be manually cleaned.

Parameter

• string $path - the destination path to extract

Return value

boolean - Returns TRUE on success, FALSE on failure.

Throws

Note

This function can not be called statically.

Example

Extract compressed archive

<?php
$tar = new Archive_Tar('archive.tar.gz', true);
$result = $tar->extract('/home/myFolder');
?>

Archive_Tar::extractList()

Archive_Tar::extractList() – extract a list files

Synopsis

boolean extractList ( array $filelist , string $path = '' , string $remove_path = '' )

Description

This method extracts only the files from the archive that are indicated in the $filelist. These files are extracted in the current directory or in the directory indicated by the optional $path parameter.

Parameter

• string $filelist - an array of filenames and directory names, or a single string with names separated by a single blank space.
• string $path - the path of the directory where the files and/or directory need to by extracted.
• string $remove_path - part of the memorized path that can be removed if present at the beginning of the files or directories path.

Return value

boolean - Returns TRUE on success, FALSE on failure.

Throws

Note

This function can not be called statically.

Example

Extract compressed archive

<?php
// tarname.tar with files :
//   dev/data/file.txt
//   dev/data/log.txt
//   readme.txt

$tar_object = new Archive_Tar("tarname.tar");
$tar_object->extractList("dev/data/file.txt readme.txt", "install",
                         "dev");

// Files will be extracted there :
//   install/data/file.txt
//   install/readme.txt
?>

Archive_Tar::extractModify()

Archive_Tar::extractModify() – extract files to a new dir

Synopsis

boolean extractModify ( string $path , string $remove_path )

Description

This method extracts all the content of the archive in the directory indicated by path. When relevant the memorized path of the files or directories can be modified by removing the remove_path path at the beginning of the file or directory path.

While extracting a file: If the file already exists it is replaced without looking for last modification date. If the file already exists and is write protected, the extraction is aborted. If a directory with the same name already exists, the extraction is aborted.

While extracting a directory, if a file with the same name already exists, the extraction is aborted. While extracting a file/directory if the destination directory exist and is write protected, or does not exist but can not be created, the extraction is aborted. If after extraction an extracted file does not show the correct stored file size, the extraction is aborted.

Parameter

• string $path - the path of the directory where the files and/or directories need to by extracted.
• string $remove_path - part of the memorized path that can be removed if present at the beginning of the files or directories path.

Return value

boolean - Returns TRUE on success, FALSE on failure.

Throws

Note

This function can not be called statically.

Example

Extract compressed archive into a new directory ignoring the old one

Extract compressed archive into a new directory ignoring the old one (especilly for Windows)

Archive_Tar::listContent()

Archive_Tar::listContent() – list files and directories in archive

Synopsis

array listContent ( )

Description

Lists the files and the directories of the archive.

Return value

array - each array entry represents a file or folder. The array is not sorted, so the index shows the position of the file or directory in the archive.

Each entry contains the following information:

• $file['filename'] - Name and path of the file/dir.
• $file['mode'] - File permissions (result of fileperms())
• $file['uid'] - user id
• $file['gid'] - group id
• $file['size'] - filesize
• $file['mtime'] - Last modification time (result of filemtime())
• $file['typeflag'] - empty for file, "5" for directory

Throws

Note

This function can not be called statically.

Example

List archive content

<?php
$tar_object = new Archive_Tar("tarname.tar");

if (($v_list  =  $tar_object->listContent()) != 0) {
    for ($i=0; $i<sizeof($v_list); $i++) {
        echo "Filename :'".$v_list[$i]['filename']."'<br>";
        echo " .size :'".$v_list[$i]['size']."'<br>";
        echo " .mtime :'".$v_list[$i]['mtime']."' (".
             date("l dS of F Y h:i:s A", $v_list[$i]['mtime']).")<br>";
        echo " .mode :'".$v_list[$i]['mode']."'<br>";
        echo " .uid :'".$v_list[$i]['uid']."'<br>";
        echo " .gid :'".$v_list[$i]['gid']."'<br>";
        echo " .typeflag :'".$v_list[$i]['typeflag']."'<br>";
   }
}
?>

Archive_Tar::extractInString()

Archive_Tar::extractInString() – extract one file and return it as a string

Synopsis

boolean extractInString ( string $path )

Description

This method extracts the file identified by path from the archive and returns it as a string. It does not use temporary files.

Parameter

• string $path - the path of the file to extract

Return value

string - the content of the extracted file

Throws

Note

This function can not be called statically.

Example

Extract a file in a string

Archive_Tar::addString()

Archive_Tar::addString() – add a string in the archive

Synopsis

boolean addString ( string $filename , string $content )

Description

This method adds the string content in the archive like a file with full filename filename.

If the archive does not exists it attempts to create it.

Parameter

• string $filename - the path and filename that will be associated with the added string in the archive.
• string $content - the string to add in the archive as a file.

Return value

boolean - Returns TRUE on success, FALSE on failure.

Throws

Note

This function can not be called statically.

Example

Add a string in a compressed archive

<?php
$tar_object = new Archive_Tar("tarname.tgz");
$content = "this file was generated from a string";
$tar_object->addString("data/readme.txt", $content);
// A file is created in the archive with name :
//   data/readme.txt
?>