From fca7325990a1f3beb1a7ac7cdca1a2c2116381fd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Rancoud?=
 <rancoud@users.noreply.github.com>
Date: Tue, 1 Apr 2025 00:35:52 +0200
Subject: [PATCH 1/4] chore: add better doc

---
 README.md        | 97 +++++++++++++++++++++++++++++++++---------------
 src/Security.php | 50 +++++++++++++++++++++++--
 2 files changed, 114 insertions(+), 33 deletions(-)

diff --git a/README.md b/README.md
index 153247f..cdd4b2c 100644
--- a/README.md
+++ b/README.md
@@ -16,51 +16,88 @@ composer require rancoud/security
 
 ## How to use it?
 ```php
-Security::escAttr('string');
+use Rancoud\Security\Security;
 
-Security::escHTML('string');
+// When you want to escape string for HTML output.
+echo '<p>' . Security::escHTML('<script>alert("test");</script>') . '<p>';
+// -> <p>&lt;script&gt;alert(&quot;test&quot;);&lt;&#47;script&gt;<p>
 
-Security::escJS('string');
+// When you want to escape string for HTML attribute output.
+echo '<div data-attr="' . Security::escAttr('my-data"><script>alert("test");</script><div hidden="') . '">;
+// -> <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 string for JS output.
+echo 'const value = "' . Security::escJS('";alert("test");let a="') . '";';
+// -> const value = "\x22\x3Balert\x28\x22test\x22\x29\x3Blet\x20a\x3D\x22";
 
-Security::escCSS('string');
+// When you want to escape string for URL output.
+echo Security::escURL('https://example.com');
+// -> https%3A%2F%2Fexample.com
 
-Security::isSupportedCharset('string');
+// When you want to escape string for CSS output.
+echo 'body { background-color: ' . Security::escCSS('red;} body {background-image: url("https://example.com");') . '}';echo "\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 }
+```
+
+## Security
+### Main functions
+Escapes string for HTML output.
+```php
+public static function escHTML($text, string $charset = 'UTF-8'): string
+```
+
+Escapes string for HTML attribute output.
+```php
+public static function escAttr($text, string $charset = 'UTF-8'): string
+```
+
+Escapes string for JS output.
+```php
+public static function escJS($text, string $charset = 'UTF-8'): string
+```
+
+Escapes string for URL output.
+```php
+public static function escURL($text, string $charset = 'UTF-8'): string
+```
+
+Escapes string 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
diff --git a/src/Security.php b/src/Security.php
index a49e084..123292b 100644
--- a/src/Security.php
+++ b/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 string for HTML output.
+     *
      * @param mixed  $text
      * @param string $charset
      *
