[Html] Introduce HTML component

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);
+}

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);
+}

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);
+}

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);
+}

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 = [

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;'];
+    }
+}

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'];
+    }
+}

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'];
+    }
+}

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'];
+    }
+}