Standardized code in all of core, not including language files, tests, or core mods.

git-svn-id: http://code.elgg.org/elgg/trunk@7124 36083f99-b078-4883-b0ff-0f9b5a30f544

1 files changed, 93 insertions, 65 deletions

diff --git a/engine/classes/ElggDiskFilestore.php b/engine/classes/ElggDiskFilestore.php
index b0924fbe7..4f9aae1af 100644
--- a/engine/classes/ElggDiskFilestore.php
+++ b/engine/classes/ElggDiskFilestore.php
@@ -5,9 +5,9 @@
  * @warning This should be used by a wrapper class
  * like {@link ElggFile}.
  *
- * @package Elgg.Core
+ * @package    Elgg.Core
  * @subpackage FileStore.Disk
- * @link http://docs.elgg.org/DataModel/FileStore/Disk
+ * @link       http://docs.elgg.org/DataModel/FileStore/Disk
  */
 class ElggDiskFilestore extends ElggFilestore {
 	/**
@@ -42,8 +42,9 @@ class ElggDiskFilestore extends ElggFilestore {
 	 * @warning This will try to create the a directory if it doesn't exist,
 	 * even in read-only mode.
 	 *
-	 * @param ElggFile $file
-	 * @param string $mode read, write, or append.
+	 * @param ElggFile $file The file to open
+	 * @param string   $mode read, write, or append.
+	 *
 	 * @throws InvalidParameterException
 	 * @return resource File pointer resource
 	 * @todo This really shouldn't try to create directories if not writing.
@@ -52,8 +53,8 @@ class ElggDiskFilestore extends ElggFilestore {
 		$fullname = $this->getFilenameOnFilestore($file);
 
 		// Split into path and name
-		$ls = strrpos($fullname,"/");
-		if ($ls===false) {
+		$ls = strrpos($fullname, "/");
+		if ($ls === false) {
 			$ls = 0;
 		}
 
@@ -67,7 +68,7 @@ class ElggDiskFilestore extends ElggFilestore {
 
 		}
 
-		if (($mode!='write') && (!file_exists($fullname))) {
+		if (($mode != 'write') && (!file_exists($fullname))) {
 			return false;
 		}
 
@@ -82,7 +83,8 @@ class ElggDiskFilestore extends ElggFilestore {
 				$mode = "a+b";
 				break;
 			default:
-				throw new InvalidParameterException(sprintf(elgg_echo('InvalidParameterException:UnrecognisedFileMode'), $mode));
+				$msg = sprintf(elgg_echo('InvalidParameterException:UnrecognisedFileMode'), $mode);
+				throw new InvalidParameterException($msg);
 		}
 
 		return fopen($fullname, $mode);
@@ -92,8 +94,9 @@ class ElggDiskFilestore extends ElggFilestore {
 	/**
 	 * Write data to a file.
 	 *
-	 * @param resource $f File pointer resource
-	 * @param mixed $data The data to write.
+	 * @param resource $f    File pointer resource
+	 * @param mixed    $data The data to write.
+	 *
 	 * @return bool
 	 */
 	public function write($f, $data) {
@@ -103,9 +106,10 @@ class ElggDiskFilestore extends ElggFilestore {
 	/**
 	 * Read data from a file.
 	 *
-	 * @param resource $f File pointer resource
-	 * @param int $length The number of bytes to read
-	 * @param inf $offset The number of bytes to start after
+	 * @param resource $f      File pointer resource
+	 * @param int      $length The number of bytes to read
+	 * @param inf      $offset The number of bytes to start after
+	 *
 	 * @return mixed Contents of file or false on fail.
 	 */
 	public function read($f, $length, $offset = 0) {
@@ -120,6 +124,7 @@ class ElggDiskFilestore extends ElggFilestore {
 	 * Close a file pointer
 	 *
 	 * @param resource $f A file pointer resource
+	 *
 	 * @return bool
 	 */
 	public function close($f) {
@@ -130,6 +135,7 @@ class ElggDiskFilestore extends ElggFilestore {
 	 * Delete an ElggFile file.
 	 *
 	 * @param ElggFile $file File to delete
+	 *
 	 * @return bool
 	 */
 	public function delete(ElggFile $file) {
@@ -144,8 +150,10 @@ class ElggDiskFilestore extends ElggFilestore {
 	/**
 	 * Seek to the specified position.
 	 *
-	 * @param resource $f File resource
-	 * @param int $position Position in bytes
+	 * @param resource $f        File resource
+	 * @param int      $position Position in bytes
+	 *
+	 * @return bool
 	 */
 	public function seek($f, $position) {
 		return fseek($f, $position);
@@ -155,6 +163,8 @@ class ElggDiskFilestore extends ElggFilestore {
 	 * Return the current location of the internal pointer
 	 *
 	 * @param resource $f File pointer resource
+	 *
+	 * @return int|false
 	 */
 	public function tell($f) {
 		return ftell($f);
@@ -162,7 +172,10 @@ class ElggDiskFilestore extends ElggFilestore {
 
 	/**
 	 * Tests for end of file on a file pointer
+	 *
 	 * @param resource $f File pointer resource
+	 *
+	 * @return bool
 	 */
 	public function eof($f) {
 		return feof($f);
@@ -171,7 +184,8 @@ class ElggDiskFilestore extends ElggFilestore {
 	/**
 	 * Returns the file size of an ElggFile file.
 	 *
-	 * @param ElggFile $file
+	 * @param ElggFile $file File object
+	 *
 	 * @return int The file size
 	 */
 	public function getFileSize(ElggFile $file) {
@@ -181,7 +195,8 @@ class ElggDiskFilestore extends ElggFilestore {
 	/**
 	 * Returns the filename as saved on disk for an ElggFile object
 	 *
-	 * @param ElggFile $file
+	 * @param ElggFile $file File object
+	 *
 	 * @return string The full path of where the file is stored
 	 */
 	public function getFilenameOnFilestore(ElggFile $file) {
@@ -191,7 +206,9 @@ class ElggDiskFilestore extends ElggFilestore {
 		}
 
 		if ((!$owner) || (!$owner->username)) {
-			throw new InvalidParameterException(sprintf(elgg_echo('InvalidParameterException:MissingOwner'), $file->getFilename(), $file->guid));
+			$msg = sprintf(elgg_echo('InvalidParameterException:MissingOwner'),
+				$file->getFilename(), $file->guid);
+			throw new InvalidParameterException($msg);
 		}
 
 		return $this->dir_root . $this->make_file_matrix($owner->guid) . $file->getFilename();
@@ -200,7 +217,8 @@ class ElggDiskFilestore extends ElggFilestore {
 	/**
 	 * Returns the contents of the ElggFile file.
 	 *
-	 * @param ElggFile $file
+	 * @param ElggFile $file File object
+	 *
 	 * @return mixed
 	 */
 	public function grabFile(ElggFile $file) {
@@ -210,7 +228,8 @@ class ElggDiskFilestore extends ElggFilestore {
 	/**
 	 * Tests if an ElggFile file exists.
 	 *
-	 * @param ElggFile $file
+	 * @param ElggFile $file File object
+	 *
 	 * @return bool
 	 */
 	public function exists(ElggFile $file) {
@@ -220,8 +239,9 @@ class ElggDiskFilestore extends ElggFilestore {
 	/**
 	 * Returns the size of all data stored under a directory in the disk store.
 	 *
-	 * @param string $prefix Optional/ The prefix to check under.
+	 * @param string $prefix         Optional/ The prefix to check under.
 	 * @param string $container_guid The guid of the entity whose data you want to check.
+	 *
 	 * @return int|false
 	 */
 	public function getSize($prefix = '', $container_guid) {
@@ -236,10 +256,26 @@ class ElggDiskFilestore extends ElggFilestore {
 	 * Create a directory $dirroot
 	 *
 	 * @param string $dirroot The full path of the directory to create
+	 *
 	 * @throws IOException
 	 * @return true
+	 * @deprecated 1.8 Use ElggDiskFilestore::makeDirectoryRoot()
 	 */
 	protected function make_directory_root($dirroot) {
+		elgg_deprecated_notice('ElggDiskFilestore::make_directory_root() is deprecated by ::makeDirectoryRoot()', 1.8);
+
+		return $this->makeDirectoryRoot($dirroot);
+	}
+
+	/**
+	 * Create a directory $dirroot
+	 *
+	 * @param string $dirroot The full path of the directory to create
+	 *
+	 * @throws IOException
+	 * @return true
+	 */
+	protected function makeDirectoryRoot($dirroot) {
 		if (!file_exists($dirroot)) {
 			if (!@mkdir($dirroot, 0700, true)) {
 				throw new IOException(sprintf(elgg_echo('IOException:CouldNotMake'), $dirroot));
@@ -252,15 +288,18 @@ class ElggDiskFilestore extends ElggFilestore {
 	/**
 	 * Multibyte string tokeniser.
 	 *
-	 * Splits a string into an array. Will fail safely if mbstring is not installed (although this may still
-	 * not handle .
+	 * Splits a string into an array. Will fail safely if mbstring is
+	 * not installed.
 	 *
-	 * @param string $string String
+	 * @param string $string  String
 	 * @param string $charset The charset, defaults to UTF8
+	 *
 	 * @return array
-	 * @todo Can be deprecated since we no long split on usernames
+	 * @deprecated 1.8 Files are stored by date and guid; no need for this.
 	 */
 	private function mb_str_split($string, $charset = 'UTF8') {
+		elgg_deprecated_notice('ElggDiskFilestore::mb_str_split() is deprecated.', 1.8);
+
 		if (is_callable('mb_substr')) {
 			$length = mb_strlen($string);
 			$array = array();
@@ -283,15 +322,34 @@ class ElggDiskFilestore extends ElggFilestore {
 	/**
 	 * Construct a file path matrix for an entity.
 	 *
-	 * @param int The guide of the entity to store the data under.
+	 * @param int $identifier The guide of the entity to store the data under.
+	 *
 	 * @return str The path where the entity's data will be stored.
+	 * @deprecated 1.8 Use ElggDiskFilestore::makeFileMatrix()
 	 */
 	protected function make_file_matrix($identifier) {
-		if (is_numeric($identifier)) {
-			return $this->user_file_matrix($identifier);
+		elgg_deprecated_notice('ElggDiskFilestore::make_file_matrix() is deprecated by ::makeFileMatrix()', 1.8);
+
+		return $this->makefileMatrix($identifier);
+	}
+
+	/**
+	 * Construct a file path matrix for an entity.
+	 *
+	 * @param int $guid The guide of the entity to store the data under.
+	 *
+	 * @return str The path where the entity's data will be stored.
+	 */
+	protected function makeFileMatrix($guid) {
+		$entity = get_entity($guid);
+
+		if (!($entity instanceof ElggEntity) || !$entity->time_created) {
+			return false;
 		}
 
-		return $this->deprecated_file_matrix($identifier);
+		$time_created = date('Y/m/d', $entity->time_created);
+
+		return "$time_created/$entity->guid/";
 	}
 
 	/**
@@ -304,45 +362,13 @@ class ElggDiskFilestore extends ElggFilestore {
 	 * YYYY/MM/DD/guid/
 	 *
 	 * @param int $guid The entity to contrust a matrix for
+	 *
 	 * @return str The
-	 * @todo This would work with non-users.  Why is it restricted to only users?
 	 */
 	protected function user_file_matrix($guid) {
-		// lookup the entity
-		$user = get_entity($guid);
-		if ($user->type != 'user') {
-			// only to be used for user directories
-			return FALSE;
-		}
-
-		if (!$user->time_created) {
-			// fall back to deprecated method
-			return $this->deprecated_file_matrix($user->username);
-		}
-
-		$time_created = date('Y/m/d', $user->time_created);
-		return "$time_created/$user->guid/";
-	}
+		elgg_deprecated_notice('ElggDiskFilestore::user_file_matrix() is deprecated by ::makeFileMatrix()', 1.8);
 
-	/**
-	 * Construct the filename matrix using a string
-	 *
-	 * Particularly, this is used with a username to generate the file storage
-	 * location.
-	 *
-	 * @deprecated for user directories: use user_file_matrix() instead.
-	 *
-	 * @param str $filename
-	 * @return str
-	 */
-	protected function deprecated_file_matrix($filename) {
-		// throw a warning for using deprecated method
-		$error  = 'Deprecated use of ElggDiskFilestore::make_file_matrix. ';
-		$error .= 'Username passed instead of guid.';
-		elgg_log($error, WARNING);
-
-		$user = new ElggUser($filename);
-		return $this->user_file_matrix($user->guid);
+		return $this->makeFileMatrix($guid);
 	}
 
 	/**
@@ -358,7 +384,9 @@ class ElggDiskFilestore extends ElggFilestore {
 	/**
 	 * Sets parameters that should be saved to database.
 	 *
-	 * return bool
+	 * @param array $parameters Set parameters to save to DB for this filestore.
+	 *
+	 * @return bool
 	 */
 	public function setParameters(array $parameters) {
 		if (isset($parameters['dir_root'])) {