feat: add more morphers (#5)

- maskBrReal
- ltrim
- rtrim
- toUpperFirst
- replaceRegex
- reverse
- limit
- normalize

Author: viniciusvts

docs/docs/methods/a-lot-of-manipulators.md

@@ -34,6 +34,44 @@ $string = SM::make($string)
 echo $string; // Hello world
 ```
 
+## limit
+Limit the string length.
+
+If $end is setted, it will be added at the end of string.
+
+If $length is less than the length of $end, $end will be the new string.
+
+```php
+$string = 'The quick brown fox jumps over the lazy dog';
+$string = SM::limit($string, 30);
+// or
+$string = SM::make($string)
+    ->limit(30);
+echo $string; // The quick brown fox jumps over
+
+//if you use $end
+$string = 'The quick brown fox jumps over the lazy dog';
+$string = SM::limit($string, 30, '[...]');
+// or
+$string = SM::make($string)
+    ->limit(30, '[...]');
+echo $string; // The quick brown fox jumps[...]
+```
+
+## normalize
+Remove all accents and special characters.
+
+Only alphanumeric and spaces are preserved
+
+```php
+$string = 'âäàåçêëèïîìÆôöòûùÿ';
+$string = SM::normalize($string);
+// or
+$string = SM::make($string)
+    ->normalize();
+echo $string; // aaaaceeeiiiooouuy
+```
+
 ## onlyAlpha
 Only keep letters
 
@@ -75,21 +113,44 @@ Replace all occurrences of a string.
 
 ```php
 $string = 'The quick brown fox jumps';
-$string = SM::sub($string, 'fox', 'dog');
+$string = SM::replace($string, 'fox', 'dog');
 // or
 $string = SM::make($string)
-    ->sub('fox', 'dog');
+    ->replace('fox', 'dog');
 echo $string; // The quick brown dog jumps
 
 // case insensitive:
 $string = 'The quick brown Fox jumps';
-$string = SM::sub($string, 'fox', 'Dog', false);
+$string = SM::replace($string, 'fox', 'Dog', false);
 // or
 $string = SM::make($string)
-    ->sub('fox', 'Dog', false);
+    ->replace('fox', 'Dog', false);
 echo $string; // The quick brown Dog jumps
 ```
 
+## replaceRegex
+Replace all occurrences of a regex.
+
+```php
+$string = 'The  quick   brown    fox jumps';
+$string = SM::replaceRegex($string, '/\s+/', ' ');
+// or
+$string = SM::make($string)
+    ->replaceRegex('/\s+/', ' ');
+echo $string; // The quick brown fox jumps
+```
+
+## reverse
+Reverse the string
+
+```php
+$string = 'spmuj xof nworb kciuq ehT';
+$string = SM::reverse($string);
+// or
+$string = SM::make($string)
+    ->reverse();
+echo $string; // The quick brown fox jumps
+```
 
 ## toBase64
 Encode to base64
@@ -127,6 +188,18 @@ $string = SM::make($string)
 echo $string; // HELLO WORLD
 ```
 
+## toUpperFirst
+Morph to upper case the first letter of string.
+
+```php
+$string = 'hello world';
+$string = SM::toUpperFirst($string);
+// or
+$string = SM::make($string)
+    ->toUpperFirst();
+echo $string; // Hello world
+```
+
 ## trim
 Remove all spaces from the start and end.
 
@@ -144,6 +217,40 @@ $string = SM::make($string)
     ->trim(" \n\r\t\v\0");
 ```
 
+## ltrim
+Remove all spaces from the start and end.
+
+```php
+$string = ' Hello world ';
+$string = SM::ltrim($string);
+// or
+$string = SM::make($string)
+    ->ltrim();
+echo $string; // Hello world 
+
+// you can set what caracters you can ltrim
+$string = SM::ltrim($string, " \n\r\t\v\0");
+$string = SM::make($string)
+    ->ltrim(" \n\r\t\v\0");
+```
+
+## rtrim
+Remove all spaces from the start and end.
+
+```php
+$string = ' Hello world ';
+$string = SM::rtrim($string);
+// or
+$string = SM::make($string)
+    ->rtrim();
+echo $string; //  Hello world
+
+// you can set what caracters you can rtrim
+$string = SM::rtrim($string, " \n\r\t\v\0");
+$string = SM::make($string)
+    ->rtrim(" \n\r\t\v\0");
+```
+
 ## withoutSpaces
 Remove all spaces
 

docs/docs/methods/brazilian-maskers.md

@@ -14,34 +14,58 @@ nav_order: 3
 Apply the Brazilian CEP mask
 
 ```php
+$string = '44555666';
 $string = SM::maskBrCep($string);
+// or
 $string = SM::withoutSpaces($string)
     ->maskBrCep();
+echo $string // 44.555-666
 ```
 
 ## maskBrCpf
 Apply the Brazilian CEP mask
 
 ```php
+$string = '11122233344';
 $string = SM::maskBrCpf($string);
+// or
 $string = SM::withoutSpaces($string)
     ->maskBrCpf();
+echo $string // 111.222.333-44
 ```
 
 ## maskBrCnpj
 Apply the Brazilian CNPJ mask
 
 ```php
+$string = '11222333444455';
 $string = SM::maskBrCnpj($string);
+// or
 $string = SM::withoutSpaces($string)
     ->maskBrCnpj();
+echo $string // 11.222.333/4444-55
 ```
 
 ## maskBrPhone
 Apply the Brazilian Phone mask
 
 ```php
+$string = '11988887777';
 $string = SM::maskBrPhone($string);
+// or
 $string = SM::withoutSpaces($string)
     ->maskBrPhone();
+echo $string // (11) 98888-7777
+```
+
+## maskBrReal
+Apply the Brazilian Phone mask
+
+```php
+$string = '1234864.20'; // or float or int
+$string = SM::maskBrReal($string);
+// or
+$string = SM::withoutSpaces($string)
+    ->maskBrReal();
+echo $string // R$ 1.234.864,20
 ```

phpunit.xml

@@ -3,6 +3,7 @@
          xsi:noNamespaceSchemaLocation="./vendor/phpunit/phpunit/phpunit.xsd"
          bootstrap="vendor/autoload.php"
          colors="true"
+         displayDetailsOnTestsThatTriggerDeprecations="true"
          processIsolation="false"
          stopOnError="false"
          stopOnFailure="false"

src/Manipulators/Manipulator.php

@@ -27,6 +27,57 @@ public function fromBase64()
         return $this;
     }
 
+    /**
+     * Limit the string length.
+     * If $end is setted, it will be added at the end.
+     * If $length is less than the length of $end, $end will be the new string.
+     * @param integer $length The maximum length.
+     * @param string|null $end The string to be added at the end.
+     * @return $this
+     */
+    public function limit(int $length, string|null $end = null)
+    {
+        if (strlen($this->string) <= $length) {
+            return $this;
+        }
+        $endLength = !is_null($end) ? strlen($end) : 0;
+        $finalLength = ($length - $endLength < 0) ? 0 : $length - $endLength;
+        $this->string = $endLength > 0 ?
+            substr($this->string, 0, $finalLength) . $end :
+            substr($this->string, 0, $finalLength);
+
+        return $this;
+    }
+
+    /**
+     * Remove all accents and special characters.
+     * Only alphanumeric and spaces are preserved
+     * @return $this
+     */
+    public function normalize()
+    {
+        $transliteration = [
+            'á' => 'a', 'à' => 'a', 'â' => 'a', 'ã' => 'a', 'ä' => 'a', 'å' => 'a',
+            'ç' => 'c',
+            'é' => 'e', 'è' => 'e', 'ê' => 'e', 'ë' => 'e',
+            'í' => 'i', 'ì' => 'i', 'î' => 'i', 'ï' => 'i',
+            'ó' => 'o', 'ò' => 'o', 'ô' => 'o', 'õ' => 'o', 'ö' => 'o', 'ð' => 'o',
+            'ú' => 'u', 'ù' => 'u', 'û' => 'u', 'ü' => 'u',
+            'ñ' => 'n', 'š' => 's', 'ý' => 'y', 'ÿ' => 'y',
+            'Á' => 'A', 'À' => 'A', 'Â' => 'A', 'Ã' => 'A', 'Ä' => 'A', 'Å' => 'A',
+            'Ç' => 'C',
+            'É' => 'E', 'È' => 'E', 'Ê' => 'E', 'Ë' => 'E',
+            'Í' => 'I', 'Ì' => 'I', 'Î' => 'I', 'Ï' => 'I',
+            'Ó' => 'O', 'Ò' => 'O', 'Ô' => 'O', 'Õ' => 'O', 'Ö' => 'O',
+            'Ú' => 'U', 'Ù' => 'U', 'Û' => 'U', 'Ü' => 'U',
+            'Ñ' => 'N', 'Š' => 'S', 'Ý' => 'Y', 'Ÿ' => 'Y',
+        ];
+        $input = strtr($this->string, $transliteration);
+        $this->string = preg_replace('/[^a-zA-Z0-9\s]/', '', $input);
+
+        return $this;
+    }
+
     /**
      * Remove all characters except letters.
      * @return $this
@@ -67,6 +118,32 @@ public function replace(array|string $needle, array|string $replace, bool $caseS
         return $this;
     }
 
+    /**
+     * Replace all occurrences of a regex.
+     * @see preg_replace()
+     * @param array|string $needleRegex The search string.
+     * @param array|string $replace The replacement string.
+     * @return $this
+     */
+    public function replaceRegex(array|string $needleRegex, array|string $replace)
+    {
+        $this->string = preg_replace($needleRegex, $replace, $this->string);
+
+        return $this;
+    }
+
+    /**
+     * Reverse the string.
+     * @see strrev()
+     * @return $this
+     */
+    public function reverse()
+    {
+        $this->string = strrev($this->string);
+
+        return $this;
+    }
+
     /**
      * Slice the string.
      * @see substr()
@@ -117,6 +194,18 @@ public function toUpper()
         return $this;
     }
 
+    /**
+     * Morph the first caracter to upper case.
+     * @see ucfirst()
+     * @return $this
+     */
+    public function toUpperFirst()
+    {
+        $this->string = ucfirst($this->string);
+
+        return $this;
+    }
+
     /**
      * Remove all spaces from the start and end.
      * @see trim()
@@ -125,7 +214,39 @@ public function toUpper()
      */
     public function trim(string $characters = " \n\r\t\v\0")
     {
-        $this->string = trim($this->string, $characters);
+        $this->string = $characters == null ?
+            trim($this->string) :
+            trim($this->string, $characters);
+
+        return $this;
+    }
+
+    /**
+     * Remove all spaces from the left.
+     * @see ltrim()
+     * @param string $characters The characters to be removed.
+     * @return $this
+     */
+    public function ltrim(string $characters = " \n\r\t\v\0")
+    {
+        $this->string = $characters == null ?
+            ltrim($this->string) :
+            ltrim($this->string, $characters);
+
+        return $this;
+    }
+
+    /**
+     * Remove all spaces from the right.
+     * @see rtrim()
+     * @param string $characters The characters to be removed.
+     * @return $this
+     */
+    public function rtrim(string $characters = " \n\r\t\v\0")
+    {
+        $this->string = $characters == null ?
+            rtrim($this->string) :
+            rtrim($this->string, $characters);
 
         return $this;
     }

src/Maskers/BrazilianMasker.php

@@ -48,4 +48,24 @@ public function maskBrPhone()
 
         return $this;
     }
+
+    /**
+     * Mask to a real currency.
+     * @return $this
+     */
+    public function maskBrReal()
+    {
+        if (empty($this->string)) {
+            return $this;
+        }
+        $aux = $this->string;
+        if (strpos($aux, ',') !== false && strpos($aux, '.') === false) {
+            $aux = str_replace(',', '.', $aux);
+        }
+        $aux = floatval($aux);
+        $aux = number_format($aux, 2, ',', '.');
+        $this->string = 'R$ ' . $aux;
+
+        return $this;
+    }
 }