c0728738a1fe947518681855f8fe05e02e6768d8
[core.git] / inc / classes / main / io / class_FrameworkDirectoryPointer.php
1 <?php
2 /**
3  * A class for directory reading and getting its contents
4  *
5  * @author              Roland Haeder <webmaster@ship-simu.org>
6  * @version             0.0.0
7  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2011 Core Developer Team
8  * @license             GNU GPL 3.0 or any newer version
9  * @link                http://www.ship-simu.org
10  *
11  * This program is free software: you can redistribute it and/or modify
12  * it under the terms of the GNU General Public License as published by
13  * the Free Software Foundation, either version 3 of the License, or
14  * (at your option) any later version.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License
22  * along with this program. If not, see <http://www.gnu.org/licenses/>.
23  */
24 class FrameworkDirectoryPointer extends BaseFrameworkSystem {
25         /**
26          * The current path we are working in
27          */
28         private $pathName = '';
29
30         /**
31          * The directory pointer
32          */
33         private $dirPointer = NULL;
34
35         /**
36          * Protected constructor
37          */
38         protected function __construct () {
39                 // Call parent constructor
40                 parent::__construct(__CLASS__);
41         }
42
43         /**
44          * Destructor for cleaning purposes, etc
45          */
46         public function __destruct() {
47                 // Is there a resource pointer? Then we have to close the directory here!
48                 if (is_resource($this->getPointer())) {
49                         // Try to close a directory
50                         $this->closeDirectory();
51                 }
52
53                 // Call the parent destructor
54                 parent::__destruct();
55         }
56
57         /**
58          * Create a directory pointer based on the given path. The path will also
59          * be verified here.
60          *
61          * @param       $pathName               The path name we shall pass to opendir()
62          * @param       $inConstructor  If we are in de/con-structor or from somewhere
63          *                                                      else
64          * @return      $pointerInstance        A prepared instance of
65          *                                                              FrameworkDirectoryPointer
66          * @throws      PathIsEmptyException    If the provided path name
67          *                                                                      is empty
68          * @throws      InvalidPathStringException      If the provided path name is
69          *                                                                              not a string
70          * @throws      PathIsNoDirectoryException      If the provided path name is
71          *                                                                              not valid
72          * @throws      PathReadProtectedException      If the provided path name is
73          *                                                                              read-protected
74          * @throws      DirPointerNotOpened                     If opendir() returns not a
75          *                                                                              directory resource
76          */
77         public static final function createFrameworkDirectoryPointer ($pathName, $inConstructor = false) {
78                 // Some pre-sanity checks...
79                 if (is_null($pathName)) {
80                         // No pathname given
81                         if ($inConstructor) {
82                                 return null;
83                         } else {
84                                 throw new PathIsEmptyException(null, self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
85                         }
86                 } elseif (!is_string($pathName)) {
87                         // Is not a string
88                         if ($inConstructor) {
89                                 return null;
90                         } else {
91                                 throw new InvalidPathStringException(null, self::EXCEPTION_INVALID_STRING);
92                         }
93                 } elseif (!is_dir($pathName)) {
94                         // Not a directory
95                         if ($inConstructor) {
96                                 return null;
97                         } else {
98                                 throw new PathIsNoDirectoryException($pathName, self::EXCEPTION_INVALID_PATH_NAME);
99                         }
100                 } elseif (!is_readable($pathName)) {
101                         // Not readable
102                         if ($inConstructor) {
103                                 return null;
104                         } else {
105                                 throw new PathReadProtectedException($pathName, self::EXCEPTION_READ_PROTECED_PATH);
106                         }
107                 }
108
109                 // Try to open a handler
110                 $dirPointer = @opendir($pathName);
111                 if (!is_resource($dirPointer)) {
112                         // Something bad happend
113                         if ($inConstructor) {
114                                 return null;
115                         } else {
116                                 throw new DirPointerNotOpenedException($pathName, self::EXCEPTION_DIR_POINTER_INVALID);
117                         }
118                 }
119
120                 // Create new instance
121                 $pointerInstance = new FrameworkDirectoryPointer();
122
123                 // Set directory pointer and path name
124                 $pointerInstance->setPointer($dirPointer);
125                 $pointerInstance->setPathName($pathName);
126
127                 // Return the instance
128                 return $pointerInstance;
129         }
130
131         /**
132          * Read raw lines of data from a directory pointer and return the data
133          *
134          * @return      string  Directory and/or file names read from the current
135          *                                      directory pointer
136          */
137         public function readRawDirectory () {
138                 // Read data from the directory pointer and return it
139                 return readdir($this->getPointer());
140         }
141
142         /**
143          * Read lines from the current directory pointer except some parts
144          *
145          * @param               $except Some parts of a directory we want to ignore.
146          *                                      Valid: dirs
147          *                                      Other values will be silently ignored
148          * @return      string  Directory and/or file names read from the current
149          *                                      directory pointer
150          */
151         public function readDirectoryExcept ($except = '') {
152                 if ((empty($except)) || (!is_array($except)) || (count($except) == 0)) {
153                         // No exception given, so read all data
154                         return $this->readRawDirectory();
155                 }
156
157                 // Read a raw line...
158                 $rawLine = $this->readRawDirectory();
159
160                 // Shall we exclude directories?
161                 if ((!is_null($rawLine)) && ($rawLine !== false) && (in_array($rawLine, $except))) {
162                         // Exclude this part
163                         return $this->readDirectoryExcept($except);
164                 } elseif ((!is_null($rawLine)) && ($rawLine !== false)) {
165                         // Return read data
166                         return $rawLine;
167                 }
168
169                 // End pointer reached
170                 return null;
171         }
172
173         /**
174          * Close a directory source and set it's instance to null and the path name
175          * to empty
176          *
177          * @return      void
178          */
179         public function closeDirectory () {
180                 // Close the directory pointer and reset the instance variable
181                 @closedir($this->getPointer());
182                 $this->setPointer(null);
183                 $this->setPathName('');
184         }
185
186         /**
187          * Setter for the directory pointer
188          *
189          * @param               $dirPointer     The directory resource
190          * @return      void
191          */
192         public final function setPointer ($dirPointer) {
193                 // Sanity-check if pointer is a valid directory resource
194                 if (is_resource($dirPointer) || is_null($dirPointer)) {
195                         // Is a valid resource
196                         $this->dirPointer = $dirPointer;
197                 } else {
198                         // Throw exception
199                         throw new InvalidResourceException($this, self::EXCEPTION_INVALID_RESOURCE);
200                 }
201         }
202
203         /**
204          * Getter for the directory pointer
205          *
206          * @return      $dirPointer     The directory pointer which shall be a valid
207          *                                              directory resource
208          */
209         public final function getPointer () {
210                 return $this->dirPointer;
211         }
212
213         /**
214          * Setter for path name
215          *
216          * @param               $pathName               The new path name
217          * @return      void
218          */
219         public final function setPathName ($pathName) {
220                 $pathName = (string) $pathName;
221                 $this->pathName = $pathName;
222         }
223
224         /**
225          * Getter for path name
226          *
227          * @return      $pathName               The current path name
228          */
229         public final function getPathName () {
230                 return $this->pathName;
231         }
232 }
233
234 // [EOF]
235 ?>