Mistralys / application-utils

src/FileHelper.php

Indentation +233 added lines, -233 removed lines

@@ -73,18 +73,18 @@ 
     public const ERROR_PATH_NOT_WRITABLE = 340039;
     public const ERROR_PATH_INVALID = 340040;
 
-   /**
-    * Opens a serialized file and returns the unserialized data.
-    *
-    * @param string $file
-    * @throws FileHelper_Exception
-    * @return array<int|string,mixed>
-    * @see SerializedFile::parse()
-    * 
-    * @see FileHelper::ERROR_FILE_DOES_NOT_EXIST
-    * @see FileHelper::ERROR_SERIALIZED_FILE_CANNOT_BE_READ
-    * @see FileHelper::ERROR_SERIALIZED_FILE_UNSERIALZE_FAILED
-    */
+    /**
+     * Opens a serialized file and returns the unserialized data.
+     *
+     * @param string $file
+     * @throws FileHelper_Exception
+     * @return array<int|string,mixed>
+     * @see SerializedFile::parse()
+     * 
+     * @see FileHelper::ERROR_FILE_DOES_NOT_EXIST
+     * @see FileHelper::ERROR_SERIALIZED_FILE_CANNOT_BE_READ
+     * @see FileHelper::ERROR_SERIALIZED_FILE_UNSERIALZE_FAILED
+     */
     public static function parseSerializedFile(string $file) : array
     {
         return SerializedFile::factory(self::getFileInfo($file))
@@ -104,13 +104,13 @@ 
         return FolderTree::delete($rootFolder);
     }
     
-   /**
-    * Create a folder, if it does not exist yet.
-    *  
-    * @param string|PathInfoInterface $path
-    * @throws FileHelper_Exception
-    * @see FileHelper::ERROR_CANNOT_CREATE_FOLDER
-    */
+    /**
+     * Create a folder, if it does not exist yet.
+     *  
+     * @param string|PathInfoInterface $path
+     * @throws FileHelper_Exception
+     * @see FileHelper::ERROR_CANNOT_CREATE_FOLDER
+     */
     public static function createFolder($path) : FolderInfo
     {
         return self::getFolderInfo($path)->create();
@@ -138,36 +138,36 @@ 
         FolderTree::copy($source, $target);
     }
     
-   /**
-    * Copies a file to the target location. Includes checks
-    * for most error sources, like the source file not being
-    * readable. Automatically creates the target folder if it
-    * does not exist yet.
-    * 
-    * @param string $sourcePath
-    * @param string $targetPath
-    * @throws FileHelper_Exception
-    * 
-    * @see FileHelper::ERROR_CANNOT_CREATE_FOLDER
-    * @see FileHelper::ERROR_SOURCE_FILE_NOT_FOUND
-    * @see FileHelper::ERROR_SOURCE_FILE_NOT_READABLE
-    * @see FileHelper::ERROR_TARGET_COPY_FOLDER_NOT_WRITABLE
-    * @see FileHelper::ERROR_CANNOT_COPY_FILE
-    */
+    /**
+     * Copies a file to the target location. Includes checks
+     * for most error sources, like the source file not being
+     * readable. Automatically creates the target folder if it
+     * does not exist yet.
+     * 
+     * @param string $sourcePath
+     * @param string $targetPath
+     * @throws FileHelper_Exception
+     * 
+     * @see FileHelper::ERROR_CANNOT_CREATE_FOLDER
+     * @see FileHelper::ERROR_SOURCE_FILE_NOT_FOUND
+     * @see FileHelper::ERROR_SOURCE_FILE_NOT_READABLE
+     * @see FileHelper::ERROR_TARGET_COPY_FOLDER_NOT_WRITABLE
+     * @see FileHelper::ERROR_CANNOT_COPY_FILE
+     */
     public static function copyFile(string $sourcePath, string $targetPath) : void
     {
         self::getFileInfo($sourcePath)->copyTo($targetPath);
     }
     
