<?php
/**
- * A class for directory reading and getting its contents
+ * A class for directory reading and getting its contents, no recursion!
*
- * @author Roland Haeder <webmaster@ship-simu.org>
+ * @author Roland Haeder <webmaster@shipsimu.org>
* @version 0.0.0
- * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2011 Core Developer Team
+ * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2013 Core Developer Team
* @license GNU GPL 3.0 or any newer version
- * @link http://www.ship-simu.org
+ * @link http://www.shipsimu.org
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
private $pathName = '';
/**
- * The directory pointer
+ * The directory iterator instance
*/
- private $dirPointer = NULL;
+ private $directoryInstance = NULL;
/**
* Protected constructor
*/
public function __destruct() {
// Is there a resource pointer? Then we have to close the directory here!
- if (is_resource($this->getPointer())) {
+ if ($this->getDirectoryInstance() instanceof DirectoryIterator) {
// Try to close a directory
$this->closeDirectory();
- }
+ } // END - if
// Call the parent destructor
parent::__destruct();
* be verified here.
*
* @param $pathName The path name we shall pass to opendir()
- * @param $inConstructor If we are in de/con-structor or from somewhere
- * else
- * @return $pointerInstance A prepared instance of
- * FrameworkDirectoryPointer
- * @throws PathIsEmptyException If the provided path name
- * is empty
- * @throws InvalidPathStringException If the provided path name is
- * not a string
- * @throws PathIsNoDirectoryException If the provided path name is
- * not valid
- * @throws PathReadProtectedException If the provided path name is
- * read-protected
- * @throws DirPointerNotOpened If opendir() returns not a
- * directory resource
+ * @param $inConstructor If we are in de/con-structor or from somewhere else
+ * @return $pointerInstance A prepared instance of FrameworkDirectoryPointer
+ * @throws PathIsEmptyException If the provided path name is empty
+ * @throws InvalidPathStringException If the provided path name is not a string
+ * @throws PathIsNoDirectoryException If the provided path name is not valid
+ * @throws PathReadProtectedException If the provided path name is read-protected
+ * @todo Get rid of inConstructor, could be old-lost code.
*/
- public static final function createFrameworkDirectoryPointer ($pathName, $inConstructor = false) {
+ public static final function createFrameworkDirectoryPointer ($pathName, $inConstructor = FALSE) {
// Some pre-sanity checks...
if (is_null($pathName)) {
// No pathname given
if ($inConstructor) {
- return null;
+ return NULL;
} else {
- throw new PathIsEmptyException(null, self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
+ throw new PathIsEmptyException(NULL, self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
}
} elseif (!is_string($pathName)) {
// Is not a string
if ($inConstructor) {
- return null;
+ return NULL;
} else {
- throw new InvalidPathStringException(null, self::EXCEPTION_INVALID_STRING);
+ throw new InvalidPathStringException(NULL, self::EXCEPTION_INVALID_STRING);
}
} elseif (!is_dir($pathName)) {
// Not a directory
if ($inConstructor) {
- return null;
+ return NULL;
} else {
throw new PathIsNoDirectoryException($pathName, self::EXCEPTION_INVALID_PATH_NAME);
}
} elseif (!is_readable($pathName)) {
// Not readable
if ($inConstructor) {
- return null;
+ return NULL;
} else {
throw new PathReadProtectedException($pathName, self::EXCEPTION_READ_PROTECED_PATH);
}
}
- // Try to open a handler
- $dirPointer = @opendir($pathName);
- if (!is_resource($dirPointer)) {
- // Something bad happend
- if ($inConstructor) {
- return null;
- } else {
- throw new DirPointerNotOpenedException($pathName, self::EXCEPTION_DIR_POINTER_INVALID);
- }
- }
+ // Get an iterator for the directory
+ $directoryInstance = new DirectoryIterator($pathName);
// Create new instance
$pointerInstance = new FrameworkDirectoryPointer();
// Set directory pointer and path name
- $pointerInstance->setPointer($dirPointer);
+ $pointerInstance->setDirectoryInstance($directoryInstance);
$pointerInstance->setPathName($pathName);
// Return the instance
/**
* Read raw lines of data from a directory pointer and return the data
*
- * @return string Directory and/or file names read from the current
- * directory pointer
+ * @return $current Current entry from encapsulated iterator
*/
public function readRawDirectory () {
- // Read data from the directory pointer and return it
- return readdir($this->getPointer());
+ // Can the next entry be read?
+ assert($this->getDirectoryInstance()->valid());
+
+ // Is it a dot directory?
+ if ($this->getDirectoryInstance()->isDot()) {
+ // Then call this method recursive
+ $current = $this->readRawDirectory();
+ } else {
+ // Read data from the directory pointer and return it
+ $current = $this->getDirectoryInstance()->current();
+ }
+
+ // Advance to next entry
+ $this->getDirectoryInstance()->next();
+
+ // Return found entry
+ return $current;
}
/**
* Read lines from the current directory pointer except some parts
*
- * @param $except Some parts of a directory we want to ignore.
- * Valid: dirs
- * Other values will be silently ignored
- * @return string Directory and/or file names read from the current
- * directory pointer
+ * @param $except Some parts of a directory we want to ignore. Valid: directory and file names, other values will be silently ignored
+ * @return string Directory and/or file names read from the current directory pointer
*/
- public function readDirectoryExcept ($except = '') {
- if ((empty($except)) || (!is_array($except)) || (count($except) == 0)) {
+ public function readDirectoryExcept (array $except = array()) {
+ // No exceptions given?
+ if (count($except) == 0) {
// No exception given, so read all data
+ self::createDebugInstance(__CLASS__)->debugOutput('DIRECTORY[' . __METHOD__ . ':' . __LINE__ . ']: No exceptions given, please use readRawDirectory() instead!');
return $this->readRawDirectory();
- }
+ } // END - if
// Read a raw line...
$rawLine = $this->readRawDirectory();
+ /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DIRECTORY[' . __METHOD__ . ':' . __LINE__ . ']: rawLine[' . gettype($rawLine) . ']=' . $rawLine);
// Shall we exclude directories?
- if ((!is_null($rawLine)) && ($rawLine !== false) && (in_array($rawLine, $except))) {
- // Exclude this part
- return $this->readDirectoryExcept($except);
- } elseif ((!is_null($rawLine)) && ($rawLine !== false)) {
+ if ((!is_null($rawLine)) && ($rawLine !== FALSE) && (!in_array($rawLine, $except))) {
// Return read data
+ /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DIRECTORY[' . __METHOD__ . ':' . __LINE__ . ']: rawLine[' . gettype($rawLine) . ']=' . $rawLine);
return $rawLine;
+ } elseif ((!is_null($rawLine)) && ($rawLine !== FALSE)) {
+ // Exclude this part
+ /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DIRECTORY[' . __METHOD__ . ':' . __LINE__ . ']: rawline[' . gettype($rawLine) . ']=' . $rawLine . ' - Recursive call!');
+ return $this->readDirectoryExcept($except);
}
// End pointer reached
- return null;
+ /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DIRECTORY[' . __METHOD__ . ':' . __LINE__ . ']: Returning NULL!');
+ return NULL;
}
/**
* @return void
*/
public function closeDirectory () {
- // Close the directory pointer and reset the instance variable
- @closedir($this->getPointer());
- $this->setPointer(null);
+ // Close the directory by unsetting it
+ $this->setDirectoryInstance(NULL);
$this->setPathName('');
}
/**
* Setter for the directory pointer
*
- * @param $dirPointer The directory resource
+ * @param $directoryInstance An instanceof a DirectoryIterator class or NULL to unset ("close") it.
* @return void
*/
- public final function setPointer ($dirPointer) {
- // Sanity-check if pointer is a valid directory resource
- if (is_resource($dirPointer) || is_null($dirPointer)) {
- // Is a valid resource
- $this->dirPointer = $dirPointer;
- } else {
- // Throw exception
- throw new InvalidResourceException($this, self::EXCEPTION_INVALID_RESOURCE);
- }
+ protected final function setDirectoryInstance (DirectoryIterator $directoryInstance = NULL) {
+ // Set instance (or NULL)
+ $this->directoryInstance = $directoryInstance;
}
/**
* Getter for the directory pointer
*
- * @return $dirPointer The directory pointer which shall be a valid
- * directory resource
+ * @return $directoryInstance The directory pointer which shall be a valid directory resource
*/
- public final function getPointer () {
- return $this->dirPointer;
+ public final function getDirectoryInstance () {
+ return $this->directoryInstance;
}
/**
* Setter for path name
*
- * @param $pathName The new path name
+ * @param $pathName The new path name
* @return void
*/
public final function setPathName ($pathName) {
/**
* Getter for path name
*
- * @return $pathName The current path name
+ * @return $pathName The current path name
*/
public final function getPathName () {
return $this->pathName;