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 five things to know about the v2.0 upgrade:

The PHP version floor moves up to 8.5. Check your host first.
The active theme resets to default. Custom themes need porting before re-enabling.
Anonymous telemetry ships on by default. Opt-out is one click.
A daily project-announcements feed also ships on by default for logged-in admins. Opt-out is a one-line config.php define.
The web panel licence has changed from CC BY-NC-SA 3.0 to the Elastic License 2.0. Hobby and community use stays free; offering the panel as a hosted or managed service to third parties now requires a separate commercial licence. SourceMod plugins remain GPLv3. See Licence change below.

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:

After upgrading, the panel will be on default.
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).
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

Sign in as an admin with Owner or Web settings permissions.
Navigate to Admin Panel → Settings → Features.
Uncheck Anonymous telemetry under the Privacy card.
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. 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.

Project announcements feed

SourceBans++ 2.0.0 also adds a small admin-only announcements strip to the home dashboard. Once a day per install, the panel fetches https://sbpp.github.io/announcements.json (a static file the maintainers publish from this repo's docs/public/ directory) and renders the freshest non-expired entry as a slim <details> strip between the dashboard's stat cards and activity panels. Anonymous viewers and non-admin users never see the strip.

This is a second always-on outbound channel in addition to telemetry. Like telemetry, it ships on by default and is opt-out-by-config. The two channels are separate: telemetry is a write-only push (panel → collector), announcements is a read-only pull (panel ← static JSON). Neither can affect the other; opting out of one leaves the other running.

What's sent

The GET request carries:

User-Agent: SourceBans++/<version> (announcements): same shape as the existing system.check_version release-check fetch.
Standard HTTP headers added by PHP's stream wrapper.

Specifically not sent:

No instance ID, no per-install random.
No cookies, no Referer, no query string, no POST body.
Nothing the panel pulls from sb_settings or any other table.

The audit trail is the file in this repo at docs/public/announcements.json. Every announcement is a git commit before it lands on your dashboard, so operators can review the full history before the deploy chain ships it to sbpp.github.io.

How to opt out

There's no in-panel toggle. Add this line to your web/config.php:

define('SB_ANNOUNCEMENTS_URL', '');

The empty string is the documented air-gap escape hatch. The panel skips the daily fetch entirely and the dashboard renders without the strip. See the announcements feature page for the full reference (self-hosted mirror, scheme guard, cache behaviour).

Performance impact

Same shape as telemetry: zero on PHP-FPM.

The announcements tick runs in register_shutdown_function. fastcgi_finish_request() closes the user's TCP socket before the upstream fetch runs, so the user-perceived response time is unaffected. The fetch has a 5-second total timeout, a 256 KiB hard cap on the response body, stale-while-error caching, and is silent on failure. A flapping sbpp.github.io can never hard-fail a panel page.

Plugin authors