-   /**
-    * Deletes the target file. Ignored if it cannot be found,
-    * and throws an exception if it fails.
-    * 
-    * @param string $filePath
-    * @throws FileHelper_Exception
-    * 
-    * @see FileHelper::ERROR_CANNOT_DELETE_FILE
-    */
+    /**
+     * Deletes the target file. Ignored if it cannot be found,
+     * and throws an exception if it fails.
+     * 
+     * @param string $filePath
+     * @throws FileHelper_Exception
+     * 
+     * @see FileHelper::ERROR_CANNOT_DELETE_FILE
+     */
     public static function deleteFile(string $filePath) : void
     {
         self::getFileInfo($filePath)->delete();
@@ -272,46 +272,46 @@ 
             ->download();
     }
     
-   /**
-    * Verifies whether the target file is a PHP file. The path
-    * to the file can be a path to a file as a string, or a 
-    * DirectoryIterator object instance.
-    * 
-    * @param string|DirectoryIterator $pathOrDirIterator
-    * @return boolean
-    */
+    /**
+     * Verifies whether the target file is a PHP file. The path
+     * to the file can be a path to a file as a string, or a 
+     * DirectoryIterator object instance.
+     * 
+     * @param string|DirectoryIterator $pathOrDirIterator
+     * @return boolean
+     */
     public static function isPHPFile($pathOrDirIterator) : bool
     {
-    	return self::getExtension($pathOrDirIterator) === 'php';
+        return self::getExtension($pathOrDirIterator) === 'php';
     }
     
-   /**
-    * Retrieves the extension of the specified file. Can be a path
-    * to a file as a string, or a DirectoryIterator object instance.
-    *
-    * NOTE: A folder will return an empty string.
-    * 
-    * @param string|DirectoryIterator $pathOrDirIterator
-    * @param bool $lowercase
-    * @return string
-    */
+    /**
+     * Retrieves the extension of the specified file. Can be a path
+     * to a file as a string, or a DirectoryIterator object instance.
+     *
+     * NOTE: A folder will return an empty string.
+     * 
+     * @param string|DirectoryIterator $pathOrDirIterator
+     * @param bool $lowercase
+     * @return string
+     */
     public static function getExtension($pathOrDirIterator, bool $lowercase = true) : string
     {
         return self::getPathInfo($pathOrDirIterator)->getExtension($lowercase);
     }
     
-   /**
-    * Retrieves the file name from a path, with or without extension.
-    * The path to the file can be a string, or a DirectoryIterator object
-    * instance.
-    * 
-    * In case of folders, behaves like the "pathinfo" function: returns
-    * the name of the folder.
-    * 
-    * @param string|DirectoryIterator $pathOrDirIterator
-    * @param bool $extension
-    * @return string
-    */
+    /**
+     * Retrieves the file name from a path, with or without extension.
+     * The path to the file can be a string, or a DirectoryIterator object
+     * instance.
+     * 
+     * In case of folders, behaves like the "pathinfo" function: returns
+     * the name of the folder.
+     * 
+     * @param string|DirectoryIterator $pathOrDirIterator
+     * @param bool $extension
+     * @return string
+     */
     public static function getFilename($pathOrDirIterator, bool $extension = true) : string
     {
         $info = self::getPathInfo($pathOrDirIterator);
@@ -345,16 +345,16 @@ 
             ->parse();
     }
     
-   /**
-    * Corrects common formatting mistakes when users enter
-    * file names, like too many spaces, dots and the like.
-    * 
-    * NOTE: if the file name contains a path, the path is
-    * stripped, leaving only the file name.
-    * 
-    * @param string $name
-    * @return string
-    */
+    /**
+     * Corrects common formatting mistakes when users enter
+     * file names, like too many spaces, dots and the like.
+     * 
+     * NOTE: if the file name contains a path, the path is
+     * stripped, leaving only the file name.
+     * 
+     * @param string $name
+     * @return string
+     */
     public static function fixFileName(string $name) : string
     {
         return NameFixer::fixName($name);
@@ -414,23 +414,23 @@ 
         return self::findFiles($targetFolder, array('php'), $options);
     }
     
