feat(asset): add AssetExtension for deduplicated CSS/JS inclusion

- require_css / require_js queue assets by file path (last-write-wins)
- flush_css / flush_js output all queued tags and clear the queue
- assign mode returns structured arrays with full metadata
- URL scheme allowlist (http, https, protocol-relative, relative paths)
- Entity-encoded URLs decoded before validation and stored decoded
- Colons in query strings correctly allowed for proxy/cache-buster URLs
- 28 tests covering dedup, scheme safety, attribute override, assign
- README, TUTORIAL, and CHANGELOG updated

Author: mambax7

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.1.0] - 2026-03-31
+
+### New Features
+
+* **AssetExtension** — deduplicated CSS and JS inclusion for templates
+  - `require_css` / `require_js` queue assets by file path (last-write-wins for conflicting attributes)
+  - `flush_css` / `flush_js` output all queued `<link>`/`<script>` tags and clear the queue
+  - `assign` mode returns structured arrays with full metadata (file, media, defer, async)
+  - URL scheme allowlist: `http://`, `https://`, protocol-relative, and relative paths only
+  - Entity-encoded URLs are decoded before validation and stored decoded
+  - Colons in query strings (e.g., `asset.php?src=https://...`) are correctly allowed
+
 ## [1.0.1] - 2026-03-31
 
 ### Security

README.md

@@ -26,6 +26,7 @@ use Xoops\SmartyExtensions\Extension\DataExtension;
 use Xoops\SmartyExtensions\Extension\SecurityExtension;
 use Xoops\SmartyExtensions\Extension\FormExtension;
 use Xoops\SmartyExtensions\Extension\XoopsCoreExtension;
+use Xoops\SmartyExtensions\Extension\AssetExtension;
 
 $registry = new ExtensionRegistry();
 $registry->add(new TextExtension());
@@ -35,6 +36,7 @@ $registry->add(new DataExtension());
 $registry->add(new SecurityExtension($xoopsSecurity, $grouppermHandler));
 $registry->add(new FormExtension($xoopsSecurity));
 $registry->add(new XoopsCoreExtension());
+$registry->add(new AssetExtension());
 
 $registry->registerAll($smarty);
 ```
@@ -180,6 +182,19 @@ XOOPS-specific functions (config, users, modules, blocks).
 | `ray_dump` | function | Dump variable structure to Ray |
 | `ray_table` | function | Send array to Ray table display |
 
+### AssetExtension
+
+Deduplicated CSS and JS inclusion (pure PHP, no XOOPS dependencies).
+
+| Plugin | Type | Description |
+|--------|------|-------------|
+| `require_css` | function | Queue a stylesheet (deduplicated by file path, last-write-wins) |
+| `require_js` | function | Queue a script (deduplicated, supports `defer`/`async`) |
+| `flush_css` | function | Output all `<link>` tags and reset the queue |
+| `flush_js` | function | Output all `<script>` tags and reset the queue |
+
+Asset URLs are validated against a safe-scheme allowlist (`http://`, `https://`, `//`, relative paths). Unsafe schemes like `javascript:` and `data:` are silently rejected.
+
 ## Writing Custom Extensions
 
 Extend `AbstractExtension` and override the getter methods:

docs/TUTORIAL.md