SourceBans++ 2.0.0 aligns the public header with the 2.0 release (SOURCEBANSPP_VERSION_MAJOR = 2; SOURCEBANSPP_VERSION_MINOR is the native API additive revision, not the panel's semver minor; SB_VERSION is stamped at compile time from release tag → configs/version.json → git describe → dev). That is a version epoch marker, not a signal that every third-party plugin must be recompiled.

If you compile plugins from a git checkout, run game/addons/sourcemod/scripting/scripts/resolve-plugin-version.sh before spcomp so sbpp_version.inc matches your tree (the repo ships a dev fallback so a bare compile still works).

You do not need to rebuild if your plugin only uses APIs that already existed on the 1.x line (for example SBPP_BanPlayer, SBPP_OnBanPlayer, SBPP_OnReportPlayer) and you are not detecting the checker via LibraryExists / GetFeatureStatus.

Recompile (and redeploy your .smx) when you:

#include <sourcebanschecker> and probe the checker with LibraryExists / GetFeatureStatus — use library name "sourcechecker++", not "sourcebans++" (#1034).
Call SBPP_CheckerGetClientsMutes or SBPP_CheckerGetClientsGags (#1032) — deploy sbpp_checker.smx from this release too.
Want to implement SBPP_OnClientPostAdminCheck (#1431) — additive forward; existing binaries ignore it until you add a hook.

Optional guard when you compile against 2.0 sourcebanspp.inc:

#if SOURCEBANSPP_VERSION_MAJOR != 2
#error Rebuild against SourceBans++ 2.0 sourcebanspp.inc
#endif

Deploy the official 2.0 plugin bundle (sbpp_main.smx, sbpp_comms.smx, sbpp_checker.smx, …) with the panel upgrade. SourceMod 1.12.x matches project CI.

Tracking: #1114.

Licence change

The 1.8.x line shipped the web panel under Creative Commons Attribution-NonCommercial-ShareAlike 3.0 (the CC BY-NC-SA 3.0 you saw referenced in LICENSE.md). v2.0.0 moves the panel to the Elastic License 2.0 (ELv2), a source-available licence whose only restriction is that you can't offer the Software as a hosted or managed service to third parties.

The full text now lives at LICENSE.txt in the panel root. The v1.x LICENSE.md file is gone.

What changes for you in practice

Most installs see no operational change. The matrix:

Running the panel for your own community, clan, or network (the typical self-host): no change. Free use of every kind ELv2 covers — copy, modify, redistribute, bundle into a Docker image, ship a Pterodactyl egg, package for a Linux distro.
Internal use inside a company (a corporate gameserver, a studio QA panel, an esports org's competitive servers): no change. ELv2 only restricts offering the panel to third parties as a managed service. Internal use isn't a third-party-managed-service use case.
Game-server hosting providers offering SourceBans++ to your customers as a hosted panel: this is the use case ELv2 reserves. You need a commercial licence to keep doing this under v2.0.x; see Sponsor / commercial licensing for how to start the conversation. The project doesn't pursue retroactive enforcement against operators upgrading in good faith; reach out before your next billing cycle and the maintainers will work with you.
Forking and redistributing the panel (publishing your own variant on GitHub, shipping a custom theme as part of a tarball): still allowed. ELv2 requires you preserve the licence text and attribution notices (which the release artefacts already ship); the panel makes no other demands on your fork.

Why the change

The v1.x CC BY-NC-SA 3.0 licence had two structural problems for a non-trivially-monetisable codebase: Creative Commons licences explicitly aren't recommended for software (no patent grant, ambiguous treatment of source / object code), and "non-commercial" is famously vague — the NC compatibility chart declines to define "commercial" at all. Practical consequence: every operator wanting to be sure they were on the right side of CC's NC clause had to take their own legal advice, and large hosting providers had no clean path to clear it with their legal teams. ELv2 replaces the wooly NC distinction with a single, explicit "no managed service to third parties" line. Self-hosters get a clearer "yes, this is fine" answer; the project gets a workable legal basis for the long-overdue dual-licensing arrangement that funds further development.

The maintainers' standing under ELv2 to relicense future contributions comes from the Contributor License Agreement contributors sign on PRs touching web/**. The pre-CLA contribution history is covered by the project's pre-CLA contribution audit, which confirmed the project maintainer as the sole significant pre-CLA contributor to the panel.

Files that moved

LICENSE.md (CC BY-NC-SA 3.0 text) was deleted. ELv2 text now lives at LICENSE.txt.
LICENSE-plugins.txt (new): GPLv3 text for the SourceMod plugins, broken out so the two licences are unambiguous.
THIRD-PARTY-NOTICES.txt (new): bundled-third-party attributions (LightOpenID MIT, SourceBans 1.4.x + SourceComms + InterWave Studios theme.conf historical CC BY-NC-SA 3.0).
Every .php / .js / .tpl source-file header was updated from the legacy banner to the new 4-line ELv2 banner.

No operator action required for any of the file moves; the panel keeps running through the upgrade. The Sponsor / commercial licensing page is the right place to read if you're affected by the managed-service reservation; the FAQ "Is it free?" entry covers the same ground shorter.