@@ -143,6 +179,8 @@ public static function escHTML($text, string $charset = 'UTF-8'): string
     }
 
     /**
+     * Escapes string 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 string for JS output.
+     *
      * @param mixed  $text
      * @param string $charset
      *
@@ -235,6 +275,8 @@ public static function escJS($text, string $charset = 'UTF-8'): string
     }
 
     /**
+     * Escapes string for URL output.
+     *
      * @param mixed  $text
      * @param string $charset
      *
@@ -252,6 +294,8 @@ public static function escURL($text, string $charset = 'UTF-8'): string
     }
 
     /**
+     * Escapes string for CSS output.
+     *
      * @param mixed  $text
      * @param string $charset
      *

From 45552bda4a78e836c31d4fe5d1749cf633259a22 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Rancoud?=
 <rancoud@users.noreply.github.com>
Date: Tue, 1 Apr 2025 00:42:46 +0200
Subject: [PATCH 2/4] typo

---
 README.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index cdd4b2c..43c6a31 100644
--- a/README.md
+++ b/README.md
@@ -23,7 +23,7 @@ echo '<p>' . Security::escHTML('<script>alert("test");</script>') . '<p>';
 // -> <p>&lt;script&gt;alert(&quot;test&quot;);&lt;&#47;script&gt;<p>
 
 // When you want to escape string for HTML attribute output.
-echo '<div data-attr="' . Security::escAttr('my-data"><script>alert("test");</script><div hidden="') . '">;
+echo '<div data-attr="' . Security::escAttr('my-data"><script>alert("test");</script><div hidden="') . '">';
 // -> <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>
 
 // When you want to escape string for JS output.
@@ -37,6 +37,12 @@ echo Security::escURL('https://example.com');
 // When you want to escape string for CSS output.
 echo 'body { background-color: ' . Security::escCSS('red;} body {background-image: url("https://example.com");') . '}';echo "\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.
+echo Security::isSupportedCharset('ISO-8859-15');
+// -> true
+echo Security::isSupportedCharset('foo');
+// -> false
 ```
 
 ## Security

From 2254bb826fb8a7731094dfcbace51eb02263581e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Rancoud?=
 <rancoud@users.noreply.github.com>
Date: Tue, 1 Apr 2025 00:49:49 +0200
Subject: [PATCH 3/4] typo

---
 README.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 43c6a31..94d6c6b 100644
--- a/README.md
+++ b/README.md
@@ -19,29 +19,29 @@ composer require rancoud/security
 use Rancoud\Security\Security;
 
 // When you want to escape string for HTML output.
-echo '<p>' . Security::escHTML('<script>alert("test");</script>') . '<p>';
-// -> <p>&lt;script&gt;alert(&quot;test&quot;);&lt;&#47;script&gt;<p>
+echo '<p>' . Security::escHTML('<script>alert("test");</script>') . '</p>' . "\n";
+// -> <p>&lt;script&gt;alert(&quot;test&quot;);&lt;&#47;script&gt;</p>
 
 // When you want to escape string for HTML attribute output.
-echo '<div data-attr="' . Security::escAttr('my-data"><script>alert("test");</script><div hidden="') . '">';
+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>
 
 // When you want to escape string for JS output.
-echo 'const value = "' . Security::escJS('";alert("test");let a="') . '";';
+echo 'const value = "' . Security::escJS('";alert("test");let a="') . '";' . "\n";
 // -> const value = "\x22\x3Balert\x28\x22test\x22\x29\x3Blet\x20a\x3D\x22";
 
 // When you want to escape string for URL output.
-echo Security::escURL('https://example.com');
+echo Security::escURL('https://example.com') . "\n";
 // -> https%3A%2F%2Fexample.com
 
 // When you want to escape string for CSS output.
-echo 'body { background-color: ' . Security::escCSS('red;} body {background-image: url("https://example.com");') . '}';echo "\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 }
+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.
-echo Security::isSupportedCharset('ISO-8859-15');
+Security::isSupportedCharset('ISO-8859-15');
 // -> true
-echo Security::isSupportedCharset('foo');
+Security::isSupportedCharset('foo');
 // -> false
 ```
 

From df6a667c2413c8b2484f3146b94113d8f4f6d514 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Rancoud?=
 <rancoud@users.noreply.github.com>
Date: Tue, 1 Apr 2025 00:52:22 +0200
Subject: [PATCH 4/4] typo

---
 README.md        | 20 ++++++++++----------
 src/Security.php | 10 +++++-----
 2 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 94d6c6b..286f96c 100644
--- a/README.md
+++ b/README.md
@@ -18,23 +18,23 @@ composer require rancoud/security
 ```php
 use Rancoud\Security\Security;
 
-// When you want to escape string for HTML output.
+// 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>
 
-// When you want to escape string for HTML attribute output.
+// 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>
 
-// When you want to escape string for JS output.
+// 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";
 
-// When you want to escape string for URL output.
+// When you want to escape text for URL output.
 echo Security::escURL('https://example.com') . "\n";
 // -> https%3A%2F%2Fexample.com
 
-// When you want to escape string for CSS output.
+// 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 }
 
@@ -47,27 +47,27 @@ Security::isSupportedCharset('foo');
 
 ## Security
 ### Main functions
-Escapes string for HTML output.
+Escapes text for HTML output.
 ```php
 public static function escHTML($text, string $charset = 'UTF-8'): string
 ```
 
-Escapes string for HTML attribute output.
+Escapes text for HTML attribute output.
 ```php
 public static function escAttr($text, string $charset = 'UTF-8'): string
 ```
 
-Escapes string for JS output.
+Escapes text for JS output.
 ```php
 public static function escJS($text, string $charset = 'UTF-8'): string
 ```
 
-Escapes string for URL output.
+Escapes text for URL output.
 ```php
 public static function escURL($text, string $charset = 'UTF-8'): string
 ```
 
-Escapes string for CSS output.
+Escapes text for CSS output.
 ```php
 public static function escCSS($text, string $charset = 'UTF-8'): string
 ```
diff --git a/src/Security.php b/src/Security.php
index 123292b..e92f301 100644
--- a/src/Security.php
+++ b/src/Security.php
@@ -159,7 +159,7 @@ protected static function convertStringFromUTF8($string, string $charset = 'UTF-
     }
 
     /**
-     * Escapes string for HTML output.
+     * Escapes text for HTML output.
      *
      * @param mixed  $text
      * @param string $charset
@@ -179,7 +179,7 @@ public static function escHTML($text, string $charset = 'UTF-8'): string
     }
 
     /**
-     * Escapes string for HTML attribute output.
+     * Escapes text for HTML attribute output.
      *
      * @param mixed  $text
      * @param string $charset
@@ -225,7 +225,7 @@ public static function escAttr($text, string $charset = 'UTF-8'): string
     }
 
     /**
-     * Escapes string for JS output.
+     * Escapes text for JS output.
      *
      * @param mixed  $text
      * @param string $charset
@@ -275,7 +275,7 @@ public static function escJS($text, string $charset = 'UTF-8'): string
     }
 
     /**
-     * Escapes string for URL output.
+     * Escapes text for URL output.
      *
      * @param mixed  $text
      * @param string $charset
@@ -294,7 +294,7 @@ public static function escURL($text, string $charset = 'UTF-8'): string
     }
 
     /**
-     * Escapes string for CSS output.
+     * Escapes text for CSS output.
      *
      * @param mixed  $text
      * @param string $charset