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