1605f8e8dSAndreas Gohr<?php 2605f8e8dSAndreas Gohr 3605f8e8dSAndreas Gohrnamespace splitbrain\PHPArchive; 4605f8e8dSAndreas Gohr 5605f8e8dSAndreas Gohrabstract class Archive 6605f8e8dSAndreas Gohr{ 7605f8e8dSAndreas Gohr 8605f8e8dSAndreas Gohr const COMPRESS_AUTO = -1; 9605f8e8dSAndreas Gohr const COMPRESS_NONE = 0; 10605f8e8dSAndreas Gohr const COMPRESS_GZIP = 1; 11605f8e8dSAndreas Gohr const COMPRESS_BZIP = 2; 12605f8e8dSAndreas Gohr 13*e43cd7e1SAndreas Gohr /** @var callable */ 14*e43cd7e1SAndreas Gohr protected $callback; 15*e43cd7e1SAndreas Gohr 16605f8e8dSAndreas Gohr /** 17605f8e8dSAndreas Gohr * Set the compression level and type 18605f8e8dSAndreas Gohr * 19605f8e8dSAndreas Gohr * @param int $level Compression level (0 to 9) 20605f8e8dSAndreas Gohr * @param int $type Type of compression to use (use COMPRESS_* constants) 21*e43cd7e1SAndreas Gohr * @throws ArchiveIllegalCompressionException 22605f8e8dSAndreas Gohr */ 23605f8e8dSAndreas Gohr abstract public function setCompression($level = 9, $type = Archive::COMPRESS_AUTO); 24605f8e8dSAndreas Gohr 25605f8e8dSAndreas Gohr /** 26605f8e8dSAndreas Gohr * Open an existing archive file for reading 27605f8e8dSAndreas Gohr * 28605f8e8dSAndreas Gohr * @param string $file 29605f8e8dSAndreas Gohr * @throws ArchiveIOException 30605f8e8dSAndreas Gohr */ 31605f8e8dSAndreas Gohr abstract public function open($file); 32605f8e8dSAndreas Gohr 33605f8e8dSAndreas Gohr /** 34605f8e8dSAndreas Gohr * Read the contents of an archive 35605f8e8dSAndreas Gohr * 36605f8e8dSAndreas Gohr * This function lists the files stored in the archive, and returns an indexed array of FileInfo objects 37605f8e8dSAndreas Gohr * 38605f8e8dSAndreas Gohr * The archive is closed afer reading the contents, because rewinding is not possible in bzip2 streams. 39605f8e8dSAndreas Gohr * Reopen the file with open() again if you want to do additional operations 40605f8e8dSAndreas Gohr * 41605f8e8dSAndreas Gohr * @return FileInfo[] 42605f8e8dSAndreas Gohr */ 43605f8e8dSAndreas Gohr abstract public function contents(); 44605f8e8dSAndreas Gohr 45605f8e8dSAndreas Gohr /** 46605f8e8dSAndreas Gohr * Extract an existing archive 47605f8e8dSAndreas Gohr * 48605f8e8dSAndreas Gohr * The $strip parameter allows you to strip a certain number of path components from the filenames 49605f8e8dSAndreas Gohr * found in the archive file, similar to the --strip-components feature of GNU tar. This is triggered when 50605f8e8dSAndreas Gohr * an integer is passed as $strip. 51605f8e8dSAndreas Gohr * Alternatively a fixed string prefix may be passed in $strip. If the filename matches this prefix, 52605f8e8dSAndreas Gohr * the prefix will be stripped. It is recommended to give prefixes with a trailing slash. 53605f8e8dSAndreas Gohr * 54605f8e8dSAndreas Gohr * By default this will extract all files found in the archive. You can restrict the output using the $include 55605f8e8dSAndreas Gohr * and $exclude parameter. Both expect a full regular expression (including delimiters and modifiers). If 56605f8e8dSAndreas Gohr * $include is set, only files that match this expression will be extracted. Files that match the $exclude 57605f8e8dSAndreas Gohr * expression will never be extracted. Both parameters can be used in combination. Expressions are matched against 58605f8e8dSAndreas Gohr * stripped filenames as described above. 59605f8e8dSAndreas Gohr * 60605f8e8dSAndreas Gohr * The archive is closed afterwards. Reopen the file with open() again if you want to do additional operations 61605f8e8dSAndreas Gohr * 62605f8e8dSAndreas Gohr * @param string $outdir the target directory for extracting 63605f8e8dSAndreas Gohr * @param int|string $strip either the number of path components or a fixed prefix to strip 64605f8e8dSAndreas Gohr * @param string $exclude a regular expression of files to exclude 65605f8e8dSAndreas Gohr * @param string $include a regular expression of files to include 66605f8e8dSAndreas Gohr * @throws ArchiveIOException 67605f8e8dSAndreas Gohr * @return array 68605f8e8dSAndreas Gohr */ 69605f8e8dSAndreas Gohr abstract public function extract($outdir, $strip = '', $exclude = '', $include = ''); 70605f8e8dSAndreas Gohr 71605f8e8dSAndreas Gohr /** 72605f8e8dSAndreas Gohr * Create a new archive file 73605f8e8dSAndreas Gohr * 74605f8e8dSAndreas Gohr * If $file is empty, the archive file will be created in memory 75605f8e8dSAndreas Gohr * 76605f8e8dSAndreas Gohr * @param string $file 77605f8e8dSAndreas Gohr */ 78605f8e8dSAndreas Gohr abstract public function create($file = ''); 79605f8e8dSAndreas Gohr 80605f8e8dSAndreas Gohr /** 81605f8e8dSAndreas Gohr * Add a file to the current archive using an existing file in the filesystem 82605f8e8dSAndreas Gohr * 83605f8e8dSAndreas Gohr * @param string $file path to the original file 84605f8e8dSAndreas Gohr * @param string|FileInfo $fileinfo either the name to us in archive (string) or a FileInfo oject with all meta data, empty to take from original 85605f8e8dSAndreas Gohr * @throws ArchiveIOException 86605f8e8dSAndreas Gohr */ 87605f8e8dSAndreas Gohr abstract public function addFile($file, $fileinfo = ''); 88605f8e8dSAndreas Gohr 89605f8e8dSAndreas Gohr /** 90605f8e8dSAndreas Gohr * Add a file to the current archive using the given $data as content 91605f8e8dSAndreas Gohr * 92605f8e8dSAndreas Gohr * @param string|FileInfo $fileinfo either the name to us in archive (string) or a FileInfo oject with all meta data 93605f8e8dSAndreas Gohr * @param string $data binary content of the file to add 94605f8e8dSAndreas Gohr * @throws ArchiveIOException 95605f8e8dSAndreas Gohr */ 96605f8e8dSAndreas Gohr abstract public function addData($fileinfo, $data); 97605f8e8dSAndreas Gohr 98605f8e8dSAndreas Gohr /** 99605f8e8dSAndreas Gohr * Close the archive, close all file handles 100605f8e8dSAndreas Gohr * 101605f8e8dSAndreas Gohr * After a call to this function no more data can be added to the archive, for 102605f8e8dSAndreas Gohr * read access no reading is allowed anymore 103605f8e8dSAndreas Gohr */ 104605f8e8dSAndreas Gohr abstract public function close(); 105605f8e8dSAndreas Gohr 106605f8e8dSAndreas Gohr /** 107605f8e8dSAndreas Gohr * Returns the created in-memory archive data 108605f8e8dSAndreas Gohr * 109605f8e8dSAndreas Gohr * This implicitly calls close() on the Archive 110605f8e8dSAndreas Gohr */ 111605f8e8dSAndreas Gohr abstract public function getArchive(); 112605f8e8dSAndreas Gohr 113605f8e8dSAndreas Gohr /** 114605f8e8dSAndreas Gohr * Save the created in-memory archive data 115605f8e8dSAndreas Gohr * 116605f8e8dSAndreas Gohr * Note: It is more memory effective to specify the filename in the create() function and 117605f8e8dSAndreas Gohr * let the library work on the new file directly. 118605f8e8dSAndreas Gohr * 119605f8e8dSAndreas Gohr * @param string $file 120605f8e8dSAndreas Gohr */ 121605f8e8dSAndreas Gohr abstract public function save($file); 122605f8e8dSAndreas Gohr 123*e43cd7e1SAndreas Gohr /** 124*e43cd7e1SAndreas Gohr * Set a callback function to be called whenever a file is added or extracted. 125*e43cd7e1SAndreas Gohr * 126*e43cd7e1SAndreas Gohr * The callback is called with a FileInfo object as parameter. You can use this to show progress 127*e43cd7e1SAndreas Gohr * info during an operation. 128*e43cd7e1SAndreas Gohr * 129*e43cd7e1SAndreas Gohr * @param callable $callback 130*e43cd7e1SAndreas Gohr */ 131*e43cd7e1SAndreas Gohr public function setCallback($callback) 132605f8e8dSAndreas Gohr { 133*e43cd7e1SAndreas Gohr $this->callback = $callback; 134605f8e8dSAndreas Gohr } 135530d6729SAndreas Gohr} 136