-   /**
-    * Finds files according to the specified options.
-    * 
-    * NOTE: This method only exists for backwards compatibility.
-    * Use the {@see FileHelper::createFileFinder()} method instead,
-    * which offers an object-oriented interface that is much easier
-    * to use.
-    *  
-    * @param string|PathInfoInterface|DirectoryIterator $targetFolder
-    * @param string[] $extensions
-    * @param array<string,mixed> $options
-    * @throws FileHelper_Exception
-    * @return string[]
-    *
-    * @see FileHelper::createFileFinder()
-    * @deprecated Use the file finder instead.
-    */
+    /**
+     * Finds files according to the specified options.
+     * 
+     * NOTE: This method only exists for backwards compatibility.
+     * Use the {@see FileHelper::createFileFinder()} method instead,
+     * which offers an object-oriented interface that is much easier
+     * to use.
+     *  
+     * @param string|PathInfoInterface|DirectoryIterator $targetFolder
+     * @param string[] $extensions
+     * @param array<string,mixed> $options
+     * @throws FileHelper_Exception
+     * @return string[]
+     *
+     * @see FileHelper::createFileFinder()
+     * @deprecated Use the file finder instead.
+     */
     public static function findFiles($targetFolder, array $extensions=array(), array $options=array()) : array
     {
         $finder = self::createFileFinder($targetFolder);
@@ -460,14 +460,14 @@ 
         return $finder->getAll();
     }
 
-   /**
-    * Removes the extension from the specified path or file name,
-    * if any, and returns the name without the extension.
-    * 
-    * @param string $filename
-    * @param bool $keepPath Whether to keep the path component, if any. Default PHP pathinfo behavior is not to.
-    * @return string
-    */
+    /**
+     * Removes the extension from the specified path or file name,
+     * if any, and returns the name without the extension.
+     * 
+     * @param string $filename
+     * @param bool $keepPath Whether to keep the path component, if any. Default PHP pathinfo behavior is not to.
+     * @return string
+     */
     public static function removeExtension(string $filename, bool $keepPath=false) : string
     {
         return self::getFileInfo($filename)->removeExtension($keepPath);
@@ -488,49 +488,49 @@ 
         return self::$unicodeHandling;
     }
     
-   /**
-    * Normalizes the slash style in a file or folder path,
-    * by replacing any anti-slashes with forward slashes.
-    * 
-    * @param string $path
-    * @return string
-    */
+    /**
+     * Normalizes the slash style in a file or folder path,
+     * by replacing any anti-slashes with forward slashes.
+     * 
+     * @param string $path
+     * @return string
+     */
     public static function normalizePath(string $path) : string
     {
         return str_replace(array('\\', '//'), array('/', '/'), $path);
     }
     
-   /**
-    * Saves the specified data to a file, JSON encoded.
-    * 
-    * @param mixed $data
-    * @param string $file
-    * @param bool $pretty
-    * @throws FileHelper_Exception
-    * 
-    * @see FileHelper::ERROR_JSON_ENCODE_ERROR
-    * @see FileHelper::ERROR_SAVE_FOLDER_NOT_WRITABLE
-    * @see FileHelper::ERROR_SAVE_FILE_NOT_WRITABLE
-    * @see FileHelper::ERROR_SAVE_FILE_WRITE_FAILED
-    */
+    /**
+     * Saves the specified data to a file, JSON encoded.
+     * 
+     * @param mixed $data
+     * @param string $file
+     * @param bool $pretty
+     * @throws FileHelper_Exception
+     * 
+     * @see FileHelper::ERROR_JSON_ENCODE_ERROR
+     * @see FileHelper::ERROR_SAVE_FOLDER_NOT_WRITABLE
+     * @see FileHelper::ERROR_SAVE_FILE_NOT_WRITABLE
+     * @see FileHelper::ERROR_SAVE_FILE_WRITE_FAILED
+     */
     public static function saveAsJSON($data, string $file, bool $pretty=false) : void
     {
         JSONFile::factory(self::getFileInfo($file))
             ->putData($data, $pretty);
     }
    
