6f56e9679e981590333140fdb0a4cf7add8b0541
[core.git] / inc / main / classes / file_directories / directory / class_FrameworkDirectoryPointer.php
1 <?php
2 // Own namespace
3 namespace CoreFramework\Filesytem\Pointer;
4
5 // Import framework stuff
6 use CoreFramework\Object\BaseFrameworkSystem;
7
8 /**
9  * A class for directory reading and getting its contents, no recursion!
10  *
11  * @author              Roland Haeder <webmaster@shipsimu.org>
12  * @version             0.0.0
13  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2017 Core Developer Team
14  * @license             GNU GPL 3.0 or any newer version
15  * @link                http://www.shipsimu.org
16  *
17  * This program is free software: you can redistribute it and/or modify
18  * it under the terms of the GNU General Public License as published by
19  * the Free Software Foundation, either version 3 of the License, or
20  * (at your option) any later version.
21  *
22  * This program is distributed in the hope that it will be useful,
23  * but WITHOUT ANY WARRANTY; without even the implied warranty of
24  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
25  * GNU General Public License for more details.
26  *
27  * You should have received a copy of the GNU General Public License
28  * along with this program. If not, see <http://www.gnu.org/licenses/>.
29  */
30 class FrameworkDirectoryPointer extends BaseFrameworkSystem implements FrameworkDirectory {
31         /**
32          * The current path we are working in
33          */
34         private $pathName = '';
35
36         /**
37          * The directory iterator instance
38          */
39         private $iteratorInstance = NULL;
40
41         /**
42          * Protected constructor
43          */
44         protected function __construct () {
45                 // Call parent constructor
46                 parent::__construct(__CLASS__);
47         }
48
49         /**
50          * Destructor for cleaning purposes, etc
51          */
52         public function __destruct() {
53                 // Is there a resource pointer? Then we have to close the directory here!
54                 if ($this->getDirectoryIteratorInstance() instanceof DirectoryIterator) {
55                         // Try to close a directory
56                         $this->closeDirectory();
57                 } // END - if
58
59                 // Call the parent destructor
60                 parent::__destruct();
61         }
62
63         /**
64          * Create a directory pointer based on the given path. The path will also
65          * be verified here.
66          *
67          * @param       $pathName               The path name we shall pass to opendir()
68          * @param       $inConstructor  If we are in de/con-structor or from somewhere else
69          * @return      $pointerInstance        A prepared instance of FrameworkDirectoryPointer
70          * @throws      PathIsEmptyException    If the provided path name is empty
71          * @throws      InvalidPathStringException      If the provided path name is not a string
72          * @throws      PathIsNoDirectoryException      If the provided path name is not valid
73          * @throws      PathReadProtectedException      If the provided path name is read-protected
74          * @todo        Get rid of inConstructor, could be old-lost code.
75          */
76         public static final function createFrameworkDirectoryPointer ($pathName, $inConstructor = FALSE) {
77                 // Some pre-sanity checks...
78                 if (is_null($pathName)) {
79                         // No pathname given
80                         if ($inConstructor) {
81                                 return NULL;
82                         } else {
83                                 throw new PathIsEmptyException(NULL, self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
84                         }
85                 } elseif (!is_string($pathName)) {
86                         // Is not a string
87                         if ($inConstructor) {
88                                 return NULL;
89                         } else {
90                                 throw new InvalidPathStringException(NULL, self::EXCEPTION_INVALID_STRING);
91                         }
92                 } elseif (!is_dir($pathName)) {
93                         // Not a directory
94                         if ($inConstructor) {
95                                 return NULL;
96                         } else {
97                                 throw new PathIsNoDirectoryException($pathName, self::EXCEPTION_INVALID_PATH_NAME);
98                         }
99                 } elseif (!is_readable($pathName)) {
100                         // Not readable
101                         if ($inConstructor) {
102                                 return NULL;
103                         } else {
104                                 throw new PathReadProtectedException($pathName, self::EXCEPTION_READ_PROTECED_PATH);
105                         }
106                 }
107
108                 // Create new instance
109                 $pointerInstance = new FrameworkDirectoryPointer();
110
111                 // Get an iterator for the directory
112                 $iteratorInstance = new DirectoryIterator($pathName);
113
114                 // ... and rewind back
115                 $iteratorInstance->rewind();
116
117                 // Set directory pointer and path name
118                 $pointerInstance->setDirectoryIteratorInstance($iteratorInstance);
119                 $pointerInstance->setPathName($pathName);
120
121                 // Return the instance
122                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DIRECTORY[' . __METHOD__ . ':' . __LINE__ . ']: Opened pathName=' . $pathName . ' - EXIT!');
123                 return $pointerInstance;
124         }
125
126         /**
127          * Read raw lines of data from a directory pointer and return the data
128          *
129          * @return      $currentEntry   Current entry from encapsulated iterator
130          */
131         public function readRawDirectory () {
132                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DIRECTORY[' . __METHOD__ . ':' . __LINE__ . '] - CALLED!');
133
134                 // Can the next entry be read?
135                 assert($this->getDirectoryIteratorInstance()->valid());
136
137                 // Read data from the directory pointer and return it
138                 $currentEntry = $this->getDirectoryIteratorInstance()->current();
139
140                 // Return found entry
141                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DIRECTORY[' . __METHOD__ . ':' . __LINE__ . ']: currentEntry[]=' . gettype($currentEntry) . ' - EXIT!');
142                 return $currentEntry;
143         }
144
145         /**
146          * Read lines from the current directory pointer except some parts
147          *
148          * @param       $except         Some parts of a directory we want to ignore. Valid: directory and file names, other values will be silently ignored
149          * @return      string          Directory and/or file names read from the current directory pointer
150          */
151         public function readDirectoryExcept (array $except = array()) {
152                 // No exceptions given?
153                 if (count($except) == 0) {
154                         // No exception given, so read all files and directories, but not recursive
155                         self::createDebugInstance(__CLASS__)->debugOutput('DIRECTORY[' . __METHOD__ . ':' . __LINE__ . ']: No exceptions given, please use readRawDirectory() instead!');
156                         return $this->readRawDirectory();
157                 } elseif (!$this->getDirectoryIteratorInstance()->valid()) {
158                         // No more left to read
159                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DIRECTORY[' . __METHOD__ . ':' . __LINE__ . ']: EOD reached.');
160                         return NULL;
161                 }
162
163                 // Init raw line
164                 $rawLine = NULL;
165
166                 // Read a raw line...
167                 $currentEntry = $this->readRawDirectory();
168                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DIRECTORY[' . __METHOD__ . ':' . __LINE__ . ']: currentEntry[]=' . gettype($currentEntry));
169
170                 // Shall we exclude directories?
171                 if (is_object($currentEntry)) {
172                         // Get file name
173                         $rawLine = $currentEntry->getFilename();
174                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DIRECTORY[' . __METHOD__ . ':' . __LINE__ . ']: rawLine[' . gettype($rawLine) . ']=' . $rawLine . ',isDot=' . intval($this->getDirectoryIteratorInstance()->isDot()));
175
176                         // Is it a dot-directory or excluded?
177                         if (($this->getDirectoryIteratorInstance()->isDot()) || (in_array($rawLine, $except))) {
178                                 // To next entry
179                                 $this->getDirectoryIteratorInstance()->next();
180
181                                 // Exclude this part
182                                 $rawLine = $this->readDirectoryExcept($except);
183                                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DIRECTORY[' . __METHOD__ . ':' . __LINE__ . ']: rawline[' . gettype($rawLine) . ']=' . $rawLine . ' - Recursive call!');
184                         } // END - if
185                 } // END - if
186
187                 // To next entry
188                 $this->getDirectoryIteratorInstance()->next();
189
190                 // Return read line
191                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DIRECTORY[' . __METHOD__ . ':' . __LINE__ . ']: rawLine[' . gettype($rawLine) . ']=' . $rawLine);
192                 return $rawLine;
193         }
194
195         /**
196          * Close a directory source and set it's instance to null and the path name
197          * to empty
198          *
199          * @return      void
200          */
201         public function closeDirectory () {
202                 // Close the directory by unsetting it
203                 $this->unsetDirectoryIteratorInstance();
204                 $this->setPathName('');
205         }
206
207         /**
208          * Setter for the directory pointer
209          *
210          * @param       $iteratorInstance       An instanceof a DirectoryIterator class
211          * @return      void
212          */
213         protected final function setDirectoryIteratorInstance (DirectoryIterator $iteratorInstance) {
214                 // Set instance
215                 $this->iteratorInstance = $iteratorInstance;
216         }
217
218         /**
219          * Getter for the directory pointer
220          *
221          * @return      $iteratorInstance       The directory pointer which shall be a valid directory resource
222          */
223         public final function getDirectoryIteratorInstance () {
224                 return $this->iteratorInstance;
225         }
226
227         /**
228          * Remove directory iterator instance (effectively closing it) by setting
229          * it to NULL. This will trigger a call on the destructor which will then
230          * "close" the iterator.
231          *
232          * @param       $iteratorInstance       An instanceof a DirectoryIterator class
233          * @return      void
234          */
235         protected final function unsetDirectoryIteratorInstance () {
236                 // "Unset" the instance
237                 $this->iteratorInstance = NULL;
238         }
239
240         /**
241          * Setter for path name
242          *
243          * @param       $pathName       The new path name
244          * @return      void
245          */
246         protected final function setPathName ($pathName) {
247                 $pathName = (string) $pathName;
248                 $this->pathName = $pathName;
249         }
250
251         /**
252          * Getter for path name
253          *
254          * @return      $pathName       The current path name
255          */
256         public final function getPathName () {
257                 return $this->pathName;
258         }
259
260 }