You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/content/docs/maintenance/Updating/0-7-to-0-8.mdoc
+349-4Lines changed: 349 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -8,7 +8,15 @@ sidebar:
8
8
text: New
9
9
---
10
10
11
-
The 0.8.0 release includes significant database and structural changes. Read the notes below before upgrading.
11
+
The 0.8.0 release includes significant database, structural, and frontend changes. Read every section below before upgrading.
12
+
13
+
{% aside type="caution" %}
14
+
**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.
15
+
{% /aside %}
16
+
17
+
## PHP Requirement
18
+
19
+
The minimum PHP version has been raised from 8.1 to **8.3**. Verify your server meets this requirement before upgrading.
12
20
13
21
## Database & Charset Migration
14
22
@@ -19,6 +27,9 @@ The database charset has been migrated from `utf8` to `utf8mb4` / `utf8mb4_unico
19
27
- `db.type` has been renamed to `db.driver` and its value changed from `'mysql'` to `'pdo_mysql'`. The patcher migrates this for you.
20
28
- 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.
21
29
- The `url` setting no longer stores the protocol prefix; it is stripped on save.
30
+
- New `security.trusted_proxies` block for configuring reverse proxy trust.
31
+
- New `security.session_regeneration_grace_period` setting (default: 300).
32
+
- New `i18n.auto_detect_locale`, `i18n.date_format`, `i18n.time_format`, `i18n.datetime_pattern` settings.
22
33
23
34
## Module Migrations
24
35
@@ -27,9 +38,11 @@ The following modules have been removed or replaced. The patcher handles the mig
27
38
| Change | Details |
28
39
|--------|---------|
29
40
| `Servicemembership` removed | Membership products and orders are migrated to the "custom" product type. Review active membership orders after updating. |
30
-
| `Spamchecker` replaced | Replaced by the new `Antispam` module (supports honeypot fields). Review your spam-protection settings after the update. |
| `Spamchecker` replaced | Replaced by the new `Antispam` module (supports Cloudflare Turnstile, hCaptcha, and honeypot fields). Review your spam-protection settings after the update. |
42
+
| `Wysiwyg` removed | CKEditor 5 is now integrated directly into themes. Use the `wysiwyg` Twig function to initialize editors. |
32
43
| `Paidsupport` removed | Module data is cleaned up. |
44
+
| Added `Antispam` | New spam-prevention module with multiple challenge providers. |
45
+
| Added `Widgets` | New module for registering renderable widget slots in templates. |
33
46
34
47
## Uploads Directory
35
48
@@ -74,7 +87,339 @@ Shared browser assets now live in `/public` instead of `/data/assets` or theme-s
74
87
75
88
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.
76
89
77
-
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.
90
+
## Theme & Frontend Changes
91
+
92
+
### Build System: Webpack Encore → esbuild
93
+
94
+
The front-end build system has been migrated from [Webpack Encore](https://symfony.com/doc/current/frontend.html) to [esbuild](https://esbuild.github.io/).
95
+
96
+
- 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`.
97
+
- Shared build helpers are in `frontend/tools/esbuild-helpers.mjs` (at the repository root).
98
+
- Theme-specific build scripts are at `src/themes/{theme}/esbuild.mjs`.
99
+
100
+
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.
101
+
102
+
### Asset Loading
103
+
104
+
Replace `encore_entry_link_tags` / `encore_entry_script_tags` with direct CSS and JS asset tags:
- Any custom theme or module JavaScript that depends on jQuery must be rewritten.
132
+
133
+
### JavaScript API Wrapper
134
+
135
+
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.
The `DebugBar_renderHead()` Twig function has been renamed to `debug_bar_render_head()`:
165
+
166
+
{% tabs %}
167
+
{% tabitem label="Before (0.7.x)" %}
168
+
```twig
169
+
{{ DebugBar_renderHead() }}
170
+
```
171
+
{% /tabitem %}
172
+
{% tabitem label="After (0.8.0)" %}
173
+
```twig
174
+
{{ debug_bar_render_head() }}
175
+
```
176
+
{% /tabitem %}
177
+
{% /tabs %}
178
+
179
+
### CSRF Meta Tag Removed
180
+
181
+
The `<meta name="csrf-token" content="{{ CSRFToken }}">` 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:
| `money_convert` / `money_convert_without_currency` | No direct Twig filter replacement. Convert the amount before rendering, then format it with `format_currency`. |
219
+
| `img_tag` | Use standard `<img>` HTML |
220
+
| `iplookup` | Removed. |
221
+
| `ipcountryname` | Renamed to `ip_country_name` |
222
+
| `autolink` | Removed. |
223
+
224
+
The following filters and functions have been **added**:
225
+
226
+
| New filter/function | Description |
227
+
|---------------------|-------------|
228
+
| `public_asset_url` | URL for shared core assets in `/public` |
229
+
| `url` | Now accepts `area` parameter (`'admin'` / `'client'`) to replace both old `alink` and `link` |
230
+
| `has_permission` | Check admin module permission in templates |
231
+
| `render_widgets` | Render widgets for a named slot |
232
+
| `svg_sprite` | Render the theme's SVG icon sprite |
| `wysiwyg` | Initialize CKEditor 5 on a textarea selector |
235
+
| `avatar` | Generate DiceBear avatar image for an email address |
236
+
| `script_tag` | Generate `<script>` tag with cache-busting hash |
237
+
| `stylesheet_tag` | Generate `<link>` stylesheet tag with cache-busting hash |
238
+
| `file_size` | Format bytes to human-readable size (replaces `size`) |
239
+
| `hash` | Hash a value (defaults to xxh128) |
240
+
| `api_url` | Supports `role` parameter to override the API area |
241
+
242
+
### Theme HTML Changes
243
+
244
+
Key template changes in both bundled themes (admin_default and huraga):
245
+
246
+
- `<html lang="en">` → `<html lang="{{ active_locale }}">` where `active_locale` is derived from the active locale.
247
+
- `<meta property="bb:url">` and `<meta property="bb:client_area">` removed.
248
+
- `<meta name="csrf-token">` removed (see CSRF section above).
249
+
- `encore_entry_link_tags` / `encore_entry_script_tags` → direct asset links (see above).
250
+
- Old admin redirect `bb.redirect(...)` → `window.location = ...`.
251
+
- The `macro_functions.html.twig` import removed from layout files; macros are now loaded individually.
252
+
- Language selectors use `js-locale-selector` class instead of `js-language-selector`.
253
+
- New widget slots: `{{ render_widgets('client.theme.body.start') }}` in Huraga.
254
+
- Dashboard cards rewritten with AJAX-loaded content.
255
+
- Tables, pagination, forms, and search have been revamped with new markup and CSS.
256
+
257
+
## Guest API Lockdown
258
+
259
+
The guest API has been hardened to expose less information publicly:
260
+
261
+
- The guest `system/version` API action (`guest.system_version` in Twig) has been **removed** — versions are no longer disclosed to unauthenticated callers.
262
+
- `guest.system_company()` hides extra company fields from unauthenticated callers when the `hide_company_public` setting is enabled.
263
+
- `guest.system_phone_codes()` no longer accepts a `country` parameter for single-code lookups; it returns all codes.
264
+
- `guest.support_ticket_create()` now requires `name`, `email`, `subject`, and `message` parameters through the `RequiredParams` attribute. Rate limiting is enforced.
265
+
- Messages submitted via guest ticket creation are now sanitized to prevent XSS.
266
+
267
+
If your integration depends on any of these guest endpoints, update accordingly.
268
+
269
+
## Architecture & Module Development Changes
270
+
271
+
### Symfony HttpKernel Routing
272
+
273
+
The custom HTTP and routing layer (`Box_App`, `Box_AppAdmin`, `Box_AppClient`) has been replaced by Symfony's HttpKernel, HttpFoundation, and Routing components.
274
+
275
+
- `Box_App` still exists and exposes `$app->get()`, `$app->post()`, `$app->render()` for backward compatibility in module controllers.
276
+
- `Box_App::run()` now returns a `Symfony\Component\HttpFoundation\Response` instead of a string.
277
+
- `Box_App::show404()` returns a `Response` object instead of echoing and exiting.
278
+
- Module controllers can return `Response` objects directly.
279
+
- New `HttpResponseException` allows aborting with a response from anywhere in the call stack.
280
+
- `RequestFactory` normalizes route paths from Symfony's `Request` object.
281
+
282
+
### Box_Mod → FOSSBilling\Module
283
+
284
+
The `Box_Mod` class has been reworked into `FOSSBilling\Module`:
285
+
286
+
{% tabs %}
287
+
{% tabitem label="Before (0.7.x)" %}
288
+
```php
289
+
$mod = new Box_Mod('Example');
290
+
```
291
+
{% /tabitem %}
292
+
{% tabitem label="After (0.8.0)" %}
293
+
```php
294
+
$mod = new FOSSBilling\Module('Example');
295
+
```
296
+
{% /tabitem %}
297
+
{% /tabs %}
298
+
299
+
The new class uses Symfony Filesystem/Path components internally and supports additional methods like `hasSettingsPage()`, `hasClientController()`, and `hasAdminController()`.
300
+
301
+
### Paginator Changes
302
+
303
+
Legacy global paginator usage should be replaced with `FOSSBilling\Paginator` (metadata only) and `FOSSBilling\Pagination` (Doctrine-backed data retrieval):
304
+
305
+
{% tabs %}
306
+
{% tabitem label="Before (0.7.x)" %}
307
+
```php
308
+
$p = new \Box_Paginator($itemsCount, $currentPage, $limit, $midRange);
309
+
```
310
+
{% /tabitem %}
311
+
{% tabitem label="After (0.8.0)" %}
312
+
```php
313
+
$p = new \FOSSBilling\Paginator($itemsCount, $currentPage, $limit, $midRange);
314
+
$p->toArray(); // Same output format
315
+
```
316
+
{% /tabitem %}
317
+
{% /tabs %}
318
+
319
+
For Doctrine-backed pagination, use `FOSSBilling\Pagination` with `PaginationOptions`:
- `FOSSBilling\Twig\Extension\DebugBarExtension` — Debug bar integration.
349
+
- `FOSSBilling\Twig\EmailPolicy` / `FOSSBilling\Twig\AdapterPolicy` — Sandbox policies for email and adapter templates.
350
+
- `FOSSBilling\Twig\SandboxedStringRenderer` — Sandboxed rendering for user-provided template strings.
351
+
352
+
The old `Box_TwigExtensions` and `Box_TwigLoader` classes have been removed.
353
+
354
+
## Gravatar Removed
355
+
356
+
Gravatar has been removed. User avatars are now generated locally using DiceBear. The `gravatar` Twig filter no longer exists; use the `avatar` function instead:
357
+
358
+
```twig
359
+
{{ avatar(email, 80) }}
360
+
```
361
+
362
+
## Honeypot Enabled by Default
363
+
364
+
The new Antispam module enables honeypot spam prevention by default for supported forms such as signup. If you have custom signup or public submission forms, use the `antispam_honeypot` function to include honeypot fields:
The old `api.rate_*` configuration settings have been replaced by a centralized `rate_limiter` block:
376
+
377
+
```php
378
+
'rate_limiter'=>[
379
+
'enabled' => true,
380
+
'whitelist_ips' => [],
381
+
// Override individual policies as needed
382
+
],
383
+
```
384
+
385
+
The rate limiter is now enforced on guest ticket creation and other public endpoints. Policies are defined in `FOSSBilling\Security\RateLimiter::getDefaultConfig()`.
386
+
387
+
## Widget System
388
+
389
+
0.8.0 introduces a new widget system for rendering dynamic content in template slots. Use `render_widgets` in your theme templates:
390
+
391
+
```twig
392
+
{{ render_widgets('client.theme.body.start') }}
393
+
{{ render_widgets('client.theme.body.end') }}
394
+
```
395
+
396
+
Widgets are registered by modules and can be created by implementing the `WidgetProviderInterface`.
397
+
398
+
## Email Templates
399
+
400
+
File-backed email templates are now supported in addition to the database-stored templates. The email Twig environment is now sandboxed for security, restricting available filters and globals.
401
+
402
+
## Deprecations & Removals (Summary)
403
+
404
+
| Component | Status | Notes |
405
+
|-----------|--------|-------|
406
+
| `Box_Mod` | Removed | Replaced by `FOSSBilling\Module` |
407
+
| `Box_Paginator` | Removed | Replaced by `FOSSBilling\Paginator` |
0 commit comments