Initial release

.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  tests:
+    if: "!contains(github.event.head_commit.message, 'skip ci')"
+    name: PHP ${{ matrix.php-versions }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    continue-on-error: ${{ matrix.php-versions >= '8.3' }}
+    strategy:
+      fail-fast: false
+      matrix:
+        php-versions: ['7.0', '7.1', '7.2', '7.3', '7.4', '8.0', '8.1', '8.2', '8.3', '8.4']
+        os: [ubuntu-latest, windows-latest]
+
+    steps:
+    - name: Configure git
+      if: runner.os == 'Windows'
+      run: git config --system core.autocrlf false; git config --system core.eol lf
+
+    - name: Checkout
+      uses: actions/checkout@v3
+
+    - name: Set up PHP ${{ matrix.php-versions }}
+      uses: shivammathur/setup-php@v2
+      with:
+        php-version: ${{ matrix.php-versions }}
+        ini-values: date.timezone=Europe/Berlin
+
+    - name: Validate composer.json and composer.lock
+      run: composer validate
+
+    - name: Get Composer Cache Directory
+      id: composer-cache
+      run: echo "::set-output name=dir::$(composer config cache-files-dir)"
+
+    - name: Cache dependencies
+      uses: actions/cache@v3
+      with:
+        path: ${{ steps.composer-cache.outputs.dir }}
+        key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
+        restore-keys: ${{ runner.os }}-composer-
+
+    - name: Install dependencies
+      run: >
+        curl -sSL https://baltocdn.com/xp-framework/xp-runners/distribution/downloads/e/entrypoint/xp-run-8.7.0.sh > xp-run &&
+        composer install --prefer-dist &&
+        echo "vendor/autoload.php" > composer.pth
+
+    - name: Run test suite
+      run: sh xp-run xp.test.Runner -r Dots src/test/php

ChangeLog.md

@@ -0,0 +1,8 @@
+HTMX for XP web frontends change log
+====================================
+
+## ?.?.? / ????-??-??
+
+## 0.1.0 / 2024-01-28
+
+* First public release - @thekid

README.md

@@ -0,0 +1,32 @@
+HTMX for XP web frontends
+=========================
+
+[![Build status on GitHub](https://github.com/xp-forge/htmx/workflows/Tests/badge.svg)](https://github.com/xp-forge/htmx/actions)
+[![XP Framework Module](https://raw.githubusercontent.com/xp-framework/web/master/static/xp-framework-badge.png)](https://github.com/xp-framework/core)
+[![BSD Licence](https://raw.githubusercontent.com/xp-framework/web/master/static/licence-bsd.png)](https://github.com/xp-framework/core/blob/master/LICENCE.md)
+[![Requires PHP 7.0+](https://raw.githubusercontent.com/xp-framework/web/master/static/php-7_0plus.svg)](http://php.net/)
+[![Supports PHP 8.0+](https://raw.githubusercontent.com/xp-framework/web/master/static/php-8_0plus.svg)](http://php.net/)
+[![Latest Stable Version](https://poser.pugx.org/xp-forge/htmx/version.png)](https://packagist.org/packages/xp-forge/htmx)
+
+HTMX Integration
+
+Authentication
+--------------
+Wrap any authentication flow in a *HtmxFlow* to ensure authentication does not redirect but instead yields an error code and triggers an event:
+
+```diff
++ use web\frontend\HtmxFlow;
+
+- $auth= new SessionBased($flow, $sessions);
++ $auth= new SessionBased(new HtmxFlow($flow), $sessions);
+```
+
+Handle this inside JavaScript with something along the lines of the following:
+
+```javascript
+window.addEventListener('authenticationexpired', e => {
+  if (confirm('Authentication expired. Do you want to re-authenticate?')) {
+    window.location.reload();
+  }
+});
+````

class.pth

@@ -0,0 +1,3 @@
+src/main/php/
+src/test/php/
+src/test/php/

composer.json

@@ -0,0 +1,20 @@
+{
+  "name" : "xp-forge/htmx",
+  "type" : "library",
+  "homepage" : "http://xp-framework.net/",
+  "license" : "BSD-3-Clause",
+  "description" : "HTMX integration for XP web frontends",
+  "keywords": ["module", "xp"],
+  "require" : {
+    "xp-framework/core": "^11.0 | ^10.0",
+    "xp-forge/frontend": "^6.0 | ^5.0",
+    "xp-forge/web-auth": "^3.7",
+    "php": ">=7.0.0"
+  },
+  "require-dev" : {
+    "xp-framework/test": "^1.0"
+  },
+  "autoload" : {
+    "files" : ["src/main/php/autoload.php"]
+  }
+}

src/main/php/autoload.php

@@ -0,0 +1,3 @@
+<?php namespace xp;
+
+\lang\ClassLoader::registerPath(__DIR__);

src/main/php/web/frontend/HtmxFlow.class.php

@@ -0,0 +1,44 @@
+<?php namespace web\frontend;
+
+use web\auth\Flow;
+
+/**
+ * Wraps around any authentication flow and ensures that if there is the
+ * need to (re-)authenticate HTMX requests, a 401 error is sent back and
+ * an `authenticationexpired` event is triggered instead of redirecting.
+ *
+ * @see  https://htmx.org/reference/#headers
+ */
+class HtmxFlow extends Flow {
+  private $delegate;
+
+  /** Creates a new instance, wrapping around a given flow */
+  public function __construct(Flow $delegate) { $this->delegate= $delegate; }
+
+  /**
+   * Refreshes access token given a refresh token if necessary.
+   *
+   * @param  [:var] $claims
+   * @return ?web.auth.Authorization
+   * @throws lang.IllegalStateException
+   */
+  public function refresh(array $claims) { return $this->delegate->refresh($claims); }
+
+  /**
+   * Executes authentication flow, returning the authentication result
+   *
+   * @param  web.Request $request
+   * @param  web.Response $response
+   * @param  web.session.Session $session
+   * @return var
+   */
+  public function authenticate($request, $response, $session) {
+    if ('true' === $request->header('Hx-Request')) {
+      $response->answer(401);
+      $response->header('HX-Trigger', 'authenticationexpired');
+      return null;
+    }
+
+    return $this->delegate->authenticate($request, $response, $session);
+  }
+}

src/test/php/web/frontend/unittest/HtmxFlowTest.class.php

@@ -0,0 +1,17 @@
+<?php namespace web\frontend\unittest;
+
+use test\{Assert, Test};
+use web\auth\Flow;
+use web\frontend\HtmxFlow;
+
+class HtmxFlowTest {
+
+  #[Test]
+  public function can_create() {
+    new HtmxFlow(new class() extends Flow {
+      public function authenticate($request, $response, $session) {
+        // NOOP
+      }
+    });
+  }
+}