1*ab8e5256SAndreas Gohr<?php 2*ab8e5256SAndreas Gohr 3*ab8e5256SAndreas Gohrnamespace splitbrain\PHPArchive; 4*ab8e5256SAndreas Gohr 5*ab8e5256SAndreas Gohrabstract class Archive 6*ab8e5256SAndreas Gohr{ 7*ab8e5256SAndreas Gohr 8*ab8e5256SAndreas Gohr const COMPRESS_AUTO = -1; 9*ab8e5256SAndreas Gohr const COMPRESS_NONE = 0; 10*ab8e5256SAndreas Gohr const COMPRESS_GZIP = 1; 11*ab8e5256SAndreas Gohr const COMPRESS_BZIP = 2; 12*ab8e5256SAndreas Gohr 13*ab8e5256SAndreas Gohr /** @var callable */ 14*ab8e5256SAndreas Gohr protected $callback; 15*ab8e5256SAndreas Gohr 16*ab8e5256SAndreas Gohr /** 17*ab8e5256SAndreas Gohr * Set the compression level and type 18*ab8e5256SAndreas Gohr * 19*ab8e5256SAndreas Gohr * @param int $level Compression level (0 to 9) 20*ab8e5256SAndreas Gohr * @param int $type Type of compression to use (use COMPRESS_* constants) 21*ab8e5256SAndreas Gohr * @throws ArchiveIllegalCompressionException 22*ab8e5256SAndreas Gohr */ 23*ab8e5256SAndreas Gohr abstract public function setCompression($level = 9, $type = Archive::COMPRESS_AUTO); 24*ab8e5256SAndreas Gohr 25*ab8e5256SAndreas Gohr /** 26*ab8e5256SAndreas Gohr * Open an existing archive file for reading 27*ab8e5256SAndreas Gohr * 28*ab8e5256SAndreas Gohr * @param string $file 29*ab8e5256SAndreas Gohr * @throws ArchiveIOException 30*ab8e5256SAndreas Gohr */ 31*ab8e5256SAndreas Gohr abstract public function open($file); 32*ab8e5256SAndreas Gohr 33*ab8e5256SAndreas Gohr /** 34*ab8e5256SAndreas Gohr * Read the contents of an archive 35*ab8e5256SAndreas Gohr * 36*ab8e5256SAndreas Gohr * This function lists the files stored in the archive, and returns an indexed array of FileInfo objects 37*ab8e5256SAndreas Gohr * 38*ab8e5256SAndreas Gohr * The archive is closed afer reading the contents, because rewinding is not possible in bzip2 streams. 39*ab8e5256SAndreas Gohr * Reopen the file with open() again if you want to do additional operations 40*ab8e5256SAndreas Gohr * 41*ab8e5256SAndreas Gohr * @return FileInfo[] 42*ab8e5256SAndreas Gohr */ 43*ab8e5256SAndreas Gohr abstract public function contents(); 44*ab8e5256SAndreas Gohr 45*ab8e5256SAndreas Gohr /** 46*ab8e5256SAndreas Gohr * Extract an existing archive 47*ab8e5256SAndreas Gohr * 48*ab8e5256SAndreas Gohr * The $strip parameter allows you to strip a certain number of path components from the filenames 49*ab8e5256SAndreas Gohr * found in the archive file, similar to the --strip-components feature of GNU tar. This is triggered when 50*ab8e5256SAndreas Gohr * an integer is passed as $strip. 51*ab8e5256SAndreas Gohr * Alternatively a fixed string prefix may be passed in $strip. If the filename matches this prefix, 52*ab8e5256SAndreas Gohr * the prefix will be stripped. It is recommended to give prefixes with a trailing slash. 53*ab8e5256SAndreas Gohr * 54*ab8e5256SAndreas Gohr * By default this will extract all files found in the archive. You can restrict the output using the $include 55*ab8e5256SAndreas Gohr * and $exclude parameter. Both expect a full regular expression (including delimiters and modifiers). If 56*ab8e5256SAndreas Gohr * $include is set, only files that match this expression will be extracted. Files that match the $exclude 57*ab8e5256SAndreas Gohr * expression will never be extracted. Both parameters can be used in combination. Expressions are matched against 58*ab8e5256SAndreas Gohr * stripped filenames as described above. 59*ab8e5256SAndreas Gohr * 60*ab8e5256SAndreas Gohr * The archive is closed afterwards. Reopen the file with open() again if you want to do additional operations 61*ab8e5256SAndreas Gohr * 62*ab8e5256SAndreas Gohr * @param string $outdir the target directory for extracting 63*ab8e5256SAndreas Gohr * @param int|string $strip either the number of path components or a fixed prefix to strip 64*ab8e5256SAndreas Gohr * @param string $exclude a regular expression of files to exclude 65*ab8e5256SAndreas Gohr * @param string $include a regular expression of files to include 66*ab8e5256SAndreas Gohr * @throws ArchiveIOException 67*ab8e5256SAndreas Gohr * @return array 68*ab8e5256SAndreas Gohr */ 69*ab8e5256SAndreas Gohr abstract public function extract($outdir, $strip = '', $exclude = '', $include = ''); 70*ab8e5256SAndreas Gohr 71*ab8e5256SAndreas Gohr /** 72*ab8e5256SAndreas Gohr * Create a new archive file 73*ab8e5256SAndreas Gohr * 74*ab8e5256SAndreas Gohr * If $file is empty, the archive file will be created in memory 75*ab8e5256SAndreas Gohr * 76*ab8e5256SAndreas Gohr * @param string $file 77*ab8e5256SAndreas Gohr */ 78*ab8e5256SAndreas Gohr abstract public function create($file = ''); 79*ab8e5256SAndreas Gohr 80*ab8e5256SAndreas Gohr /** 81*ab8e5256SAndreas Gohr * Add a file to the current archive using an existing file in the filesystem 82*ab8e5256SAndreas Gohr * 83*ab8e5256SAndreas Gohr * @param string $file path to the original file 84*ab8e5256SAndreas 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 85*ab8e5256SAndreas Gohr * @throws ArchiveIOException 86*ab8e5256SAndreas Gohr */ 87*ab8e5256SAndreas Gohr abstract public function addFile($file, $fileinfo = ''); 88*ab8e5256SAndreas Gohr 89*ab8e5256SAndreas Gohr /** 90*ab8e5256SAndreas Gohr * Add a file to the current archive using the given $data as content 91*ab8e5256SAndreas Gohr * 92*ab8e5256SAndreas Gohr * @param string|FileInfo $fileinfo either the name to us in archive (string) or a FileInfo oject with all meta data 93*ab8e5256SAndreas Gohr * @param string $data binary content of the file to add 94*ab8e5256SAndreas Gohr * @throws ArchiveIOException 95*ab8e5256SAndreas Gohr */ 96*ab8e5256SAndreas Gohr abstract public function addData($fileinfo, $data); 97*ab8e5256SAndreas Gohr 98*ab8e5256SAndreas Gohr /** 99*ab8e5256SAndreas Gohr * Close the archive, close all file handles 100*ab8e5256SAndreas Gohr * 101*ab8e5256SAndreas Gohr * After a call to this function no more data can be added to the archive, for 102*ab8e5256SAndreas Gohr * read access no reading is allowed anymore 103*ab8e5256SAndreas Gohr */ 104*ab8e5256SAndreas Gohr abstract public function close(); 105*ab8e5256SAndreas Gohr 106*ab8e5256SAndreas Gohr /** 107*ab8e5256SAndreas Gohr * Returns the created in-memory archive data 108*ab8e5256SAndreas Gohr * 109*ab8e5256SAndreas Gohr * This implicitly calls close() on the Archive 110*ab8e5256SAndreas Gohr */ 111*ab8e5256SAndreas Gohr abstract public function getArchive(); 112*ab8e5256SAndreas Gohr 113*ab8e5256SAndreas Gohr /** 114*ab8e5256SAndreas Gohr * Save the created in-memory archive data 115*ab8e5256SAndreas Gohr * 116*ab8e5256SAndreas Gohr * Note: It is more memory effective to specify the filename in the create() function and 117*ab8e5256SAndreas Gohr * let the library work on the new file directly. 118*ab8e5256SAndreas Gohr * 119*ab8e5256SAndreas Gohr * @param string $file 120*ab8e5256SAndreas Gohr */ 121*ab8e5256SAndreas Gohr abstract public function save($file); 122*ab8e5256SAndreas Gohr 123*ab8e5256SAndreas Gohr /** 124*ab8e5256SAndreas Gohr * Set a callback function to be called whenever a file is added or extracted. 125*ab8e5256SAndreas Gohr * 126*ab8e5256SAndreas Gohr * The callback is called with a FileInfo object as parameter. You can use this to show progress 127*ab8e5256SAndreas Gohr * info during an operation. 128*ab8e5256SAndreas Gohr * 129*ab8e5256SAndreas Gohr * @param callable $callback 130*ab8e5256SAndreas Gohr */ 131*ab8e5256SAndreas Gohr public function setCallback($callback) 132*ab8e5256SAndreas Gohr { 133*ab8e5256SAndreas Gohr $this->callback = $callback; 134*ab8e5256SAndreas Gohr } 135*ab8e5256SAndreas Gohr} 136