@@ -16,6 +16,7 @@ For the full plugin reference table, see [README.md](../README.md).
 - [Forms](#forms)
 - [Security and Permissions](#security-and-permissions)
 - [XOOPS Core Helpers](#xoops-core-helpers)
+- [Asset Management](#asset-management)
 - [Ray Debugging](#ray-debugging)
 - [Writing Your Own Extension](#writing-your-own-extension)
 - [Best Practices](#best-practices)
@@ -39,6 +40,7 @@ use Xoops\SmartyExtensions\Extension\SecurityExtension;
 use Xoops\SmartyExtensions\Extension\FormExtension;
 use Xoops\SmartyExtensions\Extension\XoopsCoreExtension;
 use Xoops\SmartyExtensions\Extension\RayDebugExtension;
+use Xoops\SmartyExtensions\Extension\AssetExtension;
 
 $registry = new ExtensionRegistry();
 $registry->add(new TextExtension());
@@ -49,6 +51,7 @@ $registry->add(new SecurityExtension($xoopsSecurity, $grouppermHandler));
 $registry->add(new FormExtension($xoopsSecurity));
 $registry->add(new XoopsCoreExtension());
 $registry->add(new RayDebugExtension());
+$registry->add(new AssetExtension());
 
 $registry->registerAll($smarty);
 ```
@@ -92,6 +95,7 @@ Some extensions are pure PHP and work in any Smarty environment. Others require
 | FormExtension | Optional | `XoopsSecurity` for CSRF injection; works without it (no token) |
 | SecurityExtension | Yes | `XoopsSecurity`, `XoopsGroupPermHandler`, `$xoopsUser` global |
 | XoopsCoreExtension | Yes | `$xoopsConfig`, `$xoopsUser`, `xoops_getHandler()`, `XOOPS_URL` |
+| AssetExtension | No | Pure PHP |
 | RayDebugExtension | Yes | Debugbar module with RayLogger enabled, `ray()` function |
 
 ### Plugin types
@@ -846,6 +850,65 @@ The `options` array must contain a `block` key with a block object that implemen
 
 ---
 
+## Asset Management
+
+AssetExtension prevents duplicate `<link>` and `<script>` tags when multiple templates or blocks request the same stylesheet or script within a single page render. Pure PHP, no XOOPS dependencies.
+
+### Queueing assets
+
+Register CSS and JS files from anywhere in your templates — blocks, module templates, theme includes. Duplicates are deduplicated by file path. If the same file is registered again with different attributes (e.g., different `media` or `defer`), the later registration wins.
+
+```smarty
+<{* In a block template *}>
+<{require_css file="modules/news/assets/news.css"}>
+<{require_js file="modules/news/assets/news.js" defer=true}>
+
+<{* In another block — same file, no duplicate emitted *}>
+<{require_css file="modules/news/assets/news.css"}>
+
+<{* External CDN assets *}>
+<{require_js file="https://cdn.example.com/lib.js" async=true}>
+
+<{* Print stylesheet *}>
+<{require_css file="modules/news/assets/print.css" media="print"}>
+```
+
+### Flushing assets in the theme
+
+Place these in your theme footer to output all queued tags at once:
+
+```smarty
+<{* In theme header — output all CSS *}>
+<{flush_css}>
+
+<{* In theme footer — output all JS *}>
+<{flush_js}>
+```
+
+After flushing, the queue is cleared. A second `flush_css` or `flush_js` call outputs nothing.
+
+### Custom rendering with assign
+
+Use `assign` to get the full metadata for custom rendering. The assigned value is a list of structured arrays, not just file paths:
+
+```smarty
+<{flush_css assign="styles"}>
+<{foreach $styles as $entry}>
+  <link rel="stylesheet" href="<{$entry.file|escape}>" media="<{$entry.media|escape}>">
+<{/foreach}>
+
+<{flush_js assign="scripts"}>
+<{foreach $scripts as $entry}>
+  <script src="<{$entry.file|escape}>"<{if $entry.defer}> defer<{/if}><{if $entry.async}> async<{/if}>></script>
+<{/foreach}>
+```
+
+### URL safety
+
+Asset URLs are validated against a safe-scheme allowlist. Only `http://`, `https://`, protocol-relative (`//cdn...`), and relative paths are accepted. Unsafe schemes like `javascript:` and `data:` are silently rejected, including entity-encoded variants. URLs with colons in query strings (e.g., `asset.php?src=https://cdn.example.com/lib.js`) are correctly allowed.
+
+---
+
 ## Ray Debugging
 
 RayDebugExtension sends template data to the [Ray](https://myray.app) desktop debugger. All functions silently no-op when Ray is not installed or the Debugbar RayLogger is disabled, so templates can safely contain Ray tags in production.
@@ -1058,3 +1121,5 @@ The `formatStatus()` example above intentionally returns `<span>` markup. This i
 | `has_user_permission` always returns false | `XoopsGroupPermHandler` was not injected | Pass the handler: `new SecurityExtension($security, $grouppermHandler)` |
 | Ray functions produce no output | Expected — they send data to the Ray desktop app, not the browser | Check that the Debugbar module is active, RayLogger is enabled, and the `ray()` helper function is installed. |
 | Modifier output shows raw HTML tags | `\|escape` was applied after an HTML-producing modifier | Remove `\|escape` from `nl2p`, `highlight_text`, `linkify`, and similar modifiers that return markup. |
+| `require_css` / `require_js` silently ignores a file | The URL contains an unsafe scheme (`data:`, `javascript:`) | Only `http://`, `https://`, protocol-relative (`//`), and relative paths are accepted. |
+| `flush_css` / `flush_js` outputs nothing | No assets were queued, or the queue was already flushed | Each flush clears the queue. Call `require_css`/`require_js` before flushing. |

src/Extension/AssetExtension.php

@@ -0,0 +1,190 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Xoops\SmartyExtensions\Extension;
+
+use Xoops\SmartyExtensions\AbstractExtension;
+
+/**
+ * Asset management Smarty functions — deduplicated CSS and JS inclusion.
+ *
+ * Prevents duplicate <link> and <script> tags when multiple templates or
+ * blocks request the same stylesheet or script within a single page render.
+ *
+ * Pure PHP — no XOOPS dependencies.
+ *
+ * Usage:
+ *   <{require_css file="modules/news/assets/news.css"}>
+ *   <{require_js file="modules/news/assets/news.js"}>
+ *   <{require_js file="https://cdn.example.com/lib.js" defer=true}>
+ *
+ * At the end of the page (typically in theme footer):
+ *   <{flush_css}>
+ *   <{flush_js}>
+ *
+ * Or collect them as structured arrays for custom rendering:
+ *   <{flush_css assign="styles"}>
+ *   <{flush_js assign="scripts"}>
+ *
+ * @copyright (c) 2000-2026 XOOPS Project (https://xoops.org)
+ * @license   GNU GPL 2 (https://www.gnu.org/licenses/gpl-2.0.html)
+ */
+final class AssetExtension extends AbstractExtension
+{
+    /** @var array<string, array{file: string, media: string}> */
+    private array $css = [];
+
+    /** @var array<string, array{file: string, defer: bool, async: bool}> */
+    private array $js = [];
+
+    public function getFunctions(): array
+    {
+        return [
+            'require_css' => $this->requireCss(...),
+            'require_js'  => $this->requireJs(...),
+            'flush_css'   => $this->flushCss(...),
+            'flush_js'    => $this->flushJs(...),
+        ];
+    }
+
+    /**
+     * Register a CSS stylesheet for inclusion.
+     *
+     * If the same file is registered again with different attributes,
+     * the later registration wins (last-write-wins).
+     *
+     * Parameters:
+     *   file  — URL or path to the stylesheet (required)
+     *   media — media attribute (default: "all")
+     */
+    public function requireCss(array $params, object $template): string
+    {
+        $file = $this->sanitizeAssetUrl($params['file'] ?? '');
+        if ($file === '') {
+            return '';
+        }
+
+        $this->css[$file] = [
+            'file'  => $file,
+            'media' => $params['media'] ?? 'all',
+        ];
+
+        return '';
+    }
+
+    /**
+     * Register a JavaScript file for inclusion.
+     *
+     * If the same file is registered again with different attributes,
+     * the later registration wins (last-write-wins).
+     *
+     * Parameters:
+     *   file  — URL or path to the script (required)
+     *   defer — add defer attribute (default: false)
+     *   async — add async attribute (default: false)
+     */
+    public function requireJs(array $params, object $template): string
+    {
+        $file = $this->sanitizeAssetUrl($params['file'] ?? '');
+        if ($file === '') {
+            return '';
+        }
+
+        $this->js[$file] = [
+            'file'  => $file,
+            'defer' => !empty($params['defer']),
+            'async' => !empty($params['async']),
+        ];
+
+        return '';
+    }
+
+    /**
+     * Output all registered CSS <link> tags and reset the queue.
+     *
+     * With assign: stores a list of entry arrays (file, media) for custom rendering.
+     */
+    public function flushCss(array $params, object $template): string
+    {
+        if (!empty($params['assign'])) {
+            $template->assign($params['assign'], \array_values($this->css));
+            $this->css = [];
+            return '';
+        }
+
+        $html = '';
+        foreach ($this->css as $entry) {
+            $safeFile = \htmlspecialchars($entry['file'], ENT_QUOTES, 'UTF-8');
+            $safeMedia = \htmlspecialchars($entry['media'], ENT_QUOTES, 'UTF-8');
+            $html .= '<link rel="stylesheet" href="' . $safeFile . '" media="' . $safeMedia . '">' . "\n";
+        }
+
+        $this->css = [];
+
+        return $html;
+    }
+
+    /**
+     * Output all registered JS <script> tags and reset the queue.
+     *
+     * With assign: stores a list of entry arrays (file, defer, async) for custom rendering.
+     */
+    public function flushJs(array $params, object $template): string
+    {
+        if (!empty($params['assign'])) {
+            $template->assign($params['assign'], \array_values($this->js));
+            $this->js = [];
+            return '';
+        }
+
+        $html = '';
+        foreach ($this->js as $entry) {
+            $safeFile = \htmlspecialchars($entry['file'], ENT_QUOTES, 'UTF-8');
+            $attrs = '';
+            if ($entry['defer']) {
+                $attrs .= ' defer';
+            }
+            if ($entry['async']) {
+                $attrs .= ' async';
+            }
+            $html .= '<script src="' . $safeFile . '"' . $attrs . '></script>' . "\n";
+        }
+
+        $this->js = [];
+
+        return $html;
+    }
+
+    /**
+     * Decode HTML entities and validate the URL scheme.
+     *
+     * Accepts: http://, https://, relative paths, protocol-relative (//cdn...).
+     * Rejects: javascript:, data:, and any other unsafe scheme.
+     *
+     * Returns the decoded URL on success, or empty string on rejection.
+     */
+    private function sanitizeAssetUrl(string $url): string
+    {
+        $decoded = \html_entity_decode($url, ENT_QUOTES | ENT_HTML5, 'UTF-8');
+
+        // Absolute with safe scheme
+        if (\preg_match('#^https?://#i', $decoded)) {
+            return $decoded;
+        }
+
+        // Protocol-relative
+        if (\str_starts_with($decoded, '//')) {
+            return $decoded;
+        }
+
+        // Relative path: only reject if a scheme-like colon appears in the
+        // path portion before any / or ? (colons in query strings are fine)
+        $schemeEnd = \strcspn($decoded, '/?');
+        if (!\str_contains(\substr($decoded, 0, $schemeEnd), ':')) {
+            return $decoded;
+        }
+
+        return '';
+    }
+}