chore: add better doc

README.md

@@ -16,51 +16,94 @@ composer require rancoud/security
 
 ## How to use it?
 ```php
-Security::escAttr('string');
+use Rancoud\Security\Security;
 
-Security::escHTML('string');
+// When you want to escape text for HTML output.
+echo '<p>' . Security::escHTML('<script>alert("test");</script>') . '</p>' . "\n";
+// -> <p>&lt;script&gt;alert(&quot;test&quot;);&lt;&#47;script&gt;</p>
 
-Security::escJS('string');
+// When you want to escape text for HTML attribute output.
+echo '<div data-attr="' . Security::escAttr('my-data"><script>alert("test");</script><div hidden="') . '">' . "\n";
+// -> <div data-attr="my-data&quot;&gt;&lt;script&gt;alert&#x28;&quot;test&quot;&#x29;&#x3B;&lt;&#x2F;script&gt;&lt;div&#x20;hidden&#x3D;&quot;"></div>
 
-Security::escURL('string');
+// When you want to escape text for JS output.
+echo 'const value = "' . Security::escJS('";alert("test");let a="') . '";' . "\n";
+// -> const value = "\x22\x3Balert\x28\x22test\x22\x29\x3Blet\x20a\x3D\x22";
 
-Security::escCSS('string');
+// When you want to escape text for URL output.
+echo Security::escURL('https://example.com') . "\n";
+// -> https%3A%2F%2Fexample.com
 
-Security::isSupportedCharset('string');
+// When you want to escape text for CSS output.
+echo 'body {background-color: ' . Security::escCSS('red;} body {background-image: url("https://example.com");') . '}' . "\n";
+// -> body {background-color: red\3B \7D \20 body\20 \7B background\2D image\3A \20 url\28 \22 https\3A \2F \2F example\2E com\22 \29 \3B }
+
+// Checks if charset is supported.
+Security::isSupportedCharset('ISO-8859-15');
+// -> true
+Security::isSupportedCharset('foo');
+// -> false
+```
+
+## Security
+### Main functions
+Escapes text for HTML output.
+```php
+public static function escHTML($text, string $charset = 'UTF-8'): string
+```
+
+Escapes text for HTML attribute output.
+```php
+public static function escAttr($text, string $charset = 'UTF-8'): string
+```
+
+Escapes text for JS output.
+```php
+public static function escJS($text, string $charset = 'UTF-8'): string
+```
+
+Escapes text for URL output.
+```php
+public static function escURL($text, string $charset = 'UTF-8'): string
+```
+
+Escapes text for CSS output.
+```php
+public static function escCSS($text, string $charset = 'UTF-8'): string
+```
+
+Checks if charset is supported.
+```php
+public static function isSupportedCharset(string $charset): bool
 ```
 
 ## Supported Charsets
