add html formatter

Author: michalsn

composer.json

@@ -17,7 +17,7 @@
     },
     "require-dev": {
         "codeigniter4/devkit": "^1.0",
-        "codeigniter4/framework": "^4.1"
+        "codeigniter4/framework": "^4.3"
     },
     "minimum-stability": "dev",
     "prefer-stable": true,

docs/html_formatter.md

@@ -0,0 +1,51 @@
+# HTML Formatter
+
+There are times when we want to work with HTMX through an API. In such cases, we may want to use [Response Trait API](https://codeigniter.com/user_guide/outgoing/api_responses.html).
+
+Unfortunately, CodeIgniter does not support HTML formatting for API by default. That's why such a formatter is included here. It will make it easier to work with the API when we want to return data in HTML format.
+
+### Configuration
+
+We should edit the `app/Config/Format.php` file to include the necessary changes. We should add `'text/html'` to the `$supportedResponseFormats` array, and `'text/html' => HTMLFormatter::class` to the `$formatters` array. This will be done automatically when you run the command:
+
+    php spark htmx:publish
+
+Since content negotiation will be triggered for any format other than `json` or `xml`, we have two options:
+
+1. Set the custom headers for every request via HTML tag
+   ```html
+   hx-headers='{"Accept":"text/html"}'
+   ```
+2. Move the `'text/html'` entry from the `$supportedResponseFormats` config array to the first position in the array - this way it will be used as the default value.
+   ```php
+   public array $supportedResponseFormats = [
+        'text/html'
+        'application/json',
+        'application/xml', // machine-readable XML
+        'text/xml', // human-readable XML
+   ];
+   ```
+
+### Example
+
+This is an sample of using HTML formatter:
+
+```php
+<?php
+
+namespace App\Controllers;
+
+use CodeIgniter\API\ResponseTrait;
+use CodeIgniter\RESTful\ResourcePresenter;
+
+class Photos extends ResourcePresenter
+{
+    use ResponseTrait;
+
+    public function index()
+    {
+        $this->format = 'html';
+        return $this->respondCreated('<div>Some data</div>');
+    }
+}
+```

docs/index.md

@@ -19,6 +19,7 @@ It also provides some additional help with **handling errors** and **Debug Toolb
 * [Response](response.md)
 * [RediretResponse](redirect_response.md)
 * [Debug Toolbar](debug_toolbar.md)
+* [HTML Formatter](html_formatter.md)
 * [Troubleshooting](troubleshooting.md)
 
 ### Demos

src/Commands/HtmxPublish.php

@@ -40,6 +40,26 @@ public function run(array $params)
             file_put_contents($file, $contents);
         }
 
+        $file = APPPATH . 'Config/Format.php';
+
+        $publisher->addLineAfter(
+            $file,
+            "        'text/html'",
+            "'text/xml', // human-readable XML",
+        );
+
+        $publisher->addLineAfter(
+            $file,
+            "        'text/html'        => HTMLFormatter::class,",
+            "'text/xml'         => XMLFormatter::class,",
+        );
+
+        $publisher->addLineAfter(
+            $file,
+            'use Michalsn\\CodeIgniterHtmx\\Format\\HTMLFormatter;',
+            'use CodeIgniter\\Format\\XMLFormatter;',
+        );
+
         CLI::write(CLI::color('  Published! ', 'green') . 'You can customize the configuration by editing the "app/Config/Htmx.php" file.');
     }
 }

src/Format/HTMLFormatter.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace Michalsn\CodeIgniterHtmx\Format;
+
+use CodeIgniter\Format\FormatterInterface;
+use CodeIgniter\View\Table;
+
+/**
+ * HTML data formatter
+ */
+class HTMLFormatter implements FormatterInterface
+{
+    /**
+     * Takes the given data and formats it.
+     *
+     * @param array|string|null $data
+     */
+    public function format($data): string
+    {
+        if ($data === null || $data === '' || $data === []) {
+            return '';
+        }
+
+        if (is_array($data)) {
+            if (array_keys($data) === ['status', 'error', 'messages']) {
+                if (isset($data['messages']['error']) && count($data['messages']) === 1) {
+                    return $data['messages']['error'];
+                }
+
+                $data = $data['messages'];
+            }
+
+            $data = $this->formatTable($data);
+        }
+
+        return $data;
+    }
+
+    /**
+     * Format data as a table.
+     *
+     * @param mixed $data
+     */
+    protected function formatTable($data): string
+    {
+        if (isset($data[0]) && count($data) !== count($data, COUNT_RECURSIVE)) {
+            // Multi-dimensional array
+            $headings = array_keys($data[0]);
+        } else {
+            // Single array
+            $headings = array_keys($data);
+            $data     = [$data];
+        }
+
+        $table = new Table();
+        $table->setHeading($headings);
+
+        foreach ($data as $row) {
+            // Suppressing the "array to string conversion" notice
+            // Keep the "evil" @ here
+            $row = @array_map('strval', $row);
+
+            $table->addRow($row);
+        }
+
+        return $table->generate();
+    }
+}

tests/Format/HTMLFormatterTest.php

@@ -0,0 +1,76 @@
+<?php
+
+namespace Tests\Format;
+
+use CodeIgniter\Test\CIUnitTestCase;
+use Michalsn\CodeIgniterHtmx\Format\HTMLFormatter;
+
+/**
+ * @internal
+ */
+final class HTMLFormatterTest extends CIUnitTestCase
+{
+    private HTMLFormatter $htmlFormatter;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->htmlFormatter = new HTMLFormatter();
+    }
+
+    public function testEmptyHTML(): void
+    {
+        $data = [];
+
+        $expected = '';
+
+        $this->assertSame($expected, $this->htmlFormatter->format($data));
+    }
+
+    public function testBasicHTML(): void
+    {
+        $data = '<div>Hello</div>';
+
+        $expected = '<div>Hello</div>';
+
+        $this->assertSame($expected, $this->htmlFormatter->format($data));
+    }
+
+    public function testFormatFailArray(): void
+    {
+        $data = [
+            'status'   => 400,
+            'error'    => 400,
+            'messages' => ['error' => '<div>Error</div>'],
+        ];
+
+        $expected = '<div>Error</div>';
+
+        $this->assertSame($expected, $this->htmlFormatter->format($data));
+    }
+
+    public function testFormatFailArrayWithManyMessages(): void
+    {
+        $data = [
+            'status'   => 400,
+            'error'    => 400,
+            'messages' => ['error' => '<div>Error</div>', 'example' => '<div>Example</div>'],
+        ];
+
+        $expected = <<<'EOH'
+            <table border="0" cellpadding="4" cellspacing="0">
+            <thead>
+            <tr>
+            <th>error</th><th>example</th></tr>
+            </thead>
+            <tbody>
+            <tr>
+            <td><div>Error</div></td><td><div>Example</div></td></tr>
+            </tbody>
+            </table>
+            EOH;
+
+        $this->assertSame($expected, $this->htmlFormatter->format($data));
+    }
+
+}