PEAR Manual
Prev |  | Next

# Archive_Tar::extractModify()

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

## Synopsis

    require_once 'Archive/Tar.php';

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

Table 38-1. Possible PEAR_Error values

Error code | Error message | Reason | Solution
--- | --- | --- | ---
`NULL` | " Unable to open in read mode `archive` " | The file is exclusive locked by another application. | Check for other applications working on the file. This can not be caused by a competive processing the archive with Archive_Tar
`NULL` | " Unable to open in write mode `archive` " | The file is locked by another application. | Check for other applications working on the file. This maybe caused by a competive processing the archive with Archive_Tar
`NULL` | " Invalid extractmodify mode `mode` " | Implementation error | Should not occur, please set up a bug report.
`NULL` | " Directory `name` already exists as a file " | A file is marked up as directory in the archive. | Maybe a corrupted archive.
`NULL` | " File `name` already exists as a directory " | A directoy is marked up as file in the archive. | Maybe a corrupted archive.
`NULL` | " File `name` already exists and is write protected. " | The archive contains a file which already exists in the destination dir and can not be overwritten. | Extract the archive to an empty directory.
`NULL` | " Unable to create path for `name` " | One or more new nested directories could not be created in the destination directory. | Ensure the destination directory and all nested directories have the required rights.
`NULL` | " Unable to create directory `name` " | A directory could not be created in the destination directory. | Ensure the destination directory has the required rights.
`NULL` | " Error while opening `name` in write binary mode " | The file could not be created. | The file is maybe locked.
`NULL` | " Extracted file `filename` does not have the correct file size `filesize` (`size` expected). Archive may be corrupted. " | Read the message. | Read the message.

## Note

This function can not be called statically.

## Example

Example 38-1. Extract compressed archive into a new directory ignoring the old one
    // tarname.tar with files :
    //   dev/data/file.txt
    //   dev/data/log.txt
    //   readme.txt

    $tar_object = new Archive_Tar("tarname.tar");
    $tar_object->extractModify("install", "dev");

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

Example 38-2. Extract compressed archive into a new directory ignoring the old one (especilly for Windows)
    // tarname.tar with files :
    //   dev/data/file.txt
    //   dev/data/log.txt
    //   readme.txt

    $tar_object = new Archive_Tar("tarname.tar");
    $tar_object->extractModify("d:\\install\\temp", "dev");

    // Files will be extracted there :
    //   d:\\install\\temp\\data\\file.txt
    //   d:\\install\\temp\\data\\log.txt

Prev | Home | Next
Archive_Tar::extractList() | Up | Archive_Tar::listContent()