Upgrading from 1.8.x to 2.0.x

SourceBans++ 2.0.0 is a major version bump. This page covers what changes between 1.8.x and 2.0.x and the prep work an admin should do before running the panel updater. The general upgrade flow (back up, upload, visit /updater/) is the same as any other version — see Updating SourceBans++ for that.

The three things to know about the v2.0 upgrade:

1. The PHP version floor moves up to 8.5. Check your host first.
2. The active theme resets to default. Custom themes need porting before re-enabling.
3. Anonymous telemetry ships on by default. Opt-out is one click.

Back up your database first

The updater scripts are idempotent, but a half-completed upload is much easier to recover from when you have a snapshot to roll back to. Always take a DB dump before you start.

PHP version + new dependencies

v2.0.0 raises the PHP requirement to 8.5 (up from 1.8.x’s 8.2) and pulls in several new Composer dependencies. A 1.8.x install that has a vendor/ directory left over from a prior composer install will pass the panel’s autoload check but fatal at runtime the first time v2.0 code references a class the old vendor/ doesn’t have — usually mid-page, with the Class "…" not found line buried in your PHP error log.

What’s new:

• php >= 8.5 — upgrade your host’s PHP before uploading the v2.0 files. A panel on PHP 8.4 or earlier won’t boot.
• symfony/mailer ^7.2 — replaced 1.8.x’s PHPMailer.
• league/commonmark ^2.5 — added so admin-authored Markdown on the dashboard intro text renders safely.
• lcobucci/jwt ^5.0 — major-bumped from 1.8.x.
• smarty/smarty ^v5.4 — major-bumped from 1.8.x.

Tarball install (the easy path)

Release tarballs ship a fresh web/includes/vendor/, so tarball upgrades work out of the box. Upload, visit /updater/, done.

Git checkout

If you installed from a git clone or git pull of the main branch, the old vendor/ is still in place. Run composer install from the panel root before you visit /updater/:

cd /path/to/sourcebans/web
composer install --no-dev --optimize-autoloader

If you missed this step and the panel is fataling on 500s, composer install from the panel root will get you back to a working state without losing data.

Theme reset

v2.0.0 is a complete chrome rewrite — new typed View DTOs, new admin sidebar layout, every template signature changed, MooTools and xajax are gone, the openTab() JS helper is deleted. A fork theme inherited from a 1.8.x install does not have the templates v2.0 expects. Best case: Smarty: Unable to load template … errors. Worst case: Smarty falls through to a half-rendered page where every template variable is undefined.

To keep the panel actually loadable after the upgrade, the v2.0 updater resets config.theme back to default automatically. No operator action is required.

If you maintain a fork theme:

1. After upgrading, the panel will be on default.

2. Port your fork against the v2.0 default theme — diff web/themes/default/ between the 1.8.x and 2.0 trees to see what changed. The new conventions live in AGENTS.md (typed View DTOs, the ?section=… admin sub-route pattern, the core/admin_sidebar.tpl partial, empty-state classes in theme.css).

3. Once your fork ships v2.0-shaped templates, re-select it from Admin Panel → Settings → Themes. The DB-side reset is a one-shot at upgrade time — the panel won’t flip back to default on its own.

Your fork directory under web/themes/<fork>/ is left in place — only the :prefix_settings.config.theme row is rewritten. Your work isn’t lost; the panel just stops trying to render against templates that don’t exist (yet).

Anonymous telemetry

SourceBans++ 2.0.0 ships with anonymous telemetry on by default. This is new behaviour for installs upgrading from 1.x; the rest of this section covers what it sends and how to opt out.

What’s sent

Once per day per install, the panel sends an anonymous JSON payload to a SourceBans++ Cloudflare Worker. The payload covers four categories:

• panel — version, short git SHA, dev flag, theme name (only default or custom is reported — fork theme names are never sent).
• env — PHP major.minor, DB engine + major.minor, web server family, OS family.
• scale — counts of admins, enabled servers, active and total bans / comm blocks, 30-day submission / protest counts.
• features — every checkbox under Admin Panel → Settings → Features, plus three derived booleans: SMTP-configured, Steam API key set, GeoIP DB present.

A random 32-char hex instance_id is included so pings can be deduplicated.

What is never sent

• Hostnames, IPs, install paths.
• Admin names, SteamIDs, ban reasons.
• Dashboard text, server hostnames, server IPs, MOTDs.
• SMTP credentials, the Steam API key value.

The complete field list lives in the source at web/includes/Telemetry/schema-1.lock.json.

How to opt out

1. Sign in as an admin with Owner or Web settings permissions.
2. Navigate to Admin Panel → Settings → Features.
3. Uncheck Anonymous telemetry under the Privacy card.
4. Click Save changes.

Opting out also clears the per-install random ID. Re-enabling later issues a fresh ID so the collector can never link the two states.

Self-hosted collector

The endpoint URL lives in :prefix_settings.telemetry.endpoint (default https://cf-analytics-telemetry.sbpp.workers.dev/v1/ping). To point the panel at your own collector:

UPDATE sb_settings
SET value = 'https://your-collector.example.com/v1/ping'
WHERE setting = 'telemetry.endpoint';

Setting the value to the empty string disables network calls without flipping the user-facing toggle. There’s no UI for this knob — it’s a debug / escape-hatch surface. The Worker source lives at sbpp/cf-analytics for operators who want to inspect or fork the collector.

Performance impact

Effectively zero on PHP-FPM (the common case).

The telemetry tick runs in a register_shutdown_function callback. On PHP-FPM, fastcgi_finish_request() closes the user’s TCP socket before the cURL POST runs, so a panel response time of N ms remains N ms regardless of telemetry. The cURL call has 3-second connect / 5-second total timeouts and is silent on failure — telemetry can never hard-fail a panel page or a JSON API request.