inc/classes/main/io/class_FrameworkDirectoryPointer.php

   1 <?php
   2 /**
   3  * A class for directory reading and getting its contents
   4  */
   5 class FrameworkDirectoryPointer extends BaseFrameworkSystem {
   6         /**
   7          * The current path we are working in
   8          */
   9         private $pathName = "";
  10
  11         /**
  12          * The directory pointer
  13          */
  14         private $dirPointer = null;
  15
  16         /**
  17          * Private constructor
  18          */
  19         private function __construct () {
  20                 // Call parent constructor
  21                 parent::constructor(__CLASS__);
  22
  23                 // Set part description
  24                 $this->setPartDescr("Verzeichnis-Handler");
  25
  26                 // Create unique ID
  27                 $this->createUniqueID();
  28
  29                 // Clean-up a little
  30                 $this->removeNumberFormaters();
  31         }
  32
  33         /**
  34          * Destructor for cleaning purposes, etc
  35          */
  36         public function __destruct() {
  37                 // Is there a resource pointer? Then we have to close the directory here!
  38                 if (is_resource($this->getPointer())) {
  39                         // Try to close a directory
  40                         $this->closeDirectory();
  41                 }
  42
  43                 // Call the parent destructor
  44                 parent::__destruct();
  45         }
  46
  47         /**
  48          * Create a directory pointer based on the given path. The path will also
  49          * be verified here.
  50          *
  51          * @param               $pathName                                       The path name we shall pass
  52          *                                                                      to opendir()
  53          * @param               $inConstructor                          If we are in de/con-structor
  54          *                                                                      or from somewhere else
  55          * @throws      PathIsEmptyException            If the provided path name
  56          *                                                                      is empty
  57          * @throws      InvalidPathStringException      If the provided path name is
  58          *                                                                      not a string
  59          * @throws      PathIsNoDirectoryException      If the provided path name is
  60          *                                                                      not valid
  61          * @throws      PathReadProtectedException      If the provided path name is
  62          *                                                                      read-protected
  63          * @throws      DirPointerNotOpened                     If opendir() returns not a
  64          *                                                                      directory resource
  65          * @return      $pointerInstance                        A prepared instance of
  66          *                                                                      FrameworkDirectoryPointer
  67          */
  68         public final static function createFrameworkDirectoryPointer ($pathName, $inConstructor = false) {
  69                 // Some pre-sanity checks...
  70                 if (is_null($pathName)) {
  71                         // No pathname given
  72                         if ($inConstructor) {
  73                                 return null;
  74                         } else {
  75                                 throw new PathIsEmptyException(null, self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
  76                         }
  77                 } elseif (!is_string($pathName)) {
  78                         // Is not a string
  79                         if ($inConstructor) {
  80                                 return null;
  81                         } else {
  82                                 throw new InvalidPathStringException(null, self::EXCEPTION_INVALID_STRING);
  83                         }
  84                 } elseif (!is_dir($pathName)) {
  85                         // Not a directory
  86                         if ($inConstructor) {
  87                                 return null;
  88                         } else {
  89                                 throw new PathIsNoDirectoryException($pathName, self::EXCEPTION_INVALID_PATH_NAME);
  90                         }
  91                 } elseif (!is_readable($pathName)) {
  92                         // Not readable
  93                         if ($inConstructor) {
  94                                 return null;
  95                         } else {
  96                                 throw new PathReadProtectedException($pathName, self::EXCEPTION_READ_PROTECED_PATH);
  97                         }
  98                 }
  99
 100                 // Try to open a handler
 101                 $dirPointer = @opendir($pathName);
 102                 if (!is_resource($dirPointer)) {
 103                         // Something bad happend
 104                         if ($inConstructor) {
 105                                 return null;
 106                         } else {
 107                                 throw new DirPointerNotOpenedException($pathName, self::EXCEPTION_DIR_POINTER_INVALID);
 108                         }
 109                 }
 110
 111                 // Create new instance
 112                 $pointerInstance = new FrameworkDirectoryPointer();
 113
 114                 // Set directory pointer and path name
 115                 $pointerInstance->setPointer($dirPointer);
 116                 $pointerInstance->setPathName($pathName);
 117
 118                 // Return the instance
 119                 return $pointerInstance;
 120         }
 121
 122         /**
 123          * Read raw lines of data from a directory pointer and return the data
 124          *
 125          * @return      string  Directory and/or file names read from the current
 126          *                                      directory pointer
 127          * @throws      NullPointerException    If the directory pointer instance
 128          *                                                              is not set by setPointer()
 129          * @throws      InvalidDirectoryResourceException       If there is being set
 130          *                                                                              an invalid directory resource
 131          */
 132         public function readRawDirectory () {
 133                 if (is_null($this->getPointer())) {
 134                         // Pointer not initialized
 135                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
 136                 } elseif (!is_resource($this->getPointer())) {
 137                         // Pointer is not a valid resource!
 138                         throw new InvalidDirectoryResourceException($this, self::EXCEPTION_INVALID_DIRECTORY_POINTER);
 139                 }
 140
 141                 // Read data from the directory pointer and return it
 142                 return readdir($this->getPointer());
 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.
 149          *                                      Valid: dirs
 150          *                                      Other values will be silently ignored
 151          * @return      string  Directory and/or file names read from the current
 152          *                                      directory pointer
 153          */
 154         public function readDirectoryExcept ($except = "") {
 155                 if ((empty($except)) || (!is_array($except)) || (count($except) == 0)) {
 156                         // No exception given, so read all data
 157                         return $this->readRawDirectory();
 158                 }
 159
 160                 // Read a raw line...
 161                 $rawLine = $this->readRawDirectory();
 162
 163                 // Shall we exclude directories?
 164                 if ((!is_null($rawLine)) && ($rawLine !== false) && (in_array($rawLine, $except))) {
 165                         // Exclude this part
 166                         return $this->readDirectoryExcept($except);
 167                 } elseif ((!is_null($rawLine)) && ($rawLine !== false)) {
 168                         // Return read data
 169                         return $rawLine;
 170                 }
 171
 172                 // End pointer reached
 173                 return null;
 174         }
 175
 176         /**
 177          * Close a directory source and set it's instance to null and the path name
 178          * to empty
 179          *
 180          * @return      void
 181          * @throws      NullPointerException    If the directory pointer instance
 182          *                                                              is not set by setPointer()
 183          * @throws      InvalidDirectoryResourceException       If there is being set
 184          */
 185         public function closeDirectory () {
 186                 if (is_null($this->getPointer())) {
 187                         // Pointer not initialized
 188                         return;
 189                 } elseif (!is_resource($this->getPointer())) {
 190                         // Pointer is not a valid resource!
 191                         throw new InvalidDirectoryResourceException($this, self::EXCEPTION_INVALID_DIRECTORY_POINTER);
 192                 }
 193
 194                 // Close the directory pointer and reset the instance variable
 195                 @closedir($this->getPointer());
 196                 $this->setPointer(null);
 197                 $this->setPathName("");
 198         }
 199
 200         /**
 201          * Setter for the directory pointer
 202          *
 203          * @param               $dirPointer     The directory resource
 204          * @return      void
 205          */
 206         public final function setPointer ($dirPointer) {
 207                 // Sanity-check if the pointer is a valid directory resource
 208                 if (is_resource($dirPointer) || is_null($dirPointer)) {
 209                         // Is a valid resource
 210                         $this->dirPointer = $dirPointer;
 211                 } else {
 212                         // Throw exception
 213                         throw new InvalidDirectoryResourceException($this, self::EXCEPTION_INVALID_DIRECTORY_POINTER);
 214                 }
 215         }
 216
 217         /**
 218          * Getter for the directory pointer
 219          *
 220          * @return      $dirPointer     The directory pointer which shall be a valid
 221          *                                              directory resource
 222          */
 223         public final function getPointer () {
 224                 return $this->dirPointer;
 225         }
 226
 227         /**
 228          * Setter for path name
 229          *
 230          * @param               $pathName               The new path name
 231          * @return      void
 232          */
 233         public final function setPathName ($pathName) {
 234                 $pathName = (string) $pathName;
 235                 $this->pathName = $pathName;
 236         }
 237
 238         /**
 239          * Getter for path name
 240          *
 241          * @return      $pathName               The current path name
 242          */
 243         public final function getPathName () {
 244                 return $this->pathName;
 245         }
 246 }
 247
 248 // [EOF]
 249 ?>