From 347747f72026e16bc84620e57ef50423db08bb1f Mon Sep 17 00:00:00 2001
From: azjezz <azjezz@protonmail.com>
Date: Fri, 5 Mar 2021 14:20:45 +0100
Subject: [PATCH] [Html] Introduce HTML component

---
 src/Psl/Html/decode.php                       | 28 +++++++++++++++
 src/Psl/Html/decode_special_characters.php    | 21 ++++++++++++
 src/Psl/Html/encode.php                       | 30 ++++++++++++++++
 src/Psl/Html/encode_special_characters.php    | 32 +++++++++++++++++
 src/Psl/Internal/Loader.php                   |  4 +++
 .../Psl/Html/DecodeSpecialCharactersTest.php  | 34 +++++++++++++++++++
 tests/Psl/Html/DecodeTest.php                 | 34 +++++++++++++++++++
 .../Psl/Html/EncodeSpecialCharactersTest.php  | 34 +++++++++++++++++++
 tests/Psl/Html/EncodeTest.php                 | 34 +++++++++++++++++++
 9 files changed, 251 insertions(+)
 create mode 100644 src/Psl/Html/decode.php
 create mode 100644 src/Psl/Html/decode_special_characters.php
 create mode 100644 src/Psl/Html/encode.php
 create mode 100644 src/Psl/Html/encode_special_characters.php
 create mode 100644 tests/Psl/Html/DecodeSpecialCharactersTest.php
 create mode 100644 tests/Psl/Html/DecodeTest.php
 create mode 100644 tests/Psl/Html/EncodeSpecialCharactersTest.php
 create mode 100644 tests/Psl/Html/EncodeTest.php

diff --git a/src/Psl/Html/decode.php b/src/Psl/Html/decode.php
new file mode 100644
index 00000000..6265a8e1
--- /dev/null
+++ b/src/Psl/Html/decode.php
@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Html;
+
+use Psl\Exception;
+use Psl\Internal;
+
+use function html_entity_decode;
+
+use const ENT_QUOTES;
+
+/**
+ * Convert HTML entities to their corresponding characters.
+ *
+ * @param string $encoding defines character set used in conversion.
+ *
+ * @throws Exception\InvariantViolationException If $encoding is invalid.
+ *
+ * @psalm-pure
+ */
+function decode(string $html, ?string $encoding = null): string
+{
+    $encoding = Internal\internal_encoding($encoding);
+
+    return html_entity_decode($html, ENT_QUOTES, $encoding);
+}
diff --git a/src/Psl/Html/decode_special_characters.php b/src/Psl/Html/decode_special_characters.php
new file mode 100644
index 00000000..c61f36d1
--- /dev/null
+++ b/src/Psl/Html/decode_special_characters.php
@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Html;
+
+use function htmlspecialchars_decode;
+
+use const ENT_HTML5;
+use const ENT_QUOTES;
+use const ENT_SUBSTITUTE;
+
+/**
+ * Convert special HTML entities back to characters.
+ *
+ * @psalm-pure
+ */
+function decode_special_characters(string $html): string
+{
+    return htmlspecialchars_decode($html, ENT_QUOTES | ENT_HTML5 | ENT_SUBSTITUTE);
+}
diff --git a/src/Psl/Html/encode.php b/src/Psl/Html/encode.php
new file mode 100644
index 00000000..0a97b22e
--- /dev/null
+++ b/src/Psl/Html/encode.php
@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Html;
+
+use Psl\Exception;
+use Psl\Internal;
+
+use function htmlentities;
+
+use const ENT_QUOTES;
+
+/**
+ * Convert all applicable characters to HTML entities.
+ *
+ * @param bool $double_encoding If set to false, this function will not
+ *  encode existing html entities.
+ * @param string $encoding defines character set used in conversion.
+ *
+ * @throws Exception\InvariantViolationException If $encoding is invalid.
+ *
+ * @psalm-pure
+ */
+function encode(string $html, bool $double_encoding = true, ?string $encoding = null): string
+{
+    $encoding = Internal\internal_encoding($encoding);
+
+    return htmlentities($html, ENT_QUOTES, $encoding, $double_encoding);
+}
diff --git a/src/Psl/Html/encode_special_characters.php b/src/Psl/Html/encode_special_characters.php
new file mode 100644
index 00000000..0858b1ee
--- /dev/null
+++ b/src/Psl/Html/encode_special_characters.php
@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Html;
+
+use Psl\Exception;
+use Psl\Internal;
+
+use function htmlspecialchars;
+
+use const ENT_HTML5;
+use const ENT_QUOTES;
+use const ENT_SUBSTITUTE;
+
+/**
+ * Convert special characters to HTML entities.
+ *
+ * @param bool $double_encoding If set to false, this function will not
+ *  encode existing html entities.
+ * @param string $encoding defines character set used in conversion.
+ *
+ * @throws Exception\InvariantViolationException If $encoding is invalid.
+ *
+ * @psalm-pure
+ */
+function encode_special_characters(string $html, bool $double_encoding = true, ?string $encoding = null): string
+{
+    $encoding = Internal\internal_encoding($encoding);
+
+    return htmlspecialchars($html, ENT_QUOTES | ENT_HTML5 | ENT_SUBSTITUTE, $encoding, $double_encoding);
+}
diff --git a/src/Psl/Internal/Loader.php b/src/Psl/Internal/Loader.php
index 901f116f..9ef8c361 100644
--- a/src/Psl/Internal/Loader.php
+++ b/src/Psl/Internal/Loader.php
@@ -460,6 +460,10 @@ final class Loader
         'Psl\Shell\escape_command',
         'Psl\Shell\escape_argument',
         'Psl\Shell\execute',
