From 675770a09ce552ce6f3c95e02ae5dee5d29173ff Mon Sep 17 00:00:00 2001 From: Adam Daley Date: Thu, 28 May 2026 13:11:56 +0100 Subject: [PATCH 01/14] Move shared frontend assets to /public --- src/content/docs/admin-guide/company.mdoc | 4 ++-- .../file-structure.mdoc | 23 ++++++++++++++++++- .../guides/creating-a-theme.mdoc | 12 +++++++++- .../javascript.mdoc | 3 ++- .../twig-filters.mdoc | 9 ++++++-- .../docs/getting-started/building.mdoc | 18 +++++++++++---- .../docs/getting-started/installation.mdoc | 4 ++-- src/content/docs/maintenance/changelog.mdoc | 6 ++--- src/content/docs/maintenance/updating.mdoc | 23 ++++++++++++------- 9 files changed, 77 insertions(+), 25 deletions(-) diff --git a/src/content/docs/admin-guide/company.mdoc b/src/content/docs/admin-guide/company.mdoc index a1a9e8f..7c5d565 100644 --- a/src/content/docs/admin-guide/company.mdoc +++ b/src/content/docs/admin-guide/company.mdoc @@ -20,12 +20,12 @@ Upload the logo assets FOSSBilling should use across the interface: ### Best Practices -- Store logos in your theme's `assets/` folder +- Upload custom logos through the settings page so updates do not overwrite them - Use SVG for crisp display at any size - Keep file sizes reasonable (< 500KB) {% aside type="caution" %} -Don't edit `themes/huraga/assets/img/logo.svg` directly — it's overwritten on updates. Upload your logo through the settings page instead. +Don't edit the bundled files in `public/branding/` directly. They are default assets and may be overwritten on updates. Upload your logo through the settings page instead. {% /aside %} ### Logo Not Showing? diff --git a/src/content/docs/extensions-and-development/file-structure.mdoc b/src/content/docs/extensions-and-development/file-structure.mdoc index cce05ea..f2c4931 100644 --- a/src/content/docs/extensions-and-development/file-structure.mdoc +++ b/src/content/docs/extensions-and-development/file-structure.mdoc @@ -18,6 +18,13 @@ Runtime data storage: This directory should be writable by the web server. +### `/src/public` + +Public core assets that must be web-accessible: +- **Assets** — Shared built browser assets (`/public/assets`), including the API wrapper, shared runtime, Markdown CSS, and CKEditor bundle +- **Branding** — Default logo, dark logo, and favicon (`/public/branding`) +- **Gateway icons** — Payment gateway logos (`/public/gateways`) + ### `/src/install` The installation wizard. Automatically deleted after installation unless `APP_ENV=dev` is set. @@ -28,7 +35,7 @@ Core PHP classes and business logic. #### `/src/library/Api` -Core API files including the JavaScript wrapper (`API.js`). [See the wrapper docs](/extensions-and-development/javascript/). +Core PHP API files. The browser-side API wrapper source now lives in `/frontend/core/api.js` and builds to `/src/public/assets/js/api.js`. [See the wrapper docs](/extensions-and-development/javascript/). #### `/src/library/Box` @@ -87,6 +94,19 @@ These are for shared hosting control panels. For VPS or game servers, consider c Translations as a Git submodule. Pointing to [github.com/FOSSBilling/locale](https://github.com/FOSSBilling/locale). +### `/frontend` + +Shared frontend source and build tooling: + +| Path | Purpose | +|------|---------| +| `core/` | Shared browser runtime and API wrapper source | +| `editor/` | CKEditor integration source | +| `styles/` | Shared CSS such as Markdown rendering styles | +| `tools/` | Common esbuild, Sass, PostCSS, asset copy, and PurgeCSS helpers used by theme builds | + +The root `npm run build` command builds this directory into `/src/public/assets`. + ### `/src/modules` All modules live here. Each module is a self-contained unit of functionality. @@ -122,6 +142,7 @@ Theme structure: ``` theme-name/ ├── assets/ # CSS, JS, images (built via esbuild) +│ └── build/ # Generated theme assets and manifest ├── config/ │ └── settings.html.twig # Theme settings UI ├── html/ # Twig templates diff --git a/src/content/docs/extensions-and-development/guides/creating-a-theme.mdoc b/src/content/docs/extensions-and-development/guides/creating-a-theme.mdoc index 396df50..0805c32 100644 --- a/src/content/docs/extensions-and-development/guides/creating-a-theme.mdoc +++ b/src/content/docs/extensions-and-development/guides/creating-a-theme.mdoc @@ -30,7 +30,8 @@ themes/mytheme/ ├── assets/ # CSS, JS, images (built via esbuild) │ ├── css/ │ ├── js/ -│ └── img/ +│ ├── img/ +│ └── build/ # Generated assets and manifest ├── config/ │ └── settings.html.twig # Theme settings UI (optional) ├── html/ # Your templates @@ -122,10 +123,19 @@ FOSSBilling provides [custom filters](/extensions-and-development/twig-filters) {{ price | format_currency(currency.code) }} {# Format currency #} {{ 'client/manage' | url(area: 'admin') }} {# Admin panel link #} {{ 'css/theme.css' | asset_url }} {# Theme asset URL #} +{{ 'js/api.js' | public_asset_url }} {# Shared core asset URL #} {{ date | timeago }} {# "2 hours ago" #} {{ content | markdown_to_html }} {# Parse Markdown #} ``` +Custom layouts that do not extend the bundled themes should load the shared runtime and API wrapper before theme JavaScript: + +```twig +{{ 'js/fossbilling.js'|public_asset_url|script_tag }} +{{ 'js/api.js'|public_asset_url|script_tag }} + +``` + ## Security Best Practices - Use `htmlspecialchars` when outputting user data diff --git a/src/content/docs/extensions-and-development/javascript.mdoc b/src/content/docs/extensions-and-development/javascript.mdoc index ecc449c..3bda7a8 100644 --- a/src/content/docs/extensions-and-development/javascript.mdoc +++ b/src/content/docs/extensions-and-development/javascript.mdoc @@ -19,7 +19,8 @@ If you're building themes or modules, use this wrapper instead of making raw bro The bundled admin and Huraga themes already load the wrapper. For a custom theme, add this to your base layout before your theme JavaScript: ```twig -{{ "Api/API.js"|library_url|script_tag }} +{{ 'js/fossbilling.js'|public_asset_url|script_tag }} +{{ 'js/api.js'|public_asset_url|script_tag }} ``` diff --git a/src/content/docs/extensions-and-development/twig-filters.mdoc b/src/content/docs/extensions-and-development/twig-filters.mdoc index 0d91c91..f701df1 100644 --- a/src/content/docs/extensions-and-development/twig-filters.mdoc +++ b/src/content/docs/extensions-and-development/twig-filters.mdoc @@ -50,7 +50,7 @@ Project-specific filters and functions are defined in these classes: | Filter | Description | |--------|-------------| | `asset_url` | Get the URL for a theme asset. | -| `library_url` | Get the URL for the library folder. | +| `public_asset_url` | Get the URL for a shared core public asset built into `/public/assets`. | | `mod_asset_url` | Get the URL for a module asset. Use the asset path as the filtered value and the module name as the argument. | | `script_tag` | Generate an HTML ` +{{ 'js/api.js'|public_asset_url|script_tag }} -{# API form handled by Api/API.js #} +{# API form handled by the shared API wrapper #}
+{# Shared editor bundle #} +{{ wysiwyg('.editor-textarea') }} + {# API link with a confirmation modal #} diff --git a/src/content/docs/getting-started/building.mdoc b/src/content/docs/getting-started/building.mdoc index 22b1c85..56bdc3a 100644 --- a/src/content/docs/getting-started/building.mdoc +++ b/src/content/docs/getting-started/building.mdoc @@ -14,7 +14,7 @@ Build FOSSBilling from source when you want to contribute code, test changes loc Make sure you have: - PHP 8.3 or newer - [Composer](https://getcomposer.org/) (latest version) -- [Node.js](https://nodejs.org/) (LTS version) with npm +- [Node.js](https://nodejs.org/) with npm 11 or newer {% /aside %} ## Build Steps @@ -46,6 +46,8 @@ Make sure you have: npm run build ``` + This builds the shared frontend assets into `src/public/assets` and builds the bundled `admin_default` and `huraga` theme assets. + 5. **Add translations** (optional) Download the [latest translations](https://github.com/FOSSBilling/locale/releases/tag/latest) and extract to `src/locale/`, overwriting existing files. @@ -54,13 +56,19 @@ After these steps, your checkout is ready for local development or for packaging ## Development Mode -For active development: +For active theme development, use the theme workspace scripts: ```bash -npm run dev +npm run build-admin_default +npm run build-huraga ``` -This watches files and rebuilds automatically when you make changes. +The Huraga theme also supports watch mode: + +```bash +cd src/themes/huraga +npm run dev +``` ## Running Locally @@ -71,4 +79,4 @@ cd src php -S localhost:8000 ``` -Then visit `http://localhost:8000` in your browser. \ No newline at end of file +Then visit `http://localhost:8000` in your browser. diff --git a/src/content/docs/getting-started/installation.mdoc b/src/content/docs/getting-started/installation.mdoc index b8438d1..4fddbd1 100644 --- a/src/content/docs/getting-started/installation.mdoc +++ b/src/content/docs/getting-started/installation.mdoc @@ -76,8 +76,8 @@ server { return 403; } - # Deny access to /data, except /assets/gateways - location ~* /data/(?!(assets/gateways/)) { + # Deny access to runtime data + location ^~ /data/ { return 403; } diff --git a/src/content/docs/maintenance/changelog.mdoc b/src/content/docs/maintenance/changelog.mdoc index 34b2962..0216307 100644 --- a/src/content/docs/maintenance/changelog.mdoc +++ b/src/content/docs/maintenance/changelog.mdoc @@ -27,10 +27,10 @@ For the latest changes, start with the [most recent release](https://github.com/ | **Configuration** | New `rate_limiter` block replaces old `api.rate_*` keys; new `trusted_proxies` and `auto_detect_locale` settings | | **Modules** | `Antispam` replaces `Spamchecker`; `Servicemembership`, `Paidsupport`, `Wysiwyg` removed; new `Widgets` module | | **Templates** | All module templates moved from `html_*` to `templates/{admin,client,email}/` | -| **Build** | Front-end asset build migrated from webpack to esbuild | +| **Build** | Front-end asset build migrated from webpack to esbuild; shared frontend source now lives in `/frontend` and builds into `/src/public/assets` | | **Library** | New Doctrine ORM layer alongside RedBean; Symfony Rate Limiter, Uid, Sanitizer, Serializer, PropertyAccess components added; `Box_Mod`, `Box_Paginator`, `Box_TwigExtensions` removed | -| **Patcher** | Extended through patch 63 (was 43) | -| **Uploads** | Moved from `/uploads` to `/data/uploads` | +| **Patcher** | Extended through patch 64 (was 43) | +| **Uploads & Public Assets** | Uploads moved from `/uploads` to `/data/uploads`; gateway and default branding assets moved to `/public` | [View the full 0.8.0 release notes](https://github.com/FOSSBilling/FOSSBilling/releases/latest) for the complete list of changes. diff --git a/src/content/docs/maintenance/updating.mdoc b/src/content/docs/maintenance/updating.mdoc index 6a7214b..49231e0 100644 --- a/src/content/docs/maintenance/updating.mdoc +++ b/src/content/docs/maintenance/updating.mdoc @@ -71,7 +71,7 @@ The uploads directory has moved from `/uploads` to `/data/uploads`. Files are mi location ~* /uploads/.*\.php$ { return 403; } # Updated for 0.8.0: -location ~* /data/(?!(assets/gateways/)) { return 403; } +location ^~ /data/ { return 403; } ``` {% /tabitem %} {% tabitem label="Apache (.htaccess)" %} @@ -91,14 +91,21 @@ Module templates have been moved from the old `html_*` directory names to a `tem The patcher removes the old `html_*` directories from modules. If you have custom modules, **update your file structure before applying the patches**, or the old directories will be deleted and you will lose your changes. +### Public Assets + +Shared browser assets now live in `/public` instead of `/data/assets` or theme-specific fallback paths: + +| Asset | New location | +|-------|--------------| +| Gateway icons | `/public/gateways/` | +| Default logo, dark logo, and favicon | `/public/branding/` | +| Shared JavaScript, Markdown CSS, and CKEditor bundles | `/public/assets/` | + +The patcher migrates bundled gateway icons and default branding settings automatically. If you maintain custom web-server rules, make sure `/public` remains publicly readable while `/data` remains blocked. + +Custom themes should load shared frontend assets with `public_asset_url`, for example `{{ 'js/api.js'|public_asset_url|script_tag }}`. The old `library/Api/API.js` path has been removed. + ### Encryption Format Update Custom payment adapters or modules that store encrypted data using FOSSBilling's encryption may need their data re-encrypted after the update. The patcher (patch 50) handles this migration automatically for core data, but custom implementations should be verified. -### Post-Upgrade Checklist - -- [ ] Review spam/anti-spam settings (`Antispam` module replaces `Spamchecker`) -- [ ] Review active membership orders migrated to custom products -- [ ] Update web-server rules if you have custom NGINX/Apache configs -- [ ] Verify custom modules use the new `templates/` directory structure (custom themes are unaffected) -- [ ] Clear the cache: **System → Tools → Clear cache** From dd552bb532468b3b7e21d349507f4705d7f988b7 Mon Sep 17 00:00:00 2001 From: Adam Daley Date: Thu, 28 May 2026 13:21:34 +0100 Subject: [PATCH 02/14] Split update docs into overview and 0.7-to-0.8 --- .../0-7-to-0-8.mdoc} | 61 ++++++------------- .../docs/maintenance/updating/index.mdoc | 48 +++++++++++++++ 2 files changed, 67 insertions(+), 42 deletions(-) rename src/content/docs/maintenance/{updating.mdoc => updating/0-7-to-0-8.mdoc} (67%) create mode 100644 src/content/docs/maintenance/updating/index.mdoc diff --git a/src/content/docs/maintenance/updating.mdoc b/src/content/docs/maintenance/updating/0-7-to-0-8.mdoc similarity index 67% rename from src/content/docs/maintenance/updating.mdoc rename to src/content/docs/maintenance/updating/0-7-to-0-8.mdoc index 49231e0..465fb7f 100644 --- a/src/content/docs/maintenance/updating.mdoc +++ b/src/content/docs/maintenance/updating/0-7-to-0-8.mdoc @@ -1,55 +1,24 @@ --- -title: Updating FOSSBilling -description: Keep your FOSSBilling installation up to date with the latest features and security fixes. -sidebar: - label: Updating +title: Upgrading from 0.7.x to 0.8.0 +description: Version-specific upgrade notes for moving a FOSSBilling 0.7.x installation to 0.8.0. +sidebar: + label: 0.7.x to 0.8.0 order: 2 --- -{% aside type="danger" %} -**Always back up first.** Before any update, make full backups of your database and all FOSSBilling files. If something goes wrong, you'll need these to restore your data. -{% /aside %} - -## Automatic Updates (Recommended) - -For most installations, the built-in updater is the easiest option: - -1. Log in to your admin panel -2. Go to **System** → **Update** -3. Click to apply the update - -FOSSBilling downloads and applies the update automatically. It follows the configured update branch, usually `release` or `preview`, which you can change in your [configuration file](/admin-guide/config/). - -## Manual Updates - -If you prefer to manage files yourself: - -1. **Back up your database and files** -2. [Download the latest release](https://fossbilling.org/downloads/stable) -3. Extract the files over your existing installation (overwrite existing files) -4. Delete the `install` folder that came with the new files -5. Log in to the admin panel and go to **System** → **Update** -6. Click **Apply Patches & Update Configuration** - -Always run the patches after copying in new files so the database schema and configuration stay in sync with the codebase. - -If an update fails or FOSSBilling errors after updating, see [Troubleshooting FOSSBilling Issues](/maintenance/troubleshooting/#errors-after-updating). - -## Upgrading from 0.7.x to 0.8.0 - The 0.8.0 release includes significant database and structural changes. Read the notes below before upgrading. -### Database & Charset Migration +## Database & Charset Migration The database charset has been migrated from `utf8` to `utf8mb4` / `utf8mb4_unicode_ci`. The patcher handles this automatically. -### Configuration Changes +## Configuration Changes - `db.type` has been renamed to `db.driver` and its value changed from `'mysql'` to `'pdo_mysql'`. The patcher migrates this for you. - Old `api.rate_*` settings (`rate_span`, `rate_limit`, `throttle_delay`, `rate_span_login`, `rate_limit_login`, `rate_limit_whitelist`) have been replaced by the new `rate_limiter` block. The patcher will prompt you to accept the new defaults. - The `url` setting no longer stores the protocol prefix; it is stripped on save. -### Module Migrations +## Module Migrations The following modules have been removed or replaced. The patcher handles the migration automatically, but you may need to review your configuration afterward: @@ -60,7 +29,7 @@ The following modules have been removed or replaced. The patcher handles the mig | `Wysiwyg` removed | Functionality replaced by built-in theme JavaScript. | | `Paidsupport` removed | Module data is cleaned up. | -### Uploads Directory +## Uploads Directory The uploads directory has moved from `/uploads` to `/data/uploads`. Files are migrated automatically. If you have web-server rules referencing the old path, update them: @@ -79,7 +48,7 @@ The bundled `.htaccess` is updated automatically with the new release. If you ma {% /tabitem %} {% /tabs %} -### Template Directory Restructure +## Template Directory Restructure Module templates have been moved from the old `html_*` directory names to a `templates/` structure. Theme directories (`html/` and `html_custom/`) are unchanged. @@ -91,7 +60,7 @@ Module templates have been moved from the old `html_*` directory names to a `tem The patcher removes the old `html_*` directories from modules. If you have custom modules, **update your file structure before applying the patches**, or the old directories will be deleted and you will lose your changes. -### Public Assets +## Public Assets Shared browser assets now live in `/public` instead of `/data/assets` or theme-specific fallback paths: @@ -105,7 +74,15 @@ The patcher migrates bundled gateway icons and default branding settings automat Custom themes should load shared frontend assets with `public_asset_url`, for example `{{ 'js/api.js'|public_asset_url|script_tag }}`. The old `library/Api/API.js` path has been removed. -### Encryption Format Update +## Encryption Format Update Custom payment adapters or modules that store encrypted data using FOSSBilling's encryption may need their data re-encrypted after the update. The patcher (patch 50) handles this migration automatically for core data, but custom implementations should be verified. +## Post-Upgrade Checklist + +- [ ] Review spam/anti-spam settings (`Antispam` module replaces `Spamchecker`) +- [ ] Review active membership orders migrated to custom products +- [ ] Update web-server rules if you have custom NGINX/Apache configs +- [ ] Verify custom modules use the new `templates/` directory structure (custom themes are unaffected) +- [ ] Verify custom themes load shared assets from `/public/assets` with `public_asset_url` +- [ ] Clear the cache: **System → Tools → Clear cache** diff --git a/src/content/docs/maintenance/updating/index.mdoc b/src/content/docs/maintenance/updating/index.mdoc new file mode 100644 index 0000000..d8efc34 --- /dev/null +++ b/src/content/docs/maintenance/updating/index.mdoc @@ -0,0 +1,48 @@ +--- +title: Updating FOSSBilling +description: Keep your FOSSBilling installation up to date with the latest features and security fixes. +sidebar: + label: Overview + order: 1 +--- + +{% aside type="danger" %} +**Always back up first.** Before any update, make full backups of your database and all FOSSBilling files. If something goes wrong, you'll need these to restore your data. +{% /aside %} + +## Automatic Updates (Recommended) + +For most installations, the built-in updater is the easiest option: + +1. Log in to your admin panel +2. Go to **System** → **Update** +3. Click to apply the update + +FOSSBilling downloads and applies the update automatically. It follows the configured update branch, usually `release` or `preview`, which you can change in your [configuration file](/admin-guide/config/). + +## Manual Updates + +If you prefer to manage files yourself: + +1. **Back up your database and files** +2. [Download the latest release](https://fossbilling.org/downloads/stable) +3. Extract the files over your existing installation (overwrite existing files) +4. Delete the `install` folder that came with the new files +5. Log in to the admin panel and go to **System** → **Update** +6. Click **Apply Patches & Update Configuration** + +Always run the patches after copying in new files so the database schema and configuration stay in sync with the codebase. + +If an update fails or FOSSBilling errors after updating, see [Troubleshooting FOSSBilling Issues](/maintenance/troubleshooting/#errors-after-updating). + +## Version-Specific Upgrade Notes + +Some releases need extra review before updating. + +{% cardgrid %} + {% linkcard + title="Upgrading from 0.7.x to 0.8.0" + href="/maintenance/updating/0-7-to-0-8/" + description="Review database, configuration, module, template, and public asset changes before moving to 0.8.0." + /%} +{% /cardgrid %} From 711943271c9206bc5bc98cdf90ce2392018fa155 Mon Sep 17 00:00:00 2001 From: Adam Daley Date: Thu, 28 May 2026 13:29:15 +0100 Subject: [PATCH 03/14] =?UTF-8?q?Add=20updating=20docs=20and=200.7?= =?UTF-8?q?=E2=86=920.8=20upgrade=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../docs/maintenance/Updating/0-7-to-0-8.mdoc | 88 +++++++++++++++++++ .../docs/maintenance/Updating/index.mdoc | 48 ++++++++++ 2 files changed, 136 insertions(+) create mode 100644 src/content/docs/maintenance/Updating/0-7-to-0-8.mdoc create mode 100644 src/content/docs/maintenance/Updating/index.mdoc diff --git a/src/content/docs/maintenance/Updating/0-7-to-0-8.mdoc b/src/content/docs/maintenance/Updating/0-7-to-0-8.mdoc new file mode 100644 index 0000000..465fb7f --- /dev/null +++ b/src/content/docs/maintenance/Updating/0-7-to-0-8.mdoc @@ -0,0 +1,88 @@ +--- +title: Upgrading from 0.7.x to 0.8.0 +description: Version-specific upgrade notes for moving a FOSSBilling 0.7.x installation to 0.8.0. +sidebar: + label: 0.7.x to 0.8.0 + order: 2 +--- + +The 0.8.0 release includes significant database and structural changes. Read the notes below before upgrading. + +## Database & Charset Migration + +The database charset has been migrated from `utf8` to `utf8mb4` / `utf8mb4_unicode_ci`. The patcher handles this automatically. + +## Configuration Changes + +- `db.type` has been renamed to `db.driver` and its value changed from `'mysql'` to `'pdo_mysql'`. The patcher migrates this for you. +- Old `api.rate_*` settings (`rate_span`, `rate_limit`, `throttle_delay`, `rate_span_login`, `rate_limit_login`, `rate_limit_whitelist`) have been replaced by the new `rate_limiter` block. The patcher will prompt you to accept the new defaults. +- The `url` setting no longer stores the protocol prefix; it is stripped on save. + +## Module Migrations + +The following modules have been removed or replaced. The patcher handles the migration automatically, but you may need to review your configuration afterward: + +| Change | Details | +|--------|---------| +| `Servicemembership` removed | Membership products and orders are migrated to the "custom" product type. Review active membership orders after updating. | +| `Spamchecker` replaced | Replaced by the new `Antispam` module (supports honeypot fields). Review your spam-protection settings after the update. | +| `Wysiwyg` removed | Functionality replaced by built-in theme JavaScript. | +| `Paidsupport` removed | Module data is cleaned up. | + +## Uploads Directory + +The uploads directory has moved from `/uploads` to `/data/uploads`. Files are migrated automatically. If you have web-server rules referencing the old path, update them: + +{% tabs %} +{% tabitem label="NGINX" %} +```nginx +# Old rule (0.7.x): +location ~* /uploads/.*\.php$ { return 403; } + +# Updated for 0.8.0: +location ^~ /data/ { return 403; } +``` +{% /tabitem %} +{% tabitem label="Apache (.htaccess)" %} +The bundled `.htaccess` is updated automatically with the new release. If you maintain a custom `.htaccess`, update it to block `/data/` instead of `/uploads/`. +{% /tabitem %} +{% /tabs %} + +## Template Directory Restructure + +Module templates have been moved from the old `html_*` directory names to a `templates/` structure. Theme directories (`html/` and `html_custom/`) are unchanged. + +| Old path | New path | +|----------|----------| +| `modules/{Module}/html_admin/` | `modules/{Module}/templates/admin/` | +| `modules/{Module}/html_client/` | `modules/{Module}/templates/client/` | +| `modules/{Module}/html_email/` | `modules/{Module}/templates/email/` | + +The patcher removes the old `html_*` directories from modules. If you have custom modules, **update your file structure before applying the patches**, or the old directories will be deleted and you will lose your changes. + +## Public Assets + +Shared browser assets now live in `/public` instead of `/data/assets` or theme-specific fallback paths: + +| Asset | New location | +|-------|--------------| +| Gateway icons | `/public/gateways/` | +| Default logo, dark logo, and favicon | `/public/branding/` | +| Shared JavaScript, Markdown CSS, and CKEditor bundles | `/public/assets/` | + +The patcher migrates bundled gateway icons and default branding settings automatically. If you maintain custom web-server rules, make sure `/public` remains publicly readable while `/data` remains blocked. + +Custom themes should load shared frontend assets with `public_asset_url`, for example `{{ 'js/api.js'|public_asset_url|script_tag }}`. The old `library/Api/API.js` path has been removed. + +## Encryption Format Update + +Custom payment adapters or modules that store encrypted data using FOSSBilling's encryption may need their data re-encrypted after the update. The patcher (patch 50) handles this migration automatically for core data, but custom implementations should be verified. + +## Post-Upgrade Checklist + +- [ ] Review spam/anti-spam settings (`Antispam` module replaces `Spamchecker`) +- [ ] Review active membership orders migrated to custom products +- [ ] Update web-server rules if you have custom NGINX/Apache configs +- [ ] Verify custom modules use the new `templates/` directory structure (custom themes are unaffected) +- [ ] Verify custom themes load shared assets from `/public/assets` with `public_asset_url` +- [ ] Clear the cache: **System → Tools → Clear cache** diff --git a/src/content/docs/maintenance/Updating/index.mdoc b/src/content/docs/maintenance/Updating/index.mdoc new file mode 100644 index 0000000..d8efc34 --- /dev/null +++ b/src/content/docs/maintenance/Updating/index.mdoc @@ -0,0 +1,48 @@ +--- +title: Updating FOSSBilling +description: Keep your FOSSBilling installation up to date with the latest features and security fixes. +sidebar: + label: Overview + order: 1 +--- + +{% aside type="danger" %} +**Always back up first.** Before any update, make full backups of your database and all FOSSBilling files. If something goes wrong, you'll need these to restore your data. +{% /aside %} + +## Automatic Updates (Recommended) + +For most installations, the built-in updater is the easiest option: + +1. Log in to your admin panel +2. Go to **System** → **Update** +3. Click to apply the update + +FOSSBilling downloads and applies the update automatically. It follows the configured update branch, usually `release` or `preview`, which you can change in your [configuration file](/admin-guide/config/). + +## Manual Updates + +If you prefer to manage files yourself: + +1. **Back up your database and files** +2. [Download the latest release](https://fossbilling.org/downloads/stable) +3. Extract the files over your existing installation (overwrite existing files) +4. Delete the `install` folder that came with the new files +5. Log in to the admin panel and go to **System** → **Update** +6. Click **Apply Patches & Update Configuration** + +Always run the patches after copying in new files so the database schema and configuration stay in sync with the codebase. + +If an update fails or FOSSBilling errors after updating, see [Troubleshooting FOSSBilling Issues](/maintenance/troubleshooting/#errors-after-updating). + +## Version-Specific Upgrade Notes + +Some releases need extra review before updating. + +{% cardgrid %} + {% linkcard + title="Upgrading from 0.7.x to 0.8.0" + href="/maintenance/updating/0-7-to-0-8/" + description="Review database, configuration, module, template, and public asset changes before moving to 0.8.0." + /%} +{% /cardgrid %} From 1fcc2b78d63feb9944abc8fb3689027dad8c2026 Mon Sep 17 00:00:00 2001 From: Adam Daley Date: Thu, 28 May 2026 13:29:55 +0100 Subject: [PATCH 04/14] Remove duplicate lowercase updating docs --- .../docs/maintenance/updating/0-7-to-0-8.mdoc | 88 ------------------- .../docs/maintenance/updating/index.mdoc | 48 ---------- 2 files changed, 136 deletions(-) delete mode 100644 src/content/docs/maintenance/updating/0-7-to-0-8.mdoc delete mode 100644 src/content/docs/maintenance/updating/index.mdoc diff --git a/src/content/docs/maintenance/updating/0-7-to-0-8.mdoc b/src/content/docs/maintenance/updating/0-7-to-0-8.mdoc deleted file mode 100644 index 465fb7f..0000000 --- a/src/content/docs/maintenance/updating/0-7-to-0-8.mdoc +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Upgrading from 0.7.x to 0.8.0 -description: Version-specific upgrade notes for moving a FOSSBilling 0.7.x installation to 0.8.0. -sidebar: - label: 0.7.x to 0.8.0 - order: 2 ---- - -The 0.8.0 release includes significant database and structural changes. Read the notes below before upgrading. - -## Database & Charset Migration - -The database charset has been migrated from `utf8` to `utf8mb4` / `utf8mb4_unicode_ci`. The patcher handles this automatically. - -## Configuration Changes - -- `db.type` has been renamed to `db.driver` and its value changed from `'mysql'` to `'pdo_mysql'`. The patcher migrates this for you. -- Old `api.rate_*` settings (`rate_span`, `rate_limit`, `throttle_delay`, `rate_span_login`, `rate_limit_login`, `rate_limit_whitelist`) have been replaced by the new `rate_limiter` block. The patcher will prompt you to accept the new defaults. -- The `url` setting no longer stores the protocol prefix; it is stripped on save. - -## Module Migrations - -The following modules have been removed or replaced. The patcher handles the migration automatically, but you may need to review your configuration afterward: - -| Change | Details | -|--------|---------| -| `Servicemembership` removed | Membership products and orders are migrated to the "custom" product type. Review active membership orders after updating. | -| `Spamchecker` replaced | Replaced by the new `Antispam` module (supports honeypot fields). Review your spam-protection settings after the update. | -| `Wysiwyg` removed | Functionality replaced by built-in theme JavaScript. | -| `Paidsupport` removed | Module data is cleaned up. | - -## Uploads Directory - -The uploads directory has moved from `/uploads` to `/data/uploads`. Files are migrated automatically. If you have web-server rules referencing the old path, update them: - -{% tabs %} -{% tabitem label="NGINX" %} -```nginx -# Old rule (0.7.x): -location ~* /uploads/.*\.php$ { return 403; } - -# Updated for 0.8.0: -location ^~ /data/ { return 403; } -``` -{% /tabitem %} -{% tabitem label="Apache (.htaccess)" %} -The bundled `.htaccess` is updated automatically with the new release. If you maintain a custom `.htaccess`, update it to block `/data/` instead of `/uploads/`. -{% /tabitem %} -{% /tabs %} - -## Template Directory Restructure - -Module templates have been moved from the old `html_*` directory names to a `templates/` structure. Theme directories (`html/` and `html_custom/`) are unchanged. - -| Old path | New path | -|----------|----------| -| `modules/{Module}/html_admin/` | `modules/{Module}/templates/admin/` | -| `modules/{Module}/html_client/` | `modules/{Module}/templates/client/` | -| `modules/{Module}/html_email/` | `modules/{Module}/templates/email/` | - -The patcher removes the old `html_*` directories from modules. If you have custom modules, **update your file structure before applying the patches**, or the old directories will be deleted and you will lose your changes. - -## Public Assets - -Shared browser assets now live in `/public` instead of `/data/assets` or theme-specific fallback paths: - -| Asset | New location | -|-------|--------------| -| Gateway icons | `/public/gateways/` | -| Default logo, dark logo, and favicon | `/public/branding/` | -| Shared JavaScript, Markdown CSS, and CKEditor bundles | `/public/assets/` | - -The patcher migrates bundled gateway icons and default branding settings automatically. If you maintain custom web-server rules, make sure `/public` remains publicly readable while `/data` remains blocked. - -Custom themes should load shared frontend assets with `public_asset_url`, for example `{{ 'js/api.js'|public_asset_url|script_tag }}`. The old `library/Api/API.js` path has been removed. - -## Encryption Format Update - -Custom payment adapters or modules that store encrypted data using FOSSBilling's encryption may need their data re-encrypted after the update. The patcher (patch 50) handles this migration automatically for core data, but custom implementations should be verified. - -## Post-Upgrade Checklist - -- [ ] Review spam/anti-spam settings (`Antispam` module replaces `Spamchecker`) -- [ ] Review active membership orders migrated to custom products -- [ ] Update web-server rules if you have custom NGINX/Apache configs -- [ ] Verify custom modules use the new `templates/` directory structure (custom themes are unaffected) -- [ ] Verify custom themes load shared assets from `/public/assets` with `public_asset_url` -- [ ] Clear the cache: **System → Tools → Clear cache** diff --git a/src/content/docs/maintenance/updating/index.mdoc b/src/content/docs/maintenance/updating/index.mdoc deleted file mode 100644 index d8efc34..0000000 --- a/src/content/docs/maintenance/updating/index.mdoc +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Updating FOSSBilling -description: Keep your FOSSBilling installation up to date with the latest features and security fixes. -sidebar: - label: Overview - order: 1 ---- - -{% aside type="danger" %} -**Always back up first.** Before any update, make full backups of your database and all FOSSBilling files. If something goes wrong, you'll need these to restore your data. -{% /aside %} - -## Automatic Updates (Recommended) - -For most installations, the built-in updater is the easiest option: - -1. Log in to your admin panel -2. Go to **System** → **Update** -3. Click to apply the update - -FOSSBilling downloads and applies the update automatically. It follows the configured update branch, usually `release` or `preview`, which you can change in your [configuration file](/admin-guide/config/). - -## Manual Updates - -If you prefer to manage files yourself: - -1. **Back up your database and files** -2. [Download the latest release](https://fossbilling.org/downloads/stable) -3. Extract the files over your existing installation (overwrite existing files) -4. Delete the `install` folder that came with the new files -5. Log in to the admin panel and go to **System** → **Update** -6. Click **Apply Patches & Update Configuration** - -Always run the patches after copying in new files so the database schema and configuration stay in sync with the codebase. - -If an update fails or FOSSBilling errors after updating, see [Troubleshooting FOSSBilling Issues](/maintenance/troubleshooting/#errors-after-updating). - -## Version-Specific Upgrade Notes - -Some releases need extra review before updating. - -{% cardgrid %} - {% linkcard - title="Upgrading from 0.7.x to 0.8.0" - href="/maintenance/updating/0-7-to-0-8/" - description="Review database, configuration, module, template, and public asset changes before moving to 0.8.0." - /%} -{% /cardgrid %} From 3cf15032481fb7c74459a7a1ce1f059d3157ac81 Mon Sep 17 00:00:00 2001 From: Adam Daley Date: Thu, 28 May 2026 13:31:14 +0100 Subject: [PATCH 05/14] Fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- src/content/docs/extensions-and-development/twig-filters.mdoc | 1 + 1 file changed, 1 insertion(+) diff --git a/src/content/docs/extensions-and-development/twig-filters.mdoc b/src/content/docs/extensions-and-development/twig-filters.mdoc index f701df1..c240270 100644 --- a/src/content/docs/extensions-and-development/twig-filters.mdoc +++ b/src/content/docs/extensions-and-development/twig-filters.mdoc @@ -99,6 +99,7 @@ Project-specific filters and functions are defined in these classes: {# Theme and module assets #} +{{ 'js/fossbilling.js'|public_asset_url|script_tag }} {{ 'js/api.js'|public_asset_url|script_tag }} {# API form handled by the shared API wrapper #} From 315ccdd88d818cf30eb2fea5b2cc4006bfbffc60 Mon Sep 17 00:00:00 2001 From: Adam Daley Date: Thu, 28 May 2026 13:33:14 +0100 Subject: [PATCH 06/14] Asset example and remove checklist --- src/content/docs/maintenance/Updating/0-7-to-0-8.mdoc | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) diff --git a/src/content/docs/maintenance/Updating/0-7-to-0-8.mdoc b/src/content/docs/maintenance/Updating/0-7-to-0-8.mdoc index 465fb7f..2a82c6e 100644 --- a/src/content/docs/maintenance/Updating/0-7-to-0-8.mdoc +++ b/src/content/docs/maintenance/Updating/0-7-to-0-8.mdoc @@ -72,17 +72,8 @@ Shared browser assets now live in `/public` instead of `/data/assets` or theme-s The patcher migrates bundled gateway icons and default branding settings automatically. If you maintain custom web-server rules, make sure `/public` remains publicly readable while `/data` remains blocked. -Custom themes should load shared frontend assets with `public_asset_url`, for example `{{ 'js/api.js'|public_asset_url|script_tag }}`. The old `library/Api/API.js` path has been removed. +Custom themes should load shared frontend assets with `public_asset_url`, for example `{{ 'js/fossbilling.js'|public_asset_url|script_tag }}` followed by `{{ 'js/api.js'|public_asset_url|script_tag }}`. The old `library/Api/API.js` path has been removed. ## Encryption Format Update Custom payment adapters or modules that store encrypted data using FOSSBilling's encryption may need their data re-encrypted after the update. The patcher (patch 50) handles this migration automatically for core data, but custom implementations should be verified. - -## Post-Upgrade Checklist - -- [ ] Review spam/anti-spam settings (`Antispam` module replaces `Spamchecker`) -- [ ] Review active membership orders migrated to custom products -- [ ] Update web-server rules if you have custom NGINX/Apache configs -- [ ] Verify custom modules use the new `templates/` directory structure (custom themes are unaffected) -- [ ] Verify custom themes load shared assets from `/public/assets` with `public_asset_url` -- [ ] Clear the cache: **System → Tools → Clear cache** From e8f24f7e08c7e9208cec8389dbe70e022d3435f9 Mon Sep 17 00:00:00 2001 From: Adam Daley Date: Thu, 28 May 2026 13:35:53 +0100 Subject: [PATCH 07/14] Force Astro content cache rebuild --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 226d6f1..05aac28 100644 --- a/package.json +++ b/package.json @@ -6,7 +6,7 @@ "dev": "astro dev", "start": "astro dev", "check": "astro check", - "build": "astro build", + "build": "astro build --force", "preview": "astro preview", "astro": "astro", "format": "prettier --write \"{src,public}/**/*.{astro,css,js,json,mjs,ts}\" \"*.{json,mjs,ts}\"", From a79ed2a2fb627c3474751b8494aaca45cf818ee6 Mon Sep 17 00:00:00 2001 From: Adam Daley Date: Thu, 28 May 2026 13:52:25 +0100 Subject: [PATCH 08/14] Add 0.8.0 banner and New badge --- src/content/docs/index.mdoc | 5 +++++ src/content/docs/maintenance/Updating/0-7-to-0-8.mdoc | 2 ++ 2 files changed, 7 insertions(+) diff --git a/src/content/docs/index.mdoc b/src/content/docs/index.mdoc index 9c7df6a..6b317ad 100644 --- a/src/content/docs/index.mdoc +++ b/src/content/docs/index.mdoc @@ -2,6 +2,11 @@ title: Introduction description: Learn what FOSSBilling is, where to start, and how to get involved with the project. tableOfContents: false +banner: + content: | + 0.8.0 is here! Check out the + release notes + and upgrade guide for details. --- FOSSBilling (*FOSS*: Free and Open Source Software) is a billing and client management solution for hosting providers and digital service businesses. diff --git a/src/content/docs/maintenance/Updating/0-7-to-0-8.mdoc b/src/content/docs/maintenance/Updating/0-7-to-0-8.mdoc index 2a82c6e..a85b8db 100644 --- a/src/content/docs/maintenance/Updating/0-7-to-0-8.mdoc +++ b/src/content/docs/maintenance/Updating/0-7-to-0-8.mdoc @@ -4,6 +4,8 @@ description: Version-specific upgrade notes for moving a FOSSBilling 0.7.x insta sidebar: label: 0.7.x to 0.8.0 order: 2 + badge: + text: New --- The 0.8.0 release includes significant database and structural changes. Read the notes below before upgrading. From 7b2fbedcd80d439bec57dce39e85c045dba8a9f2 Mon Sep 17 00:00:00 2001 From: Adam Daley Date: Thu, 28 May 2026 15:07:16 +0100 Subject: [PATCH 09/14] Docs: Update upgrade notes for 0.8.0 --- src/content/docs/getting-started/docker.mdoc | 3 +- .../docs/maintenance/Updating/0-7-to-0-8.mdoc | 353 +++++++++++++++++- .../docs/maintenance/Updating/index.mdoc | 6 +- src/content/docs/maintenance/changelog.mdoc | 7 +- 4 files changed, 360 insertions(+), 9 deletions(-) diff --git a/src/content/docs/getting-started/docker.mdoc b/src/content/docs/getting-started/docker.mdoc index 7edc337..6a760c8 100644 --- a/src/content/docs/getting-started/docker.mdoc +++ b/src/content/docs/getting-started/docker.mdoc @@ -32,8 +32,7 @@ Then open your server IP or hostname in a browser to complete the web installer. {% tabitem label="Docker Compose" %} This option brings up FOSSBilling and MySQL together, which makes it the fastest way to get started. -```yaml -version: "3.9" +```yaml {% meta="title='docker-compose.yml'" %} services: fossbilling: image: fossbilling/fossbilling:latest diff --git a/src/content/docs/maintenance/Updating/0-7-to-0-8.mdoc b/src/content/docs/maintenance/Updating/0-7-to-0-8.mdoc index a85b8db..743bd0b 100644 --- a/src/content/docs/maintenance/Updating/0-7-to-0-8.mdoc +++ b/src/content/docs/maintenance/Updating/0-7-to-0-8.mdoc @@ -8,7 +8,15 @@ sidebar: text: New --- -The 0.8.0 release includes significant database and structural changes. Read the notes below before upgrading. +The 0.8.0 release includes significant database, structural, and frontend changes. Read every section below before upgrading. + +{% aside type="caution" %} +**Review custom themes and modules carefully.** 0.8.0 removes jQuery, switches from Webpack Encore to esbuild, replaces the routing layer with Symfony HttpKernel, and introduces multiple Twig filter removals and renames. Custom code that depends on the old infrastructure will break. +{% /aside %} + +## PHP Requirement + +The minimum PHP version has been raised from 8.1 to **8.3**. Verify your server meets this requirement before upgrading. ## Database & Charset Migration @@ -19,6 +27,9 @@ The database charset has been migrated from `utf8` to `utf8mb4` / `utf8mb4_unico - `db.type` has been renamed to `db.driver` and its value changed from `'mysql'` to `'pdo_mysql'`. The patcher migrates this for you. - Old `api.rate_*` settings (`rate_span`, `rate_limit`, `throttle_delay`, `rate_span_login`, `rate_limit_login`, `rate_limit_whitelist`) have been replaced by the new `rate_limiter` block. The patcher will prompt you to accept the new defaults. - The `url` setting no longer stores the protocol prefix; it is stripped on save. +- New `security.trusted_proxies` block for configuring reverse proxy trust. +- New `security.session_regeneration_grace_period` setting (default: 300). +- New `i18n.auto_detect_locale`, `i18n.date_format`, `i18n.time_format`, `i18n.datetime_pattern` settings. ## Module Migrations @@ -27,9 +38,11 @@ The following modules have been removed or replaced. The patcher handles the mig | Change | Details | |--------|---------| | `Servicemembership` removed | Membership products and orders are migrated to the "custom" product type. Review active membership orders after updating. | -| `Spamchecker` replaced | Replaced by the new `Antispam` module (supports honeypot fields). Review your spam-protection settings after the update. | -| `Wysiwyg` removed | Functionality replaced by built-in theme JavaScript. | +| `Spamchecker` replaced | Replaced by the new `Antispam` module (supports Cloudflare Turnstile, hCaptcha, and honeypot fields). Review your spam-protection settings after the update. | +| `Wysiwyg` removed | CKEditor 5 is now integrated directly into themes. Use the `wysiwyg` Twig function to initialize editors. | | `Paidsupport` removed | Module data is cleaned up. | +| Added `Antispam` | New spam-prevention module with multiple challenge providers. | +| Added `Widgets` | New module for registering renderable widget slots in templates. | ## Uploads Directory @@ -74,7 +87,339 @@ Shared browser assets now live in `/public` instead of `/data/assets` or theme-s The patcher migrates bundled gateway icons and default branding settings automatically. If you maintain custom web-server rules, make sure `/public` remains publicly readable while `/data` remains blocked. -Custom themes should load shared frontend assets with `public_asset_url`, for example `{{ 'js/fossbilling.js'|public_asset_url|script_tag }}` followed by `{{ 'js/api.js'|public_asset_url|script_tag }}`. The old `library/Api/API.js` path has been removed. +## Theme & Frontend Changes + +### Build System: Webpack Encore → esbuild + +The front-end build system has been migrated from [Webpack Encore](https://symfony.com/doc/current/frontend.html) to [esbuild](https://esbuild.github.io/). + +- Bundled theme `package.json` scripts now call local `esbuild.mjs` files instead of Webpack Encore. Huraga's `dev` script uses `node ./esbuild.mjs --watch`; `admin_default` uses `node ./esbuild.mjs` for both `dev` and `build`. +- Shared build helpers are in `frontend/tools/esbuild-helpers.mjs` (at the repository root). +- Theme-specific build scripts are at `src/themes/{theme}/esbuild.mjs`. + +If you maintain a custom theme with its own build pipeline, update it for the new asset structure and Twig loading pattern. You can keep another build tool if it outputs compatible assets, but the bundled `huraga` and `admin_default` themes now use esbuild and are the best reference implementations. + +### Asset Loading + +Replace `encore_entry_link_tags` / `encore_entry_script_tags` with direct CSS and JS asset tags: + +{% tabs %} +{% tabitem label="Before (0.7.x)" %} +```twig +{{ encore_entry_link_tags('fossbilling') }} +{{ "Api/API.js" | library_url | script_tag }} +{{ encore_entry_script_tags('fossbilling') }} +``` +{% /tabitem %} +{% tabitem label="After (0.8.0)" %} +```twig + + +{{ 'js/fossbilling.js' | public_asset_url | script_tag }} +{{ 'js/api.js' | public_asset_url | script_tag }} + +``` +{% /tabitem %} +{% /tabs %} + +### jQuery Removed + +jQuery has been removed from both bundled themes. All admin and client templates have been migrated to vanilla JavaScript. + +- The old `bb` JavaScript object and `bb.redirect()` no longer exist. Use `window.location` instead. +- `$(function() { ... })` → `document.addEventListener("DOMContentLoaded", function() { ... })` +- Any custom theme or module JavaScript that depends on jQuery must be rewritten. + +### JavaScript API Wrapper + +The JS API wrapper has been rewritten and moved from `library/Api/API.js` to `frontend/core/api.js`. The browser call pattern (`API.admin.post`, `API.client.get`, `API.guest.get`, etc.) remains compatible, and the related Twig helpers (`fb_api_form`, `fb_api_link`) are still available, but the internal implementation is entirely new. + +Load it with: +```twig +{{ 'js/fossbilling.js' | public_asset_url | script_tag }} +{{ 'js/api.js' | public_asset_url | script_tag }} +``` + +The old `library_url` filter used for `{{ "Api/API.js" | library_url | script_tag }}` has been removed. + +### Frontend Directory Structure + +Shared frontend source code has moved to a new `frontend/` directory at the repository root: + +``` +frontend/ +├── core/ +│ ├── api.js # JavaScript API wrapper +│ └── fossbilling.js # Runtime helpers (message toasts, request utilities) +├── editor/ +│ └── ckeditor.js # CKEditor 5 bundle +├── styles/ +│ └── markdown.css # Markdown content styling +└── tools/ + └── esbuild-helpers.mjs # Shared build utilities +``` + +### Debug Bar + +The `DebugBar_renderHead()` Twig function has been renamed to `debug_bar_render_head()`: + +{% tabs %} +{% tabitem label="Before (0.7.x)" %} +```twig +{{ DebugBar_renderHead() }} +``` +{% /tabitem %} +{% tabitem label="After (0.8.0)" %} +```twig +{{ debug_bar_render_head() }} +``` +{% /tabitem %} +{% /tabs %} + +### CSRF Meta Tag Removed + +The `` tag has been removed from bundled themes. CSRF tokens are now sent via cookie (`csrf_token`) and handled automatically by the JavaScript API wrapper. If your custom theme relies on the meta tag, switch to reading the cookie: + +```javascript +const token = document.cookie.match(/csrf_token=([^;]*)/)?.[1] || ''; +``` + +Build output is written to theme/public asset directories such as `src/public/assets`, not to a tracked `frontend/build` directory. + +### Twig Globals + +Available Twig globals to review when updating custom templates include: + +| Global | Description | +|--------|-------------| +| `app_area` | `"admin"` or `"client"` | +| `current_theme` | The active theme code | +| `request` | Query parameters from the current request | +| `request_query` | Original query parameters array | +| `request_path` | Normalized route path | +| `request_has_filters` | Boolean indicating active filters in the request | +| `default_currency` | The default currency code | +| `FOSSBillingVersion` | The current version string | + +### Twig Filter Changes + +The following filters have been **removed**: + +| Removed filter | Replacement | +|----------------|-------------| +| `alink` | `url` with `area: 'admin'` — `{{ 'staff/login' \| url({area: 'admin'}) }}` | +| `link` | `url` — `{{ 'order' \| url }}` | +| `gravatar` | `avatar` function — `{{ avatar(email, 80) }}` (uses DiceBear locally) | +| `library_url` | `public_asset_url` | +| `markdown` | `markdown_to_html` — `{{ content \| markdown_to_html }}` | +| `size` | `file_size` — `{{ 1048576 \| file_size }}` | +| `number` | `format_number` (from Twig Intl Extra) | +| `money` / `money_without_currency` | `format_currency` — `{{ 29.99 \| format_currency('USD') }}` | +| `money_convert` / `money_convert_without_currency` | No direct Twig filter replacement. Convert the amount before rendering, then format it with `format_currency`. | +| `img_tag` | Use standard `` HTML | +| `iplookup` | Removed. | +| `ipcountryname` | Renamed to `ip_country_name` | +| `autolink` | Removed. | + +The following filters and functions have been **added**: + +| New filter/function | Description | +|---------------------|-------------| +| `public_asset_url` | URL for shared core assets in `/public` | +| `url` | Now accepts `area` parameter (`'admin'` / `'client'`) to replace both old `alink` and `link` | +| `has_permission` | Check admin module permission in templates | +| `render_widgets` | Render widgets for a named slot | +| `svg_sprite` | Render the theme's SVG icon sprite | +| `antispam_honeypot` | Return honeypot configuration array | +| `wysiwyg` | Initialize CKEditor 5 on a textarea selector | +| `avatar` | Generate DiceBear avatar image for an email address | +| `script_tag` | Generate `