-   /**
-    * Saves the specified content to the target file, creating
-    * the file and the folder as necessary.
-    * 
-    * @param string $filePath
-    * @param string $content
-    * @throws FileHelper_Exception
-    * 
-    * @see FileHelper::ERROR_SAVE_FOLDER_NOT_WRITABLE
-    * @see FileHelper::ERROR_SAVE_FILE_NOT_WRITABLE
-    * @see FileHelper::ERROR_SAVE_FILE_WRITE_FAILED
-    */
+    /**
+     * Saves the specified content to the target file, creating
+     * the file and the folder as necessary.
+     * 
+     * @param string $filePath
+     * @param string $content
+     * @throws FileHelper_Exception
+     * 
+     * @see FileHelper::ERROR_SAVE_FOLDER_NOT_WRITABLE
+     * @see FileHelper::ERROR_SAVE_FILE_NOT_WRITABLE
+     * @see FileHelper::ERROR_SAVE_FILE_WRITE_FAILED
+     */
     public static function saveFile(string $filePath, string $content='') : void
     {
         self::getFileInfo($filePath)->putContents($content);
@@ -595,14 +595,14 @@ 
         return $output;
     }
     
-   /**
-    * Retrieves the last modified date for the specified file or folder.
-    * 
-    * Note: If the target does not exist, returns null. 
-    * 
-    * @param string $path
-    * @return DateTime|NULL
-    */
+    /**
+     * Retrieves the last modified date for the specified file or folder.
+     * 
+     * Note: If the target does not exist, returns null. 
+     * 
+     * @param string $path
+     * @return DateTime|NULL
+     */
     public static function getModifiedDate(string $path) : ?DateTime
     {
         $time = filemtime($path);
@@ -642,70 +642,70 @@ 
             ->getPaths();
     }
 
-   /**
-    * Retrieves the maximum allowed upload file size, in bytes.
-    * Takes into account the PHP ini settings <code>post_max_size</code>
-    * and <code>upload_max_filesize</code>. Since these cannot
-    * be modified at runtime, they are the hard limits for uploads.
-    * 
-    * NOTE: Based on binary values, where 1KB = 1024 Bytes.
-    * 
-    * @return int Will return <code>-1</code> if no limit.
-    */
+    /**
+     * Retrieves the maximum allowed upload file size, in bytes.
+     * Takes into account the PHP ini settings <code>post_max_size</code>
+     * and <code>upload_max_filesize</code>. Since these cannot
+     * be modified at runtime, they are the hard limits for uploads.
+     * 
+     * NOTE: Based on binary values, where 1KB = 1024 Bytes.
+     * 
+     * @return int Will return <code>-1</code> if no limit.
+     */
     public static function getMaxUploadFilesize() : int
     {
         return UploadFileSizeInfo::getFileSize();
     }
    
-   /**
-    * Makes a path relative using a folder depth: will reduce the
-    * length of the path so that only the amount of folders defined
-    * in the <code>$depth</code> attribute are shown below the actual
-    * folder or file in the path.
-    *  
-    * @param string  $path The absolute or relative path
-    * @param int $depth The folder depth to reduce the path to
-    * @return string
-    */
+    /**
+     * Makes a path relative using a folder depth: will reduce the
+     * length of the path so that only the amount of folders defined
+     * in the <code>$depth</code> attribute are shown below the actual
+     * folder or file in the path.
+     *  
+     * @param string  $path The absolute or relative path
+     * @param int $depth The folder depth to reduce the path to
+     * @return string
+     */
     public static function relativizePathByDepth(string $path, int $depth=2) : string
     {
         return PathRelativizer::relativizeByDepth($path, $depth);
     }
     
-   /**
-    * Makes the specified path relative to another path,
-    * by removing one from the other if found. Also 
-    * normalizes the path to use forward slashes. 
-    * 
-    * Example:
-    * 
-    * <pre>
-    * relativizePath('c:\some\folder\to\file.txt', 'c:\some\folder');
-    * </pre>
-    * 
-    * Result: <code>to/file.txt</code>
-    * 
-    * @param string $path
-    * @param string $relativeTo
-    * @return string
-    */
+    /**
+     * Makes the specified path relative to another path,
+     * by removing one from the other if found. Also 
+     * normalizes the path to use forward slashes. 
+     * 
+     * Example:
+     * 
+     * <pre>
+     * relativizePath('c:\some\folder\to\file.txt', 'c:\some\folder');
+     * </pre>
+     * 
+     * Result: <code>to/file.txt</code>
+     * 
+     * @param string $path
+     * @param string $relativeTo
+     * @return string
+     */
     public static function relativizePath(string $path, string $relativeTo) : string
     {
         return PathRelativizer::relativize($path, $relativeTo);
     }
     
