From 31667cb2571c9e4da209237bfd1b79c382b8caf3 Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Sun, 21 Aug 2016 19:15:42 +0200 Subject: [PATCH] Added more comments --- DataStorage/Database/DataMapperAbstract.php | 10 + System/File/File.php | 191 ++++++++++++++++++-- Utils/StringUtils.php | 113 ++++++++---- Validation/Base/CreditCard.php | 12 +- 4 files changed, 267 insertions(+), 59 deletions(-) diff --git a/DataStorage/Database/DataMapperAbstract.php b/DataStorage/Database/DataMapperAbstract.php index a28425dcc..a7a642436 100644 --- a/DataStorage/Database/DataMapperAbstract.php +++ b/DataStorage/Database/DataMapperAbstract.php @@ -263,6 +263,16 @@ class DataMapperAbstract implements DataMapperInterface return __CLASS__; } + /** + * Resets all loaded mapper variables. + * + * This is used after one action is performed otherwise other models would use wrong settings. + * + * @return void + * + * @since 1.0.0 + * @author Dennis Eichhorn + */ public static function clear() { self::$overwrite = true; diff --git a/System/File/File.php b/System/File/File.php index 4cbb6ab29..3d7d3df76 100644 --- a/System/File/File.php +++ b/System/File/File.php @@ -68,20 +68,20 @@ class File extends FileAbstract * Save string to file. * * If the directory doesn't exist where the string should be saved it will be created - * as well as potential subdirectories. The directories will be created with '0644' + * as well as potential parent directories. The directories will be created with '0644' * permission. * - * @param string $path Path to save the string to - * @param string $content Content to save to file - * @param bool $overwrite Should the file be overwritten if it already exists + * @param string $path Path to save the string to + * @param string $content Content to save to file + * @param bool $overwrite Should the file be overwritten if it already exists * * @example File::put('/var/www/html/test.txt', 'string'); // true * @example File::put('/var/www/html/test.txt', 'string', false); // false * - * @return bool Returns true on successfule file write and false on failure + * @return bool Returns true on successful file write and false on failure * - * @since 1.0.0 - * @author Dennis Eichhorn + * @since 1.0.0 + * @author Dennis Eichhorn */ public static function put(string $path, string $content, bool $overwrite = true) : bool { @@ -109,8 +109,8 @@ class File extends FileAbstract * * @throws PathException In case the file doesn't exist this exception gets thrown. * - * @since 1.0.0 - * @author Dennis Eichhorn + * @since 1.0.0 + * @author Dennis Eichhorn */ public static function get(string $path) : string { @@ -130,8 +130,8 @@ class File extends FileAbstract * * @return bool Returns true if the file exists and false if it doesn't. * - * @since 1.0.0 - * @author Dennis Eichhorn + * @since 1.0.0 + * @author Dennis Eichhorn */ public static function exists(string $path) : bool { @@ -147,8 +147,8 @@ class File extends FileAbstract * * @return string Returns the parent full directory path. * - * @since 1.0.0 - * @author Dennis Eichhorn + * @since 1.0.0 + * @author Dennis Eichhorn */ public static function parent(string $path) : string { @@ -166,8 +166,8 @@ class File extends FileAbstract * * @example File::created('/var/www/html/test.txt'); * - * @since 1.0.0 - * @author Dennis Eichhorn + * @since 1.0.0 + * @author Dennis Eichhorn */ public static function created(string $path) : \DateTime { @@ -192,8 +192,8 @@ class File extends FileAbstract * * @example File::changed('/var/www/html/test.txt'); * - * @since 1.0.0 - * @author Dennis Eichhorn + * @since 1.0.0 + * @author Dennis Eichhorn */ public static function changed(string $path) : \DateTime { @@ -207,6 +207,18 @@ class File extends FileAbstract return $changed; } + /** + * Gets the size of a file. + * + * @param string $path Path of the file to get the size for. + * + * @return int Returns the size of a file + * + * @example File::size('/var/www/html/test.txt'); + * + * @since 1.0.0 + * @author Dennis Eichhorn + */ public static function size(string $path) : int { if (!file_exists($path)) { @@ -216,6 +228,18 @@ class File extends FileAbstract return filesize($path); } + /** + * Gets the owner of a file. + * + * @param string $path Path of the file to get owner for. + * + * @return int Returns the owner of a file. + * + * @example File::owner('/var/www/html/test.txt'); + * + * @since 1.0.0 + * @author Dennis Eichhorn + */ public static function owner(string $path) : int { if (!file_exists($path)) { @@ -225,6 +249,18 @@ class File extends FileAbstract return fileowner($path); } + /** + * Gets the permission of a file. + * + * @param string $path Path of the file to get the permission for. + * + * @return int Returns the permission of a file + * + * @example File::size('/var/www/html/test.txt'); + * + * @since 1.0.0 + * @author Dennis Eichhorn + */ public static function permission(string $path) : int { if (!file_exists($path)) { @@ -234,11 +270,61 @@ class File extends FileAbstract return fileperms($path); } + /** + * Gets the directory name of a file. + * + * @param string $path Path of the file to get the directory name for. + * + * @return string Returns the directory name of a file. + * + * @example File::size('/var/www/html/test.txt'); // html + * + * @since 1.0.0 + * @author Dennis Eichhorn + */ public static function dirname(string $path) : string + { + return basename(dirname($path)); + } + + /** + * Gets the directory path of a file. + * + * @param string $path Path of the file to get the directory path for. + * + * @return string Returns the directory path of a file. + * + * @example File::size('/var/www/html/test.txt'); // /var/www/html + * + * @since 1.0.0 + * @author Dennis Eichhorn + */ + public static function dirpath(string $path) : string { return dirname($path); } + /** + * Copies a file. + * + * If the directory doesn't exist where the file should be copied to it will be created + * as well as potential parent directories. The directories will be created with '0644' + * permission. + * + * @param string $from The path of the file to copy. + * @param string $to The path and name of the file where to save the copy. + * @param bool $overwrite Should the file be overwritten if it already exists + * + * @example File::copy('/var/www/html/test.txt', '/var/www/html/test2.txt'); // true + * @example File::copy('/var/www/html/test.txt', '/var/www/html/test2.txt'); // false + * + * @return bool Returns true on successful file copy and false on failure + * + * @throws PathException Throws this exception if the file to copy doesn't exist. + * + * @since 1.0.0 + * @author Dennis Eichhorn + */ public static function copy(string $from, string $to, bool $overwrite = false) : bool { if (!file_exists($from)) { @@ -258,6 +344,27 @@ class File extends FileAbstract return false; } + /** + * Moves a file. + * + * If the directory doesn't exist where the file should be moved to it will be created + * as well as potential parent directories. The directories will be created with '0644' + * permission. + * + * @param string $from The path of the file to move. + * @param string $to The path and name of the file where to move it. + * @param bool $overwrite Should the file be overwritten if it already exists. + * + * @example File::move('/var/www/html/test.txt', '/var/www/html/test2.txt'); // true + * @example File::move('/var/www/html/test.txt', '/var/www/html/test2.txt'); // false + * + * @return bool Returns true on successful file move and false on failure + * + * @throws PathException Throws this exception if the file to move doesn't exist. + * + * @since 1.0.0 + * @author Dennis Eichhorn + */ public static function move(string $from, string $to, bool $overwrite = false) : bool { if (!file_exists($from)) { @@ -277,22 +384,52 @@ class File extends FileAbstract return false; } + /** + * Deletes a file. + * + * @param string $path Path of the file delete. + * + * @return bool Returns true if the file could get deleted false otherwise. + * + * @throws PathException Throws this exception if the file to delete doesn't exist. + * + * @example File::size('/var/www/html/test.txt'); + * + * @since 1.0.0 + * @author Dennis Eichhorn + */ public static function delete(string $path) : bool { if (!file_exists($path)) { - return false; + throw new PathException($path); } unlink($path); - return true; + return !file_exists($path); } + /** + * Gets the directory name of a file. + * + * @return string Returns the directory name of the file. + * + * @since 1.0.0 + * @author Dennis Eichhorn + */ public function getDirName() : string { return basename(dirname($this->path)); } + /** + * Gets the directory path of a file. + * + * @return string Returns the directory path of the file. + * + * @since 1.0.0 + * @author Dennis Eichhorn + */ public function getDirPath() : string { return dirname($this->path); @@ -306,6 +443,20 @@ class File extends FileAbstract return self::create($this->path); } + /** + * Create an empty file. + * + * If the directory doesn't exist where the file should be created it will be created + * as well as potential parent directories. The directories will be created with '0644' + * permission. + * + * @param string $path Path of the file to create. + * + * @return bool Returns true if the file could get created false otherwise or if it already existed. + * + * @since 1.0.0 + * @author Dennis Eichhorn + */ public static function create(string $path) : bool { if (!file_exists($path)) { @@ -315,7 +466,7 @@ class File extends FileAbstract touch($path); - return true; + return file_exists($path); } return false; diff --git a/Utils/StringUtils.php b/Utils/StringUtils.php index 6162d07ba..094fc7a9b 100644 --- a/Utils/StringUtils.php +++ b/Utils/StringUtils.php @@ -16,7 +16,9 @@ namespace phpOMS\Utils; /** - * String utils. + * String utils class. + * + * This class provides static helper functionalities for strings. * * @category Framework * @package phpOMS\Utils @@ -32,6 +34,8 @@ class StringUtils /** * Constructor. * + * This class is purely static and is preventing any initialization + * * @since 1.0.0 * @author Dennis Eichhorn */ @@ -40,12 +44,18 @@ class StringUtils } /** - * Contains any string + * Check if a string contains any of the provided needles. + * + * The validation is done case sensitive. * * @param string $haystack Haystack - * @param array $needles Needles + * @param array $needles Needles to check if any of them are part of the haystack * - * @return bool + * @example StringUtils::contains('This string', ['This', 'test']); // true + * @example StringUtils::contains('This string', 'is st'); // true + * @example StringUtils::contains('This string', 'something'); // false + * + * @return bool The function returns true if any of the needles is part of the haystack, false otherwise. * * @since 1.0.0 * @author Dennis Eichhorn @@ -62,12 +72,19 @@ class StringUtils } /** - * String ends with? + * Tests if a string ends with a certain string. + * + * The validation is done case sensitive. The function takes strings or an array of strings for the validation. + * In case of an array the function will test if any of the needles is at the end of the haystack string. * * @param string $haystack Haystack - * @param string|array $needles Needles + * @param string|array $needles Needles to check if they are at the end of the haystack. * - * @return bool + * @example StringUtils::endsWith('Test string', ['test1', 'string']); // true + * @example StringUtils::endsWith('Test string', 'string'); // true + * @example StringUtils::endsWith('Test string', 'String'); // false + * + * @return bool The function returns true if any of the needles is at the end of the haystack, false otherwise. * * @since 1.0.0 * @author Dennis Eichhorn @@ -88,12 +105,19 @@ class StringUtils } /** - * String starts with? + * Tests if a string starts with a certain string. + * + * The validation is done case sensitive. The function takes strings or an array of strings for the validation. + * In case of an array the function will test if any of the needles is at the beginning of the haystack string. * * @param string $haystack Haystack - * @param string|array $needles Needles + * @param string|array $needles Needles to check if they are at the beginning of the haystack. * - * @return bool + * @example StringUtils::startsWith('Test string', ['Test', 'something']); // true + * @example StringUtils::startsWith('Test string', 'string'); // false + * @example StringUtils::startsWith('Test string', 'Test'); // true + * + * @return bool The function returns true if any of the needles is at the beginning of the haystack, false otherwise. * * @since 1.0.0 * @author Dennis Eichhorn @@ -114,12 +138,15 @@ class StringUtils } /** - * String starts with? + * Tests if a multi byte string starts with a certain string. + * + * The validation is done case sensitive. The function takes strings or an array of strings for the validation. + * In case of an array the function will test if any of the needles is at the beginning of the haystack string. * * @param string $haystack Haystack - * @param string|array $needles Needles + * @param string|array $needles Needles to check if they are at the beginning of the haystack. * - * @return bool + * @return bool The function returns true if any of the needles is at the beginning of the haystack, false otherwise. * * @since 1.0.0 * @author Dennis Eichhorn @@ -140,12 +167,19 @@ class StringUtils } /** - * String ends with? + * Tests if a multi byte string ends with a certain string. + * + * The validation is done case sensitive. The function takes strings or an array of strings for the validation. + * In case of an array the function will test if any of the needles is at the end of the haystack string. * * @param string $haystack Haystack - * @param string|array $needles Needles + * @param string|array $needles Needles to check if they are at the end of the haystack. * - * @return bool + * @example StringUtils::endsWith('Test string', ['test1', 'string']); // true + * @example StringUtils::endsWith('Test string', 'string'); // true + * @example StringUtils::endsWith('Test string', String); // false + * + * @return bool The function returns true if any of the needles is at the end of the haystack, false otherwise. * * @since 1.0.0 * @author Dennis Eichhorn @@ -166,11 +200,11 @@ class StringUtils } /** - * Uppercase first letter. + * Makes first letter of a multi byte string upper case. * - * @param string $string String to manipulate + * @param string $string String to upper case first letter. * - * @return string + * @return string Multi byte string with first character as upper case. * * @since 1.0.0 * @author Dennis Eichhorn @@ -185,11 +219,11 @@ class StringUtils } /** - * Lowercase first letter. + * Makes first letter of a multi byte string lower case. * - * @param string $string String to manipulate + * @param string $string String to lower case first letter. * - * @return string + * @return string Multi byte string with first character as lower case. * * @since 1.0.0 * @author Dennis Eichhorn @@ -204,12 +238,12 @@ class StringUtils } /** - * Trim string. + * Trim multi byte characters from a multi byte string. * - * @param string $string String to manipulate - * @param string $charlist String to trim + * @param string $string Multi byte string to trim multi byte characters from. + * @param string $charlist Multi byte character list used for trimming * - * @return string + * @return string Trimmed multi byte string. * * @since 1.0.0 * @author Dennis Eichhorn @@ -226,12 +260,12 @@ class StringUtils } /** - * Trim right part of string. + * Trim multi byte characters from the right of a multi byte string. * - * @param string $string String to manipulate - * @param string $charlist String to trim + * @param string $string Multi byte string to trim multi byte characters from. + * @param string $charlist Multi byte character list used for trimming * - * @return string + * @return string Trimmed multi byte string. * * @since 1.0.0 * @author Dennis Eichhorn @@ -248,12 +282,12 @@ class StringUtils } /** - * Trim left part of string. + * Trim multi byte characters from the left of a multi byte string. * - * @param string $string String to manipulate - * @param string $charlist String to trim + * @param string $string Multi byte string to trim multi byte characters from. + * @param string $charlist Multi byte character list used for trimming * - * @return string + * @return string Trimmed multi byte string. * * @since 1.0.0 * @author Dennis Eichhorn @@ -270,12 +304,15 @@ class StringUtils } /** - * Count occurences of character at the beginning of string. + * Count occurences of character at the beginning of a string. * - * @param string $string String to manipulate - * @param string $character Character to count + * @param string $string String to analyze. + * @param string $character Character to count at the beginning of the string. * - * @return int + * @example StringUtils::countCharacterFromStart(' Test string', ' '); // 4 + * @example StringUtils::countCharacterFromStart(' Test string', 's'); // 0 + * + * @return int The amount of repeating occurences at the beginning of the string. * * @since 1.0.0 * @author Dennis Eichhorn diff --git a/Validation/Base/CreditCard.php b/Validation/Base/CreditCard.php index c56719861..7cfc93047 100644 --- a/Validation/Base/CreditCard.php +++ b/Validation/Base/CreditCard.php @@ -72,7 +72,17 @@ abstract class CreditCard extends ValidatorAbstract return ($total % 10 == 0) ? true : false; } - public static function luhnTest(string $num) + /** + * Luhn algorithm or mod 10 algorithm is used to verify credit cards. + * + * @param string $num Credit card number. + * + * @return bool Returns true if the number is a valid credit card and false if it isn't. + * + * @since 1.0.0 + * @author Dennis Eichhorn + */ + public static function luhnTest(string $num) : bool { $len = strlen($num); $sum = 0;