BackwardsCompatibilityBreak - fUpload no longer accepts uploaded file…

…s that start with a `.` unless ::allowDotFiles() is called. Added fUpload::setOptional().

classes/fUpload.php

@@ -9,8 +9,9 @@
  * @package    Flourish
  * @link       http://flourishlib.com/fUpload
  * 
- * @version    1.0.0b8
- * @changes    1.0.0b8  BackwardsCompatiblityBreak - ::validate() no longer returns the `$_FILES` array for the file being validated - added `$return_message` parameter to ::validate(), fixed a bug with detection of mime type for text files [wb, 2010-05-26]
+ * @version    1.0.0b9
+ * @changes    1.0.0b9  BackwardsCompatibilityBreak - the class no longer accepts uploaded files that start with a `.` unless ::allowDotFiles() is called - added ::setOptional() [wb, 2010-05-30]
+ * @changes    1.0.0b8  BackwardsCompatibilityBreak - ::validate() no longer returns the `$_FILES` array for the file being validated - added `$return_message` parameter to ::validate(), fixed a bug with detection of mime type for text files [wb, 2010-05-26]
  * @changes    1.0.0b7  Added ::filter() to allow for ignoring array file upload field entries that did not have a file uploaded [wb, 2009-10-06]
  * @changes    1.0.0b6  Updated ::move() to use the new fFilesystem::createObject() method [wb, 2009-01-21]
  * @changes    1.0.0b5  Removed some unnecessary error suppression operators from ::move() [wb, 2009-01-05]
@@ -130,9 +131,16 @@ static public function filter($field)
 
 
 	/**
-	 * The type of files accepted
+	 * If files starting with `.` can be uploaded
 	 * 
-	 * @var string
+	 * @var boolean
+	 */
+	private $allow_dot_files = FALSE;
+
+	/**
+	 * If PHP files can be uploaded
+	 * 
+	 * @var boolean
 	 */
 	private $allow_php = FALSE;
 
@@ -164,6 +172,13 @@ static public function filter($field)
 	 */
 	private $mime_types = array();
 
+	/**
+	 * If the file upload is required
+	 * 
+	 * @var boolean
+	 */
+	private $required = TRUE;
+
 
 	/**
 	 * All requests that hit this method should be requests for callbacks
@@ -179,6 +194,20 @@ public function __get($method)
 	}
 
 
+	/**
+	 * Sets the upload class to allow files starting with a `.`
+	 * 
+	 * Files starting with `.` may change the behaviour of web servers,
+	 * for instance `.htaccess` files for Apache.
+	 * 
+	 * @return void
+	 */
+	public function allowDotFiles()
+	{
+		$this->allow_dot_files = TRUE;
+	}
+
+
 	/**
 	 * Sets the upload class to allow PHP files
 	 * 
@@ -248,7 +277,7 @@ private function extractFileUploadArray($field, $index=NULL)
 	 * @param  string|fDirectory $directory  The directory to upload the file to
 	 * @param  string            $field      The file upload field to get the file from
 	 * @param  mixed             $index      If the field was an array file upload field, upload the file corresponding to this index
-	 * @return fFile  An fFile (or fImage) object
+	 * @return fFile|NULL  An fFile (or fImage) object, or `NULL` if no file was uploaded
 	 */
 	public function move($directory, $field, $index=NULL)
 	{
@@ -276,6 +305,11 @@ public function move($directory, $field, $index=NULL)
 			throw new fValidationException($error);
 		}
 
+		// This will only ever be true if the file is optional
+		if ($file_array['name'] == '' || $file_array['tmp_name'] == '' || $file_array['size'] == 0) {
+			return NULL;
+		}
+
 		$file_name  = fFilesystem::makeURLSafe($file_array['name']);
 
 		$file_name = $directory->getPath() . $file_name;
@@ -321,6 +355,17 @@ public function setMIMETypes($mime_types, $message)
 	}
 
 
+	/**
+	 * Sets the file upload to be optional instead of required
+	 * 
+	 * @return void
+	 */
+	public function setOptional()
+	{
+		$this->required = FALSE;
+	}
+
+
 	/**
 	 * Validates the uploaded file, ensuring a file was actually uploaded and that is matched the restrictions put in place
 	 * 
@@ -331,7 +376,7 @@ public function setMIMETypes($mime_types, $message)
 	 * @param  boolean $return_message  If any validation error should be returned as a string instead of being thrown as an fValidationException
 	 * @param  string  :$field
 	 * @param  boolean :$return_message
-	 * @return void
+	 * @return NULL|string  If `$return_message` is not `TRUE` or if no error occurs, `NULL`, otherwise a string error message
 	 */
 	public function validate($field, $index=NULL, $return_message=NULL)
 	{
@@ -367,7 +412,10 @@ public function validate($field, $index=NULL, $return_message=NULL)
 	private function validateField($file_array)
 	{
 		if (empty($file_array['name'])) {
-			return self::compose('Please upload a file');
+			if ($this->required) {
+				return self::compose('Please upload a file');
+			}
+			return NULL;
 		}
 
 		if ($file_array['error'] == UPLOAD_ERR_FORM_SIZE || $file_array['error'] == UPLOAD_ERR_INI_SIZE) {
@@ -386,7 +434,10 @@ private function validateField($file_array)
 		}
 
 		if (empty($file_array['tmp_name']) || empty($file_array['size'])) {
-			return self::compose('Please upload a file');	
+			if ($this->required) {
+				return self::compose('Please upload a file');
+			}
+			return NULL;	
 		}
 
 		if (!empty($this->mime_types) && file_exists($file_array['tmp_name'])) {
@@ -402,6 +453,12 @@ private function validateField($file_array)
 				return self::compose('The file uploaded is a PHP file, but those are not permitted');
 			}
 		}
+
+		if (!$this->allow_dot_files) {
+			if (substr($file_array['name'], 0, 1) == '.') {
+				return self::compose('The name of the uploaded file may not being with a .');
+			}
+		}
 	}
 }