PEAR Manual
Prev |  | Next

# Archive_Tar::addModify()

Archive_Tar::addModify() -- add files or directories

## Synopsis

    require_once 'Archive/Tar.php';

``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

Table 38-1. Possible PEAR_Error values

Error code | Error message | Reason | Solution
--- | --- | --- | ---
`NULL` | "Invalid file list" | The argument for the function is not correctly formatted or build. | Check for typing mistakes in the argument
`NULL` | "Unable to open in write mode `file name`" | The file permissions for an existing file do not allow writing or the file is locked. | Check permissions and possible competive programs using the file.
`NULL` | "Invalid file list" | Archive is empty or corrupted |
`NULL` | "File `filename` does not exist" | A file you want to add to the archive does not exist. | Check for typing mistakes in the function argument.
`NULL` | "Directory `dirname` can not be read" | A directory or a file in it you want to add to the archive does not exists or the permissions for reading the directory does not allow access. | Check for typing mistakes in the function argument and permissions.
`NULL` | "Unable to open file `filename`in binary read mode" | The file to add to the archive could not be read. | Check for typing mistakes in the function argument and file permissions.

## Note

This function can not be called statically.

## Example

Example 38-1. Add files to a compressed archive in a new directory
    $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

Example 38-2. Add files to a compressed archive moving to a new directory
    $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

Example 38-3. Add files to a compressed archive moving to a new directory (especially for Windows)
    $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.

Prev | Home | Next
Archive_Tar::add() | Up | Archive_Tar::create()