-Charsets supported are only charsets shortlisted (see list below) which are also supported by mbstring extension.    
-[More info at PHP documentation](https://www.php.net/manual/en/mbstring.encodings.php)  
-[And at the PHP libmbfl README](https://github.com/php/php-src/tree/master/ext/mbstring/libmbfl)  
+Charsets supported are only charsets shortlisted (see list below) which are also supported by mbstring extension.  
+[More info at PHP documentation](https://www.php.net/manual/en/mbstring.encodings.php) [and at the PHP libmbfl README](https://github.com/php/php-src/tree/master/ext/mbstring/libmbfl)
 
-Charsets shortlisted:  
+Charsets shortlisted:
+* BIG5
+* BIG5-HKSCS
+* CP866
+* CP932
+* CP1251
+* CP1252
+* EUC-JP
+* eucJP-win
+* GB2312
 * ISO-8859-1
 * ISO-8859-5
 * ISO-8859-15
-* UTF-8
-* cp866
-* cp1251
-* cp1252
 * KOI8-R
-* BIG5
-* GB2312
-* BIG5-HKSCS
-* Shift_JIS
-* EUC-JP
 * MacRoman
-
-## Security Methods
-### General Static Methods
-* isSupportedCharset(charset: string): bool
-* areCharsetAliases(charsetToCheck: string, charsetReference: string): bool
-* escHTML(text: mixed, [charset: string = 'UTF-8']): string
-* escAttr(text: mixed, [charset: string = 'UTF-8']): string
-* escJS(text: mixed, [charset: string = 'UTF-8']): string
-* escURL(text: mixed, [charset: string = 'UTF-8']): string
-* escCSS(text: mixed, [charset: string = 'UTF-8']): string
+* Shift_JIS
+* SJIS
+* SJIS-win
+* UTF-8
+* Windows-1251
+* Windows-1252
 
 ## How to Dev
 `composer ci` for php-cs-fixer and phpunit and coverage  
 `composer lint` for php-cs-fixer  
-`composer test` for phpunit and coverage  
+`composer test` for phpunit and coverage

src/Security.php

@@ -10,24 +10,50 @@
 class Security
 {
     /**
-     * Array of charsets supported by PHP. It will be generated when first used.
+     * Array of supported charsets by PHP.<br>
+     * It will be populate on the first usage.
      *
      * @var array|null
      */
     protected static ?array $supportedCharsets = null;
 
     /**
+     * Populate supported charsets.<br>
+     * It will keep only supported encodings and aliases that are in the shortlist
+     * and available on the current PHP installation.<br>
+     * Current shortlist are:
+     * - BIG5
+     * - BIG5-HKSCS
+     * - CP866
+     * - CP932
+     * - CP1251
+     * - CP1252
+     * - EUC-JP
+     * - eucJP-win
+     * - GB2312
+     * - ISO-8859-1
+     * - ISO-8859-5
+     * - ISO-8859-15
+     * - KOI8-R
+     * - MacRoman
+     * - Shift_JIS
+     * - SJIS
+     * - SJIS-win
+     * - UTF-8
+     * - Windows-1251
+     * - Windows-1252.
+     *
      * @return array
      */
     protected static function generateSupportedCharsets(): array
     {
-        $maxSupportedCharsets = [
+        $shortlistSupportedCharsets = [
             'ISO-8859-1', 'ISO-8859-5', 'ISO-8859-15', 'UTF-8', 'CP866', 'CP1251', 'Windows-1251', 'CP1252',
             'Windows-1252', 'KOI8-R', 'BIG5', 'GB2312', 'BIG5-HKSCS', 'Shift_JIS', 'SJIS', 'SJIS-win', 'EUC-JP',
             'eucJP-win', 'CP932', 'MacRoman'
         ];
 
-        $charsets = \array_intersect(\mb_list_encodings(), $maxSupportedCharsets);
+        $charsets = \array_intersect(\mb_list_encodings(), $shortlistSupportedCharsets);
 
         $callbackAliases = static function (string $charset) {
             return \mb_encoding_aliases($charset);
@@ -39,6 +65,8 @@ protected static function generateSupportedCharsets(): array
     }
 
     /**
+     * Checks if charset is supported.
+     *
      * @param string $charset
      *
      * @return bool
@@ -63,6 +91,8 @@ public static function isSupportedCharset(string $charset): bool
     }
 
     /**
+     * Throws Security Exception if charset is not supported.
+     *
      * @param string $charset
      *
      * @throws SecurityException
@@ -75,6 +105,8 @@ protected static function throwExceptionIfCharsetIsUnsupported(string $charset):
     }
 
     /**
+     * Converts string from any charset to UTF-8.
+     *
      * @param mixed  $string
      * @param string $charset
      *
@@ -108,6 +140,8 @@ protected static function convertStringToUTF8($string, string $charset = 'UTF-8'
     }
 
     /**
+     * Converts string from UTF-8 to any charset.
+     *
      * @param mixed  $string
      * @param string $charset
      *
@@ -125,6 +159,8 @@ protected static function convertStringFromUTF8($string, string $charset = 'UTF-
     }
 
     /**
+     * Escapes text for HTML output.
+     *
      * @param mixed  $text
      * @param string $charset
      *
@@ -143,6 +179,8 @@ public static function escHTML($text, string $charset = 'UTF-8'): string
     }
 
     /**
+     * Escapes text for HTML attribute output.
+     *
      * @param mixed  $text
      * @param string $charset
      *
@@ -187,6 +225,8 @@ public static function escAttr($text, string $charset = 'UTF-8'): string
     }
 
     /**
+     * Escapes text for JS output.
+     *
      * @param mixed  $text
      * @param string $charset
      *
@@ -235,6 +275,8 @@ public static function escJS($text, string $charset = 'UTF-8'): string
     }
 
     /**
+     * Escapes text for URL output.
+     *
      * @param mixed  $text
      * @param string $charset
      *
@@ -252,6 +294,8 @@ public static function escURL($text, string $charset = 'UTF-8'): string
     }
 
     /**
+     * Escapes text for CSS output.
+     *
      * @param mixed  $text
      * @param string $charset
      *