+        'Psl\Html\encode',
+        'Psl\Html\encode_special_characters',
+        'Psl\Html\decode',
+        'Psl\Html\decode_special_characters',
     ];
 
     public const INTERFACES = [
diff --git a/tests/Psl/Html/DecodeSpecialCharactersTest.php b/tests/Psl/Html/DecodeSpecialCharactersTest.php
new file mode 100644
index 00000000..739ecb83
--- /dev/null
+++ b/tests/Psl/Html/DecodeSpecialCharactersTest.php
@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Html;
+
+use PHPUnit\Framework\TestCase;
+use Psl\Html;
+
+final class DecodeSpecialCharactersTest extends TestCase
+{
+    /**
+     * @dataProvider provideData
+     */
+    public function testEncode(string $expected, string $html): void
+    {
+        static::assertSame($expected, Html\decode_special_characters($html));
+    }
+
+    public function provideData(): iterable
+    {
+        yield ['hello', 'hello'];
+        yield ['héllo', 'héllo'];
+        yield ['<hello />', '&lt;hello /&gt;'];
+        yield ['<p>Hello</p>', '&lt;p&gt;Hello&lt;/p&gt;'];
+        yield ['<p>&lt; </p>', '&lt;p&gt;&amp;lt; &lt;/p&gt;'];
+
+        yield ['hello', 'hello'];
+        yield ['héllo', 'héllo'];
+        yield ['<hello />', '&lt;hello /&gt;'];
+        yield ['<p>Hello</p>', '&lt;p&gt;Hello&lt;/p&gt;'];
+        yield ['<p>< </p>', '&lt;p&gt;&lt; &lt;/p&gt;'];
+    }
+}
diff --git a/tests/Psl/Html/DecodeTest.php b/tests/Psl/Html/DecodeTest.php
new file mode 100644
index 00000000..8b56fe52
--- /dev/null
+++ b/tests/Psl/Html/DecodeTest.php
@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Html;
+
+use PHPUnit\Framework\TestCase;
+use Psl\Html;
+
+final class DecodeTest extends TestCase
+{
+    /**
+     * @dataProvider provideData
+     */
+    public function testEncode(string $expected, string $html, ?string $encoding): void
+    {
+        static::assertSame($expected, Html\decode($html, $encoding));
+    }
+
+    public function provideData(): iterable
+    {
+        yield ['hello', 'hello', 'UTF-8'];
+        yield ['héllo', 'h&eacute;llo', 'UTF-8'];
+        yield ['<hello />', '&lt;hello /&gt;', 'UTF-8'];
+        yield ['<p>Hello</p>', '&lt;p&gt;Hello&lt;/p&gt;', 'UTF-8'];
+        yield ['<p>&lt; </p>', '&lt;p&gt;&amp;lt; &lt;/p&gt;', 'UTF-8'];
+
+        yield ['hello', 'hello', 'UTF-8'];
+        yield ['héllo', 'h&eacute;llo', 'UTF-8'];
+        yield ['<hello />', '&lt;hello /&gt;', 'UTF-8'];
+        yield ['<p>Hello</p>', '&lt;p&gt;Hello&lt;/p&gt;', 'UTF-8'];
+        yield ['<p>< </p>', '&lt;p&gt;&lt; &lt;/p&gt;', 'UTF-8'];
+    }
+}
diff --git a/tests/Psl/Html/EncodeSpecialCharactersTest.php b/tests/Psl/Html/EncodeSpecialCharactersTest.php
new file mode 100644
index 00000000..17c5b730
--- /dev/null
+++ b/tests/Psl/Html/EncodeSpecialCharactersTest.php
@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Html;
+
+use PHPUnit\Framework\TestCase;
+use Psl\Html;
+
+final class EncodeSpecialCharactersTest extends TestCase
+{
+    /**
+     * @dataProvider provideData
+     */
+    public function testEncode(string $expected, string $html, bool $double_encoding, ?string $encoding): void
+    {
+        static::assertSame($expected, Html\encode_special_characters($html, $double_encoding, $encoding));
+    }
+
+    public function provideData(): iterable
+    {
+        yield ['hello', 'hello', true, 'UTF-8'];
+        yield ['héllo', 'héllo', true, 'UTF-8'];
+        yield ['&lt;hello /&gt;', '<hello />', true, 'UTF-8'];
+        yield ['&lt;p&gt;Hello&lt;/p&gt;', '<p>Hello</p>', true, 'UTF-8'];
+        yield ['&lt;p&gt;&amp;lt; &lt;/p&gt;', '<p>&lt; </p>', true, 'UTF-8'];
+
+        yield ['hello', 'hello', false, 'UTF-8'];
+        yield ['héllo', 'héllo', false, 'UTF-8'];
+        yield ['&lt;hello /&gt;', '<hello />', false, 'UTF-8'];
+        yield ['&lt;p&gt;Hello&lt;/p&gt;', '<p>Hello</p>', false, 'UTF-8'];
+        yield ['&lt;p&gt;&lt; &lt;/p&gt;', '<p>&lt; </p>', false, 'UTF-8'];
+    }
+}
diff --git a/tests/Psl/Html/EncodeTest.php b/tests/Psl/Html/EncodeTest.php
new file mode 100644
index 00000000..a3d45296
--- /dev/null
+++ b/tests/Psl/Html/EncodeTest.php
@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Html;
+
+use PHPUnit\Framework\TestCase;
+use Psl\Html;
+
+final class EncodeTest extends TestCase
+{
+    /**
+     * @dataProvider provideData
+     */
+    public function testEncode(string $expected, string $html, bool $double_encoding, ?string $encoding): void
+    {
+        static::assertSame($expected, Html\encode($html, $double_encoding, $encoding));
+    }
+
+    public function provideData(): iterable
+    {
+        yield ['hello', 'hello', true, 'UTF-8'];
+        yield ['h&eacute;llo', 'héllo', true, 'UTF-8'];
+        yield ['&lt;hello /&gt;', '<hello />', true, 'UTF-8'];
+        yield ['&lt;p&gt;Hello&lt;/p&gt;', '<p>Hello</p>', true, 'UTF-8'];
+        yield ['&lt;p&gt;&amp;lt; &lt;/p&gt;', '<p>&lt; </p>', true, 'UTF-8'];
+
+        yield ['hello', 'hello', false, 'UTF-8'];
+        yield ['h&eacute;llo', 'héllo', false, 'UTF-8'];
+        yield ['&lt;hello /&gt;', '<hello />', false, 'UTF-8'];
+        yield ['&lt;p&gt;Hello&lt;/p&gt;', '<p>Hello</p>', false, 'UTF-8'];
+        yield ['&lt;p&gt;&lt; &lt;/p&gt;', '<p>&lt; </p>', false, 'UTF-8'];
+    }
+}