-   /**
-    * Checks that the target file exists, and throws an exception
-    * if it does not. 
-    * 
-    * @param string|DirectoryIterator $path
-    * @param int|NULL $errorCode Optional custom error code
-    * @throws FileHelper_Exception
-    * @return string The real path to the file
-    * 
-    * @see FileHelper::ERROR_FILE_DOES_NOT_EXIST
-    * @see FileHelper::ERROR_REAL_PATH_NOT_FOUND
-    */
+    /**
+     * Checks that the target file exists, and throws an exception
+     * if it does not. 
+     * 
+     * @param string|DirectoryIterator $path
+     * @param int|NULL $errorCode Optional custom error code
+     * @throws FileHelper_Exception
+     * @return string The real path to the file
+     * 
+     * @see FileHelper::ERROR_FILE_DOES_NOT_EXIST
+     * @see FileHelper::ERROR_REAL_PATH_NOT_FOUND
+     */
     public static function requireFileExists($path, ?int $errorCode=null) : string
     {
         return self::getPathInfo($path)
@@ -728,18 +728,18 @@ 
             ->getPath();
     }
     
-   /**
-    * Reads a specific line number from the target file and returns its
-    * contents, if the file has such a line. Does so with little memory
-    * usage, as the file is not read entirely into memory.
-    * 
-    * @param string $path
-    * @param int $lineNumber Note: 1-based; the first line is number 1.
-    * @return string|NULL Will return null if the requested line does not exist.
-    * @throws FileHelper_Exception
-    * 
-    * @see FileHelper::ERROR_FILE_DOES_NOT_EXIST
-    */
+    /**
+     * Reads a specific line number from the target file and returns its
+     * contents, if the file has such a line. Does so with little memory
+     * usage, as the file is not read entirely into memory.
+     * 
+     * @param string $path
+     * @param int $lineNumber Note: 1-based; the first line is number 1.
+     * @return string|NULL Will return null if the requested line does not exist.
+     * @throws FileHelper_Exception
+     * 
+     * @see FileHelper::ERROR_FILE_DOES_NOT_EXIST
+     */
     public static function getLineFromFile(string $path, int $lineNumber) : ?string
     {
         return self::getFileInfo($path)
@@ -816,33 +816,33 @@ 
             ->getLines($amount);
     }
     
-   /**
-    * Reads all content from a file.
-    * 
-    * @param string $filePath
-    * @throws FileHelper_Exception
-    * @return string
-    * 
-    * @see FileHelper::ERROR_FILE_DOES_NOT_EXIST
-    * @see FileHelper::ERROR_CANNOT_READ_FILE_CONTENTS
-    */
+    /**
+     * Reads all content from a file.
+     * 
+     * @param string $filePath
+     * @throws FileHelper_Exception
+     * @return string
+     * 
+     * @see FileHelper::ERROR_FILE_DOES_NOT_EXIST
+     * @see FileHelper::ERROR_CANNOT_READ_FILE_CONTENTS
+     */
     public static function readContents(string $filePath) : string
     {
         return self::getFileInfo($filePath)->getContents();
     }
 
-   /**
-    * Ensures that the target path exists on disk, and is a folder.
-    * 
-    * @param string $path
-    * @return string The real path, with normalized slashes.
-    * @throws FileHelper_Exception
-    * 
-    * @see FileHelper::normalizePath()
-    * 
-    * @see FileHelper::ERROR_FOLDER_DOES_NOT_EXIST
-    * @see FileHelper::ERROR_PATH_IS_NOT_A_FOLDER
-    */
+    /**
+     * Ensures that the target path exists on disk, and is a folder.
+     * 
+     * @param string $path
+     * @return string The real path, with normalized slashes.
+     * @throws FileHelper_Exception
+     * 
+     * @see FileHelper::normalizePath()
+     * 
+     * @see FileHelper::ERROR_FOLDER_DOES_NOT_EXIST
+     * @see FileHelper::ERROR_PATH_IS_NOT_A_FOLDER
+     */
     public static function requireFolderExists(string $path) : string
     {
         return self::getFolderInfo($path)