+ Either CASE_UPPER or + CASE_LOWER (default)
(int) +### Method arraySearchField() It returns the first (or all) key(s) inside an array/object in an array that matches the value of the field), 1=javascript console, 2=table (use future) (int) +* **$returnValue** param bool $returnValue (bool) -### isUpper +### Method WriteLog() +Write a log file. If the file is over 10mb then the file is resetted.
+``` +DebugLib::WriteLog('somefile.txt','warning','it is a warning'); +DebugLib::WriteLog('somefile.txt','it is a warning'); +``` +#### Parameters: +* **$logFile** The file to write (string) +* **$level** The level of the message, example "error", "info", 1, etc. (mixed) +* **$txt** if txt is empty then level is defined as warning and level is used for the description (string|object|array) -> isUpper($str) +## TextLib +Class TextLib +### Method isUpper() Returns true if the str is (completelly) uppercase +#### Parameters: +* **$str** Input text (string) -### isLower - -> isLower($str) - +### Method isLower() Returns true if the str is (completelly) lowercase +#### Parameters: +* **$str** param $str () -### stripQuotes - -> stripQuotes($text) - -Strip quotes of a text (" or ') - -Example: -```php +### Method between() +Obtain a string between one text and other. +**Example:** +``` +TextLib::between('Hello Brave World','Hello','World'); // returns " Brave " +TextLib::between('mary has a lamb','has','lamb') // returns ' a ' +``` +#### Parameters: +* **$haystack** param string $haystack (string) +* **$startNeedle** The initial text to search
+ if empty then it starts at the start of the haystack. (string) +* **$endNeedle** The end tag to search
+ if empty then it ends at the end of the haystack (string) +* **$offset** param null|int $offset (null|int) +* **$ignoreCase** param bool $ignoreCase (bool) + +### Method stripQuotes() +Strip quotes of a text " or ' if the value in between quotes
+If the value is not quoted then it is not touched.
+If the value is not correctly closed ("hello or "hello' ), then the quota is not removed.
+The value is trimmed ' "hello world"' --> 'hello world'
+**Example:** +``` TextLib::stripQuotes('"hello world"'); // returns hello world ``` +#### Parameters: +* **$text** param $text () -* If the value is not quoted then it is not touched. -* If the value is not correctly closed ("hello or "hello' ), then the quota is not removed. -* The value is trimmed ' "hello world"' --> 'hello world' - -### between - -> between($haystack, $startNeedle, $endNeedle,&$offset=0, $ignoreCase=false) - -Returns the text between two needles. - -> TextLib::between('Hello Brave World','Hello','World') // returns " Brave " - -### replaceBetween - -> replaceBetween($haystack, $startNeedle, $endneedle, $replaceText, &$offset=0,$$replaceTag=false) - -Replace the text between two needles -* If $replaceTag is true then it also replaces the $startNeedle and $endneedle - -> TextLib::replaceBetween('Hello Brave World','Hello','World',' Wayne ') // returns "Hello Wayne World" - - - -### removeFirstChars - -> removeFirstChars($txt,$length=1) - -Remove the first character(s) for a string - -> TextLib::removeFirstChars('Hello') // returns "ello" - -### removeLastChars - -> removeLastChars($txt,$length=1) - -Remove the last character(s) for a string - -> TextLib::removeLastChars('Hello') // returns "Hell" - -### parseArg - -It transforms a text = 'a1=1,a2=2' into an associative array. -It uses the method parse_str() to do the conversion +### Method removeParenthesis() +Remove the initial and final parenthesis but only if both matches.
+If the $start and $end are arrays then both must have the same count and arrays are compared by pair of index
+**Example:** +``` +TextLib::removeParenthesis('hello'); // return "hello"; +TextLib::removeParenthesis('(hello)'); // return "hello"; +TextLib::removeParenthesis('[hello]' +,['(','{','['] +,[')','}',']']); // returns "hello" +TextLib::removeParenthesis("'hello'" +,"'" +,"'"); // returns "hello" +``` +#### Parameters: +* **$txt** Input value. Example "hello", "(hello)" (string) +* **$start** the open parenthesis, by default it's '('. (string|array) +* **$end** the close parenthesis, by default it's ')'. (string|array) + +### Method replaceBetween() +Replace the text between two needles
+**Example:** +``` +TextLib::replaceBetween('Hello Brave World','Hello','World',' Wayne ') // returns "Hello Wayne World" +``` +#### Parameters: +* **$haystack** the input value (string) +* **$startNeedle** The initial text to search
+ if empty then it starts at the start of the haystack. (string) +* **$endNeedle** The end tag to search
+ if empty then it ends at the end of the haystack (string) +* **$replaceText** Text to replace (string) +* **$offset** the offset position to start the search. (null|int) +* **$replaceTag** If true then it also replaces the tags (bool) + +### Method removeFirstChars() +Remove the first character(s) for a string
+**Example:** +``` +TextLib::removeFirstChars('Hello') // returns "ello" +``` +#### Parameters: +* **$str** The input text (string) +* **$length** The amount of characters to remove (default 1) (int) -> parseArg($text, $separator = ',') +### Method removeLastChars() +Remove the last character(s) for a string
+**Example:** +``` +TextLib::removeLastChars('Hello') // returns "Hell" +``` +#### Parameters: +* **$str** The input text (string) +* **$length** The amount of characters to remove (default 1) (int) -```php -TextLib::parseArg('a=1,b=1'); -// returns ['a'=>'1','b'=>'1'] +### Method getArgument() +It separates an argument from the value to the set value.
+Returns an array with the name of the argument and value (if any). It always returns a two dimension array +**Example:** +``` +self::getArgument("arg=200"); // returns ["arg","200"] +self::getArgument("arg:200",':'); // returns ["arg","200"] +``` +#### Parameters: +* **$str** The input text (string) +* **$set** The separator of operator (string) +* **$trimValue** param bool $trimValue (bool) + +### Method strPosNotSpace() +It returns the first non-space position inside a string. +**Example:** +``` +TextLib::strPosNotSpace(' abc def'); // returns 3 +``` +#### Parameters: +* **$str** input string (string) +* **$offset** offset position (int) +* **$charlist** list of characters considered as space (string) + +### Method strposArray() +It finds the first (or last) ocurrence of a text.
+Unlikely strpos(), this method allows finding more than one neddle.
+**Example:** ``` +TextLib::strposArray('a,b.d.e,f.g',['x','t','.']); // return 3 +TextLib::strposArray('a,b.d.e,f.g',['x','t',','],0,true); // return 7 +``` +#### Parameters: +* **$haystack** the input value (string) +* **$needles** the value (or values) to find (string|array) +* **$offset** the offset position (initially it's 0) (int) +* **$last** if false (default) it returns the first ocurrence. If true returns the last one (bool) + +### Method parseArg() +It transforms a text = 'a1=1,a2=2' into an associative array
+It uses the method parse_str() to do the conversion
+**Note:** It doesn't work with quotes or double quotes. a1="aa,bb",bb=30 doesn't work +**Example:** +``` +TextLib::parseArg('a=1,b=1'); // returns ['a'=>'1','b'=>'1'] +``` +#### Parameters: +* **$text** The input string with the initial values (string) +* **$separator** The separator (string) -### naturalArg +### Method parseArg2() +It's the same than parseArg() but it's x3 times slower.
+It also considers quotes and doubles quotes.
+Example: +``` +TextLib::parseArg2("a1=1,a2=2,a3="aa,bb"); // ["a1"=>1,"a2"=>2,"a3"=>""aa,bb""] +TextLib::parseArg("a1=1,a2=2,a3="aa,bb"); // ["a1"=>1,"a2"=>2,"a3"=>""aa","bb""=>""] +``` +#### Parameters: +* **$text** The input string with the initial values (string) +* **$separator** The separator. It does not separates text inside quotes or double-quotes. (string) -It parses a natural string and returns a declarative array. +### Method naturalArg() +It parses a natural string and returns a declarative array
A "natural string", it is a set of values or arguments separated by space , where a value is the index and the new one is the value of the index. - -> naturalArg($text, $separator = ',') - -* $text the input expression -* $separator is an associative array where the key is the key of the - end result, and the value of each key is - * first = first value. This value is the first of the string expression - * req = required value. If the value is missing then it returns null - * opt = optional value. If the value is missing then the field returns null - -```php +``` TextLib::naturalArg('select * from table where 1=1' - ,['select'=>'req','from'=>'req','where'=>'opt']); +,['select'=>'req','from'=>'req','where'=>'opt']); // returns ['select'=>'*','from'=>'table','where'=>'1=1'] - TextLib::naturalArg('item export table inport file' - ,['item'=>'first','export'=>'opt','inport'=>'opt']); +,['item'=>'first','export'=>'opt','inport'=>'opt']); // returns: ['item' => 'item', 'export' => 'table', 'inport' => 'file'] ``` - -### camelCase - -Retains the case of the text minus the first letter that it's converted in lowercase. - -Example: -```php -TextLib::camelCase('HelloWorld'); -// return "helloWorld"; -TextLib::camelCase('hello_world'); -// return "helloWorld"; - +#### Parameters: +* **$txt** the input value. Example "somevalue TYPE int LENGHT 30" (string) +* **$separators** the indicator for each field.
+ first = indicates the first element (optional)
+ opt = indicates the field is optional
+ req = indicates the field is required
(array) + +### Method str_replace_ex() +It works as str_replace, but it also allows to limit the number of replacements. +#### Parameters: +* **$search** param string $search (string) +* **$replace** param string $replace (string) +* **$subject** param string $subject (string) +* **$limit** param int $limit (int) + +### Method wildCardComparison() +It compares with wildcards (*) and returns true if both strings are equals
+The wildcards only works at the beginning or at the end of the string.
+Example:
``` - -### strposArray - -It finds the first (or last) ocurrence of a text. -Unlikely strpos(), this method allows to find more than one neddle. - -> function strposArray($haystack, $needles,$offset=0,$last=false) - -Example: -```php -TextLib::strposArray('a,b.d.e,f.g',['x','t','.']); -// return 3 -TextLib::strposArray('a,b.d.e,f.g',['x','t',','],0,true); -// return 7 +TextLib::wildCardComparison('abcdef','abc*'); // true +TextLib::wildCardComparison('abcdef','*def'); // true +TextLib::wildCardComparison('abcdef','*abc*'); // true +TextLib::wildCardComparison('abcdef','*cde*'); // true +TextLib::wildCardComparison('abcdef','*cde'); // false ``` +#### Parameters: +* **$text** param string $text (string) +* **$textWithWildcard** param string|null $textWithWildcard (string|null) -### removeParenthesis - -Remove the initial and final parenthesis but only if both matches. -If the **$start** and **$end** arguments are arrays then both must have the same count and arrays are compared by pair of index - -Example: -```php -TextLib::removeParenthesis('hello'); -// return "hello"; -TextLib::removeParenthesis('(hello)'); -// return "hello"; -TextLib::removeParenthesis('[hello]' - ,['(','{','['] - ,[')','}',']']); -// returns "hello" -TextLib::removeParenthesis("'hello'" - ,"'" - ,"'"); -// returns "hello" +### Method endsWith() +it returns true if $string ends with $endString
+Example:
``` - -### hasParenthesis - -Returns true if it has both parenthesis. - - -Example: -```php -TextLib::hasParenthesis('hello'); -// return false; -TextLib::hasParenthesis('(hello)'); -// return true; +TextLib::endsWidth('hello world','world'); // true ``` - - -### addParenthesis - -It adds parenthesis only if the original input does not have it. - -Example: -```php -TextLib::addParenthesis('hello'); -// return '(hello)'; -TextLib::addParenthesis('(hello)'); -// return '(hello)'; +#### Parameters: +* **$string** param $string () +* **$endString** param $endString () + +### Method replaceCurlyVariable() +Replaces all variables defined between {{ }} by a variable inside the dictionary of values.
+Example:
+replaceCurlyVariable('hello={{var}}',['var'=>'world']) // hello=world
+replaceCurlyVariable('hello={{var}}',['varx'=>'world']) // hello=
+replaceCurlyVariable('hello={{var}}',['varx'=>'world'],true) // hello={{var}}
+#### Parameters: +* **$string** The input value. It could contain variables defined as {{namevar}} (string) +* **$values** The dictionary of values. (array) +* **$notFoundThenKeep** [false] If true and the value is not found, then it keeps the value. + Otherwise, it is replaced by an empty value (bool) + +### Method addParenthesis() +It adds a parenthesis (or other symbol) at the start and end of the text. +If it already has it, then it is not added.
+**Example:** +``` +TextLib::addParenthesis('hello'); // return '(hello)'; +TextLib::addParenthesis('(hello)');// return '(hello)'; ``` +#### Parameters: +* **$txt** Input value. Example "hello", "(hello)" (string) +* **$start** the open parenthesis, by default it's '('. (string|array) +* **$end** the close parenthesis, by default it's ')'. (string|array) + +### Method hasParenthesis() +It returns true if the text has an open and ending parenthesis (or other symbol).
+**Example:** +``` +TextLib::hasParenthesis('hello'); // return false; +TextLib::hasParenthesis('(hello)'); // return true; +``` +#### Parameters: +* **$txt** Input value. Example "hello", "(hello)" (string) +* **$start** the open parenthesis, by default it's '('. (string|array) +* **$end** the close parenthesis, by default it's ')'. (string|array) + +### Method camelCase() +Retains the case minus the first letter that it's converted in lowercase
+If the text contains the characters "_" or " ", then the next character is uppercase
+If the text does not contain any character "_" or " ", then only the first character is replaced. +**Example:** +``` +TextLib::camelCase('HelloWorld'); // return "helloWorld"; +TextLib::camelCase('hello_world'); // return "helloWorld"; +``` +#### Parameters: +* **$txt** input value (string) + ## FileLib -> Todo: missing documentation, check the phpdoc for more information. +Class Files
+This class has a collection of functions to interact with files and directories. +### Field lastError () + + +### Method getDirFiles() +It gets the content (files) of a directory. It does not include other directories. +#### Parameters: +* **$dir** The directory to scan. (string) +* **$extensions** The extension to find (without dot). ['*'] means any extension. (array) +* **$recursive** if true (default), then it scans the folders recursively. (bool) + +### Method getDirFirstFile() +It returns the first file (exclude directories) find in a directory that matches a specific extension(s)
+The order of the extensions could count.
+If there are two files with the same extension, then it returns the first one. +#### Parameters: +* **$dir** The directory to scan. (string) +* **$extensions** The extension to find (without dot). ['*'] means any extension. (array) +* **$sort** (default false), if true then it sorts the list previous the filter. (bool) +* **$descending** (default false), if true then it sorts (if enable) descending. (bool) + +### Method getDirFolders() +It gets the content (folders) of a directory without trailing slash. It does not include files. +#### Parameters: +* **$dir** The directory to scan. (string) +* **$recursive** if true (default), then it scans the folders recursively. (bool) + +### Method getExtensionPath() +It gets the extension of a file (without dot). If the file has no extension then it returns empty. +#### Parameters: +* **$fullPath** the path to analize. (string) + +### Method getFileNamePath() +It gets the filename (without extension and directory) +#### Parameters: +* **$fullPath** the path to analize. (string) + +### Method getBaseNamePath() +It gets the base name (filename with extension). It does not include the directory. +#### Parameters: +* **$fullPath** the path to analize. (string) + +### Method getDirPath() +It gets the dir from a full path (without trailing slash) +#### Parameters: +* **$fullPath** the path to analize. (string) + +### Method fixUrlSeparator() +It fixes the path by converting the slash and inverse lash into the system folder separator +#### Parameters: +* **$fullPath** the path to analize. (string) + +### Method safeFileGetContent() +It gets the content of a file. It never throws an exception
+In case of error, it returns the default value +#### Parameters: +* **$filename** The filename to open. (string) +* **$use_include_path** used to trigger include path search. (bool) +* **$context** A valid context resource created with (null) +* **$offset** The offset where the reading starts. (int) +* **$length** Maximum length of data read. The default is to read until end + of file is reached. (int|null) +* **$default** The value to return if it is unable to open the file (null|mixed) + +### Method safeFilePutContent() +Write a string to a file. This operator is safe, it never throws an exception. +#### Parameters: +* **$filename** Path to the file where to write the data. (string) +* **$data** The data to write. Can be either a string, an array or a stream resource. (mixed) +* **$flag** The value of flags can be any combination of the following flags, with some + restrictions, joined with the binary OR (|) operator. (int) +* **$context** A valid context resource created with stream_context_create. (mixed) +* **$tries** The number of tries (default 3). Every try has a delay of 300ms. (int) + +### Method isAbsolutePath() +Returns true if the path is absolute, otherwise it returns false.
+This function works in Linux and Windows (and most probably in other UNIX OS) +#### Parameters: +* **$fullPath** The path to analize. (string) ## Version list +* 1.24 + * Fixed an exception with FileLib. It also stores every error in a field. + * Completed README.md + * Cleaned PHPDocs. * 1.23 Modified .gitattributes and .gitignore to streamline the final version. * 1.22 The next classes have been renamed: * Text (deprecated) => TextLib diff --git a/lib/CollectionLib.php b/lib/CollectionLib.php index 54776ad..fc1bfdc 100644 --- a/lib/CollectionLib.php +++ b/lib/CollectionLib.php @@ -12,7 +12,7 @@ * Class CollectionLib * * @package mapache_commons - * @version 1.23 2024-08-12 + * @version 1.24 2024-08-24 * @copyright Jorge Castro Castillo * @license Apache-2.0 * @see https://github.com/EFTEC/mapache-commons @@ -20,20 +20,33 @@ class CollectionLib { /** - * Returns true if array is an associative array, false is it's an indexed array + * Returns true if array is an associative array, false is it's an indexed array
+ * **Example:** + * ``` + * $isAssoc=CollectionLib::isAssoc($array); // slow, more precise. + * $isAssoc=CollectionLib::isAssoc($array,true); // fast, less precise + * ``` * * @param array $array input array + * @param bool $fast (default false), if true then it checks if the index 0 exists, and it is the first index.
+ * if false, then it checks every value comparing the indexed array with an associative array. * * @return bool * @see https://stackoverflow.com/questions/173400/how-to-check-if-php-array-is-associative-or-sequential */ - public static function isAssoc($array): bool + public static function isAssoc(array $array,bool $fast=false): bool { + if($fast){ + return !(isset($array[0]) && array_key_first($array) ===0); + } return (array_values($array) !== $array); } + /** - * Returns the first element of an array. + * Returns the first element of an array.
+ * Sometimes the first element is not the index [0], for example ['key1'=>1,0=2] where the first element is 'key1' and not 0. + * This function always returns the right value. * * @param array $array input array * @@ -161,14 +174,16 @@ public static function generateTable($array, $css = true): string } /** - * Split a string using an opening and closing tag.
+ * Split a string using an opening and closing tag, by default "(" and ")".
* Example:
- * Collection::splitOpeningClosing("a(B,C,D)e(F,G,H)"); // ['a','B,C,D','e','F,G,H']
- * Collection::splitOpeningClosing("a(B,C,D)e(F,G,H)i"); // ['a','B,C,D','e','F,G,H','i']
+ * ``` + * CollectionLib::splitOpeningClosing("a(B,C,D)e(F,G,H)"); // ['a','B,C,D','e','F,G,H'] + * CollectionLib::splitOpeningClosing("a(B,C,D)e(F,G,H)i"); // ['a','B,C,D','e','F,G,H','i'] + * ``` * * @param string $text input text to separated - * @param string $openingTag Opening tag - * @param string $closingTag closing tag + * @param string $openingTag Opening tag, default "(" + * @param string $closingTag closing tag, default ")" * @param int $startPosition start position (by default it is zero) * @param bool $excludeEmpty if true then it excludes all empty values. * @param bool $includeTag if true then it includes the tag. @@ -227,7 +242,9 @@ public static function splitOpeningClosing( /** * Split a string by ignoring parts of string where values are between " or '.
* Example:
- * Collection::splitNotString('a,b,"CC,D,E",e,f' ,","); // ['a','b','CC,D,E','e','f']
+ * ``` + * CollectionLib::splitNotString('a,b,"CC,D,E",e,f' ,","); // ['a','b','CC,D,E','e','f'] + * ``` * * @param string $text input text * @param string $separator @@ -292,8 +309,16 @@ public static function splitNotString($text, $separator, $offset = 0, $excludeEm } /** - * It changes the case (to lower or upper case) of the keys of an array recursively - * + * It changes the case (to lower or upper case) of the keys of an array recursively
+ * **Example:** + * ``` + * $arr=['A'=>'a','b'=>'b']; + * CollectionLib::arrayChangeKeyCaseRecursive($arr); + * // returns ['a'=>'a','b'=>'b'] + * CollectionLib::arrayChangeKeyCaseRecursive($arr,true); + * // returns ['A'=>'a','B'=>'b'] + * ``` + * * @param array $array input array * * @param int $case [optional] by default is CASE_LOWER@@ -315,7 +340,13 @@ public static function arrayChangeKeyCaseRecursive($array, $case = CASE_LOWER): /** * It returns the first (or all) key(s) inside an array/object in an array that matches the value of the field
- * Example: arraySearchField([['name'=>'john'],['name'=>'mary']],'name','mary'); // returns 1 + * **Example:** + * ``` + * $array=[['name'=>'john'],['name'=>'mary']]; + * CollectionLib::arraySearchField($array,'name','mary'); // 1 + * CollectionLib::arraySearchField([(object)['name'=>'john'],(object)['name'=>'mary']],'name','mary'); // 1 + * CollectionLib::arraySearchField([['name'=>'john'],['name'=>'mary'],['name'=>'mary']],'name','mary',true); // returns [1,2] + * ``` * * @param array $array input array * @param string|int $fieldName name of index of the field @@ -365,9 +396,9 @@ public static function arraySearchField($array, $fieldName, $value, $returnAll = /** * It converts a xml (SimpleXMLElement object) into a string
- **Example:** - * ```php - * $string=Collection::xmlToString($xml,true); // "... " + * **Example:** + * ``` + * $string=CollectionLib::xmlToString($xml,true); // "... " * ``` * @param SimpleXMLElement $xml * @param bool $format if true then the result is formatted. @@ -388,8 +419,8 @@ public static function xmlToString(SimpleXMLElement $xml,$format=true): string /** * It convers an array into a xml (SimpleXMLElement object) * **Example:** - * ```php - * $xml=Collection::arrayToXML($array,'root'); //... + * ``` + * $xml=CollectionLib::arrayToXML($array,'root'); //... * ``` * @param array $data * @param string $rootName The name of the root tag (default root) @@ -464,8 +495,8 @@ protected static function arrayToXMLInt(SimpleXMLElement $object, array $data, /** * It converts a string into a xml (SimpleXMLElement object) using simplexml_load_string including a fix
* **Example:** - * ```php - * $xml=Collection::stringToXML(''); + * ``` + * $xml=CollectionLib::stringToXML(' - a
- b
'); * ``` * * @param string $string the value to convert @@ -483,7 +514,11 @@ public static function stringToXML(string $string,$className=null,int $options=0 } /** - * It converts a xml (SimpleXMLElement object) into an array. + * It converts an XML class (SimpleXMLElement object) into an array. + * **Example:** + * ``` + * $array=CollectionLib::xmlToArray($xml); + * ``` * @param SimpleXMLElement $xml * @return array|null * @throws JsonException @@ -493,4 +528,4 @@ public static function xmlToArray(SimpleXMLElement $xml): ?array return json_decode(json_encode($xml, JSON_THROW_ON_ERROR), TRUE, 512, JSON_THROW_ON_ERROR); } -} \ No newline at end of file +} diff --git a/lib/DebugLib.php b/lib/DebugLib.php index e568c7e..a2096e7 100644 --- a/lib/DebugLib.php +++ b/lib/DebugLib.php @@ -16,13 +16,18 @@ * Class Debug * * @package mapache_commons - * @version 1.23 2024-08-12 + * @version 1.24 2024-08-24 * @copyright Jorge Castro Castillo * @license Apache-2.0 * @see https://github.com/EFTEC/mapache-commons */ class DebugLib { /** + * Alternative to var_dump. It "pre" the result or it shows the result in the console of javascript. - a
- b
+ * **Example:** + * ``` + * DebugLib::var_dump($value,true); // returns a var_dump visible via the console of javascript (browser) + * ``` * @param $value * @param int $type : 0=normal (), 1=javascript console, 2=table (use future) * @param bool $returnValue @@ -55,18 +60,17 @@ public static function var_dump($value, $type = 1, $returnValue = false) { /** * Write a log file. If the file is over 10mb then the file is resetted.
- *+ * ``` * DebugLib::WriteLog('somefile.txt','warning','it is a warning'); * DebugLib::WriteLog('somefile.txt','it is a warning'); - *+ * ``` * - * @param mixed $logFile - * @param mixed $level + * @param string $logFile The file to write + * @param mixed $level The level of the message, example "error", "info", 1, etc. * @param string|object|array $txt if txt is empty then level is defined as warning and level is used for the description - * * @return bool */ - public static function WriteLog($logFile, $level, $txt = '') { + public static function WriteLog(string $logFile, $level, $txt = '') { /** @noinspection TypeUnsafeComparisonInspection */ if ($logFile == '') { return false; diff --git a/lib/FileLib.php b/lib/FileLib.php index 6b6079f..26a072c 100644 --- a/lib/FileLib.php +++ b/lib/FileLib.php @@ -9,13 +9,17 @@ * This class has a collection of functions to interact with files and directories. * * @package mapache_commons - * @version 1.23 2024-08-12 + * @version 1.24 2024-08-24 * @copyright Jorge Castro Castillo * @license Apache-2.0 * @see https://github.com/EFTEC/mapache-commons */ class FileLib { + /** + * @var string|null It stores the last error. This value is nulled every time the operation is called. + */ + public static ?string $lastError = null; /** * It gets the content (files) of a directory. It does not include other directories. * @param string $dir The directory to scan. @@ -41,7 +45,12 @@ public static function getDirFiles(string $dir, array $extensions = ['*'], bool */ public static function getDirFirstFile(string $dir, array $extensions = ['*'],bool $sort=false,$descending=false): ?string { + self::$lastError=null; $files = scandir($dir); + if($files===false) { + self::$lastError = "Can't read directory '$dir'."; + return null; + } if($sort) { $files=natcasesort($files); } @@ -64,7 +73,12 @@ public static function getDirFirstFile(string $dir, array $extensions = ['*'],bo protected static function _getDirFiles(string $dir, array &$results = [], array $extensions = ['*'], bool $recursive = true): array { + self::$lastError=null; $files = scandir($dir); + if($files===false) { + self::$lastError = "Can't read directory '$dir'."; + return []; + } foreach ($files as $value) { $fullName = realpath($dir . DIRECTORY_SEPARATOR . $value); $extension = self::getExtensionPath($fullName); @@ -101,7 +115,12 @@ public static function getDirFolders(string $dir, bool $recursive = true): array protected static function _getDirFolders(string $dir, array &$results = [], bool $recursive = true): array { - $files = scandir($dir); + self::$lastError=null; + $files =@scandir($dir); + if($files===false) { + self::$lastError = "Can't read directory '$dir'."; + return []; + } foreach ($files as $value) { $fullName = realpath($dir . DIRECTORY_SEPARATOR . $value); if ($value !== "." && $value !== ".." && is_dir($fullName)) { @@ -179,12 +198,17 @@ public static function fixUrlSeparator(string $fullPath): string public static function safeFileGetContent(string $filename, bool $use_include_path = false, $context = null, int $offset = 0, ?int $length = null, $default = null) { + static::$lastError = null; try { $content = $length === null ? - file_get_contents($filename, $use_include_path, $context, $offset) : - file_get_contents($filename, $use_include_path, $context, $offset, $length); + @file_get_contents($filename, $use_include_path, $context, $offset) : + @file_get_contents($filename, $use_include_path, $context, $offset, $length); $content = $content === false ? $default : $content; + if($content===false) { + static::$lastError="unable to get content file $filename"; + } } catch (Throwable $e) { + static::$lastError = $e->getMessage(); $content = $default; } return $content; @@ -203,16 +227,21 @@ public static function safeFileGetContent(string $filename, bool $use_include_pa public static function safeFilePutContent(string $filename, $data = "", int $flag = 0, $context = null, int $tries = 3): bool { + self::$lastError=null; + $msg=null; for ($try = 0; $try < $tries; $try++) { try { - $result = file_put_contents($filename, $data, $flag, $context); + $result = @file_put_contents($filename, $data, $flag, $context); if ($result !== false) { + return true; } } catch (Throwable $e) { + $msg=$e->getMessage(); } usleep(300); } + self::$lastError = $msg; return false; } @@ -228,4 +257,4 @@ public static function isAbsolutePath(string $fullPath): bool { } return ($fullPath !== '' && $fullPath[0]==='/'); // example: /path1 } -} \ No newline at end of file +} diff --git a/lib/TextLib.php b/lib/TextLib.php index 05f2343..a4d76a3 100644 --- a/lib/TextLib.php +++ b/lib/TextLib.php @@ -3,23 +3,20 @@ /** @noinspection GrazieInspection */ /** @noinspection PhpMissingReturnTypeInspection */ /** @noinspection PhpMissingParamTypeInspection */ - /** @noinspection ReturnTypeCanBeDeclaredInspection */ namespace mapache_commons; - /** * Class TextLib * * @package mapache_commons - * @version 1.23 2024-08-12 + * @version 1.24 2024-08-24 * @copyright Jorge Castro Castillo * @license Apache-2.0 * @see https://github.com/EFTEC/mapache-commons */ class TextLib { - /** * Returns true if the str is (completelly) uppercase * @@ -28,7 +25,8 @@ class TextLib * @return bool true if the text is uppercase, otherwise false * @see https://stackoverflow.com/questions/4211875/check-if-a-string-is-all-caps-in-php */ - public static function isUpper($str) { + public static function isUpper($str) + { return strtoupper($str) == $str; } @@ -40,14 +38,18 @@ public static function isUpper($str) { * @return bool * @see https://stackoverflow.com/questions/25340288/php-function-to-check-string-if-is-all-lowercase */ - public static function isLower($str) { + public static function isLower($str) + { return strtolower($str) == $str; } /** * Obtain a string between one text and other. - * Example: between('mary has a lamb','has','lamb') // returns ' a ' - * + * **Example:** + * ``` + * TextLib::between('Hello Brave World','Hello','World'); // returns " Brave " + * TextLib::between('mary has a lamb','has','lamb') // returns ' a ' + * ``` * @param string $haystack * @param string $startNeedle The initial text to search
* if empty then it starts at the start of the haystack. @@ -58,7 +60,8 @@ public static function isLower($str) { * * @return bool|string */ - public static function between($haystack, $startNeedle, $endNeedle, &$offset = 0, $ignoreCase = false) { + public static function between($haystack, $startNeedle, $endNeedle, &$offset = 0, $ignoreCase = false) + { if ($startNeedle === '') { $ini = 0; } else { @@ -83,19 +86,38 @@ public static function between($haystack, $startNeedle, $endNeedle, &$offset = 0 } /** - * Strip quotes of a text " or ' - * + * Strip quotes of a text " or ' if the value in between quotes
+ * If the value is not quoted then it is not touched.
+ * If the value is not correctly closed ("hello or "hello' ), then the quota is not removed.
+ * The value is trimmed ' "hello world"' --> 'hello world'
+ * **Example:** + * ``` + * TextLib::stripQuotes('"hello world"'); + * // returns hello world + * ``` * @param $text * * @return bool|string */ - public static function stripQuotes($text) { + public static function stripQuotes($text) + { return self::removeParenthesis($text, ['"', "'"], ['"', "'"]); } /** * Remove the initial and final parenthesis but only if both matches.
- * If the $start and $end are arrays then both must have the same count and arrays are compared by pair of index + * If the $start and $end are arrays then both must have the same count and arrays are compared by pair of index
+ * **Example:** + * ``` + * TextLib::removeParenthesis('hello'); // return "hello"; + * TextLib::removeParenthesis('(hello)'); // return "hello"; + * TextLib::removeParenthesis('[hello]' + * ,['(','{','['] + * ,[')','}',']']); // returns "hello" + * TextLib::removeParenthesis("'hello'" + * ,"'" + * ,"'"); // returns "hello" + * ``` * * @param string $txt Input value. Example "hello", "(hello)" * @param string|array $start the open parenthesis, by default it's '('. @@ -103,7 +125,8 @@ public static function stripQuotes($text) { * * @return bool|string The string processed of false if error. */ - public static function removeParenthesis($txt, $start = '(', $end = ')') { + public static function removeParenthesis($txt, $start = '(', $end = ')') + { if ($txt == "") { return $txt; } @@ -123,8 +146,11 @@ public static function removeParenthesis($txt, $start = '(', $end = ')') { } /** - * Replace the text between two needles - * + * Replace the text between two needles
+ * **Example:** + * ``` + * TextLib::replaceBetween('Hello Brave World','Hello','World',' Wayne ') // returns "Hello Wayne World" + * ``` * @param string $haystack the input value * @param string $startNeedle The initial text to search
* if empty then it starts at the start of the haystack. @@ -143,7 +169,8 @@ public static function replaceBetween( $replaceText, &$offset = 0, $replaceTag = false - ) { + ) + { $ini = ($startNeedle === '') ? 0 : strpos($haystack, $startNeedle, $offset); if ($ini === false) { return false; @@ -156,9 +183,7 @@ public static function replaceBetween( $len = $p1 + strlen($endNeedle) - $ini; $offset = $ini + $len; return substr_replace($haystack, $replaceText, $ini, $len); - } - $ini += strlen($startNeedle); $len = $p1 - $ini; $offset = $ini + $len; @@ -166,33 +191,47 @@ public static function replaceBetween( } /** - * Remove the first character(s) for a string + * Remove the first character(s) for a string
+ * **Example:** + * ``` + * TextLib::removeFirstChars('Hello') // returns "ello" + * ``` * * @param string $str The input text - * @param int $length The amount of characters to remove + * @param int $length The amount of characters to remove (default 1) * * @return bool|string */ - public static function removeFirstChars($str, $length = 1) { + public static function removeFirstChars($str, $length = 1) + { return substr($str, $length); } /** - * Remove the last character(s) for a string + * Remove the last character(s) for a string
+ * **Example:** + * ``` + * TextLib::removeLastChars('Hello') // returns "Hell" + * ``` * * @param string $str The input text - * @param int $length The amount of characters to remove + * @param int $length The amount of characters to remove (default 1) * * @return bool|string */ - public static function removeLastChars($str, $length = 1) { + public static function removeLastChars($str, $length = 1) + { return substr($str, 0, -$length); } /** - * It separates an argument from the value to the set value. - * Example self::getArgument("arg=200") returns ["arg","200"] - * Example self::getArgument("arg:200",':') returns ["arg","200"] + * It separates an argument from the value to the set value.
+ * Returns an array with the name of the argument and value (if any). It always returns a two dimension array + * **Example:** + * ``` + * self::getArgument("arg=200"); // returns ["arg","200"] + * self::getArgument("arg:200",':'); // returns ["arg","200"] + * ``` * * @param string $str The input text * @param string $set The separator of operator @@ -200,7 +239,8 @@ public static function removeLastChars($str, $length = 1) { * * @return array it always returns a two-dimensional array. It could return [null,null] or ['arg',null] */ - public static function getArgument($str, $set = '=', $trimValue = true) { + public static function getArgument($str, $set = '=', $trimValue = true) + { if (empty($str)) { return [null, null]; } @@ -212,27 +252,35 @@ public static function getArgument($str, $set = '=', $trimValue = true) { if ($trimValue && $parts[1]) { $parts[1] = trim($parts[1]); } - return $parts; } /** * It returns the first non-space position inside a string. - * + * **Example:** + * ``` + * TextLib::strPosNotSpace(' abc def'); // returns 3 + * ``` * @param string $str input string * @param int $offset offset position * @param string $charlist list of characters considered as space * * @return int the position of the first non-space */ - public static function strPosNotSpace($str, $offset = 0, $charlist = " \t\n\r\0\x0B") { + public static function strPosNotSpace($str, $offset = 0, $charlist = " \t\n\r\0\x0B") + { $txtTmp = substr($str, 0, $offset) . ltrim(substr($str, $offset), $charlist); return strlen($str) - strlen($txtTmp) + $offset; } /** * It finds the first (or last) ocurrence of a text.
- * Unlikely strpos(), this method allows finding more than one neddle. + * Unlikely strpos(), this method allows finding more than one neddle.
+ * **Example:** + * ``` + * TextLib::strposArray('a,b.d.e,f.g',['x','t','.']); // return 3 + * TextLib::strposArray('a,b.d.e,f.g',['x','t',','],0,true); // return 7 + * ``` * * @param string $haystack the input value * @param string|array $needles the value (or values) to find @@ -241,7 +289,8 @@ public static function strPosNotSpace($str, $offset = 0, $charlist = " \t\n\r\0\ * * @return bool|int if not found then it returns false */ - public static function strposArray($haystack, $needles, $offset = 0, $last = false) { + public static function strposArray($haystack, $needles, $offset = 0, $last = false) + { $min = strlen($haystack); if (is_array($needles)) { foreach ($needles as $str) { @@ -263,14 +312,19 @@ public static function strposArray($haystack, $needles, $offset = 0, $last = fal /** * It transforms a text = 'a1=1,a2=2' into an associative array
* It uses the method parse_str() to do the conversion
- * Note: It doesn't work with quotes or double quotes. a1="aa,bb",bb=30 doesn't work + * **Note:** It doesn't work with quotes or double quotes. a1="aa,bb",bb=30 doesn't work + * **Example:** + * ``` + * TextLib::parseArg('a=1,b=1'); // returns ['a'=>'1','b'=>'1'] + * ``` * * @param string $text The input string with the initial values * @param string $separator The separator * * @return array An associative array */ - public static function parseArg($text, $separator = ',') { + public static function parseArg($text, $separator = ',') + { $tmpToken = '¶|¶'; $output = []; if ($separator === '&') { @@ -289,7 +343,7 @@ public static function parseArg($text, $separator = ',') { * It's the same than parseArg() but it's x3 times slower.
* It also considers quotes and doubles quotes.
* Example: - * ```php + * ``` * TextLib::parseArg2("a1=1,a2=2,a3="aa,bb"); // ["a1"=>1,"a2"=>2,"a3"=>""aa,bb""] * TextLib::parseArg("a1=1,a2=2,a3="aa,bb"); // ["a1"=>1,"a2"=>2,"a3"=>""aa","bb""=>""] * ``` @@ -299,8 +353,8 @@ public static function parseArg($text, $separator = ',') { * * @return array An associative array */ - public static function parseArg2($text, $separator = ',') { - + public static function parseArg2($text, $separator = ',') + { $chars = str_split($text); $parts = []; $nextpart = ""; @@ -336,11 +390,16 @@ public static function parseArg2($text, $separator = ',') { /** * It parses a natural string and returns a declarative array
- * Example: natural("v1 obj obj1 type type1"
- * ,['item'=>'first','obj'=>'opt','type'=>'req']) - * returns ['item'=>v1,'obj'=>'obj1','type'=>'type1']
- * example natural("select * from table where condition" - * ,['select'=>'req','from'=>'req','where'=>'opt']); + * A "natural string", it is a set of values or arguments separated by space + * , where a value is the index and the new one is the value of the index. + * ``` + * TextLib::naturalArg('select * from table where 1=1' + * ,['select'=>'req','from'=>'req','where'=>'opt']); + * // returns ['select'=>'*','from'=>'table','where'=>'1=1'] + * TextLib::naturalArg('item export table inport file' + * ,['item'=>'first','export'=>'opt','inport'=>'opt']); + * // returns: ['item' => 'item', 'export' => 'table', 'inport' => 'file'] + * ``` * * @param string $txt the input value. Example "somevalue TYPE int LENGHT 30" * @param array $separators the indicator for each field.
@@ -350,11 +409,12 @@ public static function parseArg2($text, $separator = ',') { * * @return array|null It returns an associative array or null if the operation fails. */ - public static function naturalArg($txt, $separators) { + public static function naturalArg($txt, $separators) + { $keySeparator = array_keys($separators); $result = array_flip($keySeparator); $firstKey = array_search('first', $separators, true); - foreach ($result as $k=>$v) { + foreach ($result as $k => $v) { $result[$k] = null; } if (!$txt) { @@ -390,19 +450,20 @@ public static function naturalArg($txt, $separators) { * @param string $search * @param string $replace * @param string $subject - * @param int $limit + * @param int $limit * * @return string */ - public static function str_replace_ex($search, $replace, $subject,$limit=99999) { - return implode($replace, explode($search, $subject, $limit+1)); + public static function str_replace_ex($search, $replace, $subject, $limit = 99999) + { + return implode($replace, explode($search, $subject, $limit + 1)); } /** * It compares with wildcards (*) and returns true if both strings are equals
* The wildcards only works at the beginning or at the end of the string.
* Example:
- * ```php + * ``` * TextLib::wildCardComparison('abcdef','abc*'); // true * TextLib::wildCardComparison('abcdef','*def'); // true * TextLib::wildCardComparison('abcdef','*abc*'); // true @@ -411,45 +472,45 @@ public static function str_replace_ex($search, $replace, $subject,$limit=99999) * * ``` * - * @param string $text + * @param string $text * @param string|null $textWithWildcard * * @return bool */ - public static function wildCardComparison($text,$textWithWildcard) { - if(($textWithWildcard===null || $textWithWildcard==='') - || strpos($textWithWildcard,'*')===false) { + public static function wildCardComparison($text, $textWithWildcard) + { + if (($textWithWildcard === null || $textWithWildcard === '') + || strpos($textWithWildcard, '*') === false) { // if the text with wildcard is null or empty, or it contains two ** or it contains no * then.. - return $text==$textWithWildcard; + return $text == $textWithWildcard; } if ($textWithWildcard === '*' || $textWithWildcard === '**') { return true; } - $c0=$textWithWildcard[0]; - $c1=substr($textWithWildcard, -1); - $textWithWildcardClean=str_replace('*','',$textWithWildcard); - $p0=strpos($text,$textWithWildcardClean); - if($p0===false) { + $c0 = $textWithWildcard[0]; + $c1 = substr($textWithWildcard, -1); + $textWithWildcardClean = str_replace('*', '', $textWithWildcard); + $p0 = strpos($text, $textWithWildcardClean); + if ($p0 === false) { // no matches. return false; } - if($c0==='*' && $c1==='*') { + if ($c0 === '*' && $c1 === '*') { // $textWithWildcard='*asasasas*' return true; } - if($c1==='*') { + if ($c1 === '*') { // $textWithWildcard='asasasas*' - return $p0===0; + return $p0 === 0; } // $textWithWildcard='*asasasas' - return static::endsWith($text,$textWithWildcardClean); - + return static::endsWith($text, $textWithWildcardClean); } /** * it returns true if $string ends with $endString
* Example:
- * ```php + * ``` * TextLib::endsWidth('hello world','world'); // true * ``` * @@ -481,11 +542,12 @@ public static function endsWith($string, $endString) * * @return string|string[]|null */ - public static function replaceCurlyVariable($string, $values, $notFoundThenKeep = false) { + public static function replaceCurlyVariable($string, $values, $notFoundThenKeep = false) + { if (strpos($string, '{{') === false) { return $string; } // nothing to replace. - return preg_replace_callback('/{{\s?(\w+)\s?}}/u', static function ($matches) use ($values, $notFoundThenKeep) { + return preg_replace_callback('/{{\s?(\w+)\s?}}/u', static function($matches) use ($values, $notFoundThenKeep) { if (is_array($matches)) { $item = substr($matches[0], 2, -2); // removes {{ and }} /** @noinspection NestedTernaryOperatorInspection */ @@ -493,15 +555,19 @@ public static function replaceCurlyVariable($string, $values, $notFoundThenKeep /** @noinspection PhpIssetCanBeReplacedWithCoalesceInspection */ return isset($values[$item]) ? $values[$item] : ($notFoundThenKeep ? $matches[0] : ''); } - $item = substr($matches, 2, -2); // removes {{ and }} - return $values[$item] ?? $notFoundThenKeep ? $matches : ''; }, $string); } /** - * It adds a parenthesis (or other symbol) at the start and end of the text. If it already has it, then it is not added. + * It adds a parenthesis (or other symbol) at the start and end of the text. + * If it already has it, then it is not added.
+ * **Example:** + * ``` + * TextLib::addParenthesis('hello'); // return '(hello)'; + * TextLib::addParenthesis('(hello)');// return '(hello)'; + * ``` * * @param string $txt Input value. Example "hello", "(hello)" * @param string|array $start the open parenthesis, by default it's '('. @@ -509,7 +575,8 @@ public static function replaceCurlyVariable($string, $values, $notFoundThenKeep * * @return string */ - public static function addParenthesis($txt, $start = '(', $end = ')') { + public static function addParenthesis($txt, $start = '(', $end = ')') + { if (self::hasParenthesis($txt, $start, $end) === false) { return $start . $txt . $end; } @@ -517,7 +584,12 @@ public static function addParenthesis($txt, $start = '(', $end = ')') { } /** - * It returns true if the text has an open and ending parenthesis (or other symbol). + * It returns true if the text has an open and ending parenthesis (or other symbol).
+ * **Example:** + * ``` + * TextLib::hasParenthesis('hello'); // return false; + * TextLib::hasParenthesis('(hello)'); // return true; + * ``` * * @param string $txt Input value. Example "hello", "(hello)" * @param string|array $start the open parenthesis, by default it's '('. @@ -525,7 +597,8 @@ public static function addParenthesis($txt, $start = '(', $end = ')') { * * @return bool */ - public static function hasParenthesis($txt, $start = '(', $end = ')') { + public static function hasParenthesis($txt, $start = '(', $end = ')') + { if ($txt == "") { return false; } @@ -548,16 +621,20 @@ public static function hasParenthesis($txt, $start = '(', $end = ')') { * Retains the case minus the first letter that it's converted in lowercase
* If the text contains the characters "_" or " ", then the next character is uppercase
* If the text does not contain any character "_" or " ", then only the first character is replaced. - * + * **Example:** + * ``` + * TextLib::camelCase('HelloWorld'); // return "helloWorld"; + * TextLib::camelCase('hello_world'); // return "helloWorld"; + * ``` * @param string $txt input value * * @return string */ - public static function camelCase($txt) { + public static function camelCase($txt) + { if ($txt === null || $txt === '') { return $txt; } - if (strpos($txt, '_') || strpos($txt, ' ')) { $txt = strtolower($txt); $result = ''; @@ -577,8 +654,7 @@ public static function camelCase($txt) { } return $result; } - -// the text is simple. + // the text is simple. return strtolower($txt[0]) . substr($txt, 1); } } diff --git a/test/CollectionTest.php b/test/CollectionTest.php index 034a769..d7bc221 100644 --- a/test/CollectionTest.php +++ b/test/CollectionTest.php @@ -66,8 +66,8 @@ public function testXML2(): void $this->assertInstanceOf('SimpleXMLElement',$xmlBack); $this->assertEquals(''."\n".''."\n",$stringBack); } - public function testsplitOpeningClosing() - { + public function testsplitOpeningClosing(): void + { $this->assertEquals(['a','B-C-D','e','F-G-H'] , CollectionLib::splitOpeningClosing("a(B-C-D)e(F-G-H)")); $this->assertEquals(['a','B,C,D','e','F,G,H'] @@ -93,8 +93,8 @@ public function testsplitOpeningClosing() $this->assertEquals([1,2] ,CollectionLib::arraySearchField([['name'=>'john'],['name'=>'mary'],['name'=>'mary']],'name','mary',true)); } - public function testsplitNotString() - { + public function testsplitNotString(): void + { $this->assertEquals(['a' , 'b' , 'CC,D,E' , 'e' , 'f'] , CollectionLib::splitNotString('a,b,"CC,D,E",e,f',",")); @@ -102,11 +102,15 @@ public function testsplitNotString() , CollectionLib::splitNotString('a b "CC D E" e f'," ",0,false)); } - public function testisAssoc() { + public function testisAssoc(): void + { $this->assertEquals(false,CollectionLib::isAssoc(['a','b'])); + $this->assertEquals(false,CollectionLib::isAssoc(['a','b'],true)); $this->assertEquals(true,CollectionLib::isAssoc(['a'=>'a','b'=>'b'])); + $this->assertEquals(true,CollectionLib::isAssoc(['a'=>'a','b'=>'b'],true)); } - public function testarrayChangeKeyCaseRecursive() { + public function testarrayChangeKeyCaseRecursive(): void + { $arr=['A'=>'a','b'=>'b']; $this->assertEquals(['a'=>'a','b'=>'b'],CollectionLib::arrayChangeKeyCaseRecursive($arr)); $this->assertEquals(['A'=>'a','B'=>'b'],CollectionLib::arrayChangeKeyCaseRecursive($arr,CASE_UPPER)); - a
- b