[2.1]: Full PHP 8.5 compatibility audit and fixes #9179

Basic Information

The release-2.1 branch has multiple PHP 8.5 incompatibilities that need to be addressed. PHP 8.5 promotes several deprecations from PHP 8.1–8.4 to errors/removals, and the current codebase — originally targeting PHP 7.0 — is affected in numerous places. The CI workflow (.github/workflows/php.yml) only lints syntax up to PHP 8.4 and does not run any runtime tests, so these issues are not currently caught.

This issue consolidates all known and discoverable PHP 8.5 incompatibilities into a single tracking issue with exact code references.

1. trigger_error() with E_USER_ERROR (deprecated PHP 8.4, error in 8.5)

PHP 8.4 deprecated passing E_USER_ERROR to trigger_error(). In PHP 8.5, this will throw a ValueError. SMF's database error backtrace function passes E_USER_ERROR through from callers and also directly invokes trigger_error() with it.

Related issue: #9141 (open, in 2.1.8 milestone — but only covers the DB layer)

1a. Sources/Subs-Db-mysql.php — smf_db_error_backtrace()

The function accepts $error_type and passes it directly to trigger_error() on lines 913–915. Every caller that passes E_USER_ERROR triggers the deprecation:

• Line 195 — smf_db_error_backtrace('Invalid value inserted...', '', E_USER_ERROR, ...)
• Line 209 — Integer type check failure
• Line 222 — Empty array_int
• Line 227 — Non-integer in array_int
• Line 235 — Non-array for array_int
• Line 243 — Empty array_string
• Line 251 — Non-array for array_string
• Line 258 — Invalid date
• Line 265 — Invalid time
• Line 274 ��� Invalid datetime
• Line 279 — Invalid float
• Line 296 — Invalid IPv4/IPv6
• Line 304 — Empty array_inet
• Line 311 — Invalid inet value
• Line 318 — Non-array for array_inet

1b. Sources/Subs-Compat.php — disabled function polyfill uses eval() + trigger_error()

Line 558 creates a polyfill via eval() that calls trigger_error() with E_USER_WARNING — this one is fine, but the overall pattern of using trigger_error() for fatal errors throughout the codebase is the concern.

Fix: Replace all trigger_error($msg, E_USER_ERROR) calls with a proper exception or fatal_error() call. The smf_db_error_backtrace() function already has a fatal_error() path — the trigger_error() fallback on line 913 needs to use E_USER_WARNING or throw an exception instead of E_USER_ERROR.

2. mysqli_ping() deprecated (PHP 8.4, removal expected in future)

mysqli_ping() was deprecated in PHP 8.4 and emits a deprecation warning.

'db_ping' => 'mysqli_ping',

This maps $smcFunc['db_ping'] directly to the deprecated mysqli_ping function. Any code calling $smcFunc['db_ping']() will trigger deprecation warnings on PHP 8.4 and may fail on PHP 8.5+.

Fix: Replace with a wrapper that executes a lightweight query (e.g., SELECT 1) or uses mysqli_query() to test the connection.

3. SessionHandler return type declarations / #[\ReturnTypeWillChange]

The release-2.1 branch uses a custom session handler class that implements SessionHandlerInterface. Based on the version header comments (e.g., "When 8.1 is the minimum, this can be removed"), these methods use #[\ReturnTypeWillChange] to suppress return type warnings.

In PHP 8.5, #[\ReturnTypeWillChange] may no longer suppress warnings, and the missing return type declarations will generate deprecation notices or errors.

The affected methods that need proper return types are:

Fix: Add proper return type declarations to all SessionHandlerInterface methods and remove the #[\ReturnTypeWillChange] attributes. This is safe because SMF 2.1 already requires PHP 7.0+ and return types can be conditionally handled.

4. Passing null to non-nullable parameters of internal functions

PHP 8.1 deprecated passing null to non-nullable string parameters of internal functions. PHP 8.5 promotes these to TypeErrors. The release-2.1 codebase, written for PHP 7.0, does not guard against null in many places.

Related issue: #9173 (strtr() receiving array — open, not in any milestone)

4a. Sources/Subs-Db-mysql.php line 285 — strlen as callback to array_filter

return '`' . implode('`.`', array_filter(explode('.', strtr($replacement, array('`' => ''))), 'strlen')) . '`';

If $replacement is null, strtr() will throw a TypeError in PHP 8.5. Additionally, 'strlen' as a callback to array_filter() will throw a TypeError if any element is null.

4b. Widespread $_SERVER / $_REQUEST / $modSettings values passed directly to string functions

Throughout the codebase, values from superglobals and $modSettings are passed directly to functions like strpos(), strlen(), strtolower(), htmlspecialchars(), trim(), strtr(), substr(), explode(), str_replace(), preg_match(), preg_replace(), urlencode(), rawurlencode(), md5(), sha1(), etc. — all of which require non-null string arguments in PHP 8.5.

Key high-traffic files that need auditing for null-to-string-function calls:

• Sources/Load.php — loading settings, user info, themes
• Sources/Subs.php — general utility functions
• Sources/QueryString.php — URL/request parsing (directly handles $_GET, $_POST, $_REQUEST)
• Sources/Security.php — security checks
• Sources/LogInOut.php — authentication
• Sources/Subs-Db-mysql.php — database layer
• Sources/Subs-Compat.php — compatibility functions

Example pattern that breaks:

// If $modSettings['some_key'] is not set, it's null, and strlen(null) is a TypeError in 8.5
if (strlen($modSettings['some_key']) > 0)

Fix: Add null coalescing (?? '' or ?? 0) before passing potentially null values to internal functions, or add explicit null checks. A codebase-wide audit using static analysis (e.g., PHPStan level 6+) is strongly recommended.

5. Implicit nullable parameter types (deprecated PHP 8.4)

Since PHP 8.4, function signatures like function foo(string $bar = null) generate a deprecation warning. The correct form is function foo(?string $bar = null).

5a. Sources/Subs-Db-mysql.php — multiple functions

function smf_db_insert_id($table, $field = null, $connection = null)

The $field and $connection parameters default to null but have no type declarations. While this specific case is untyped (and thus unaffected), any typed parameters with = null defaults need the ? nullable prefix. A full audit of all function signatures is needed.

5b. Sources/Subs-Compat.php — mb_ord() and mb_chr() polyfills

function mb_ord($string, $encoding = null)
function mb_chr($codepoint, $encoding = null)

These are polyfills only defined when the native functions don't exist, so they are unlikely to be active on PHP 8.5 (which ships mbstring). However, any similar patterns elsewhere in the codebase with explicit type hints will break.

Fix: Search the entire codebase for the regex pattern function\s+\w+\s*\([^)]*\b\w+\s+\$\w+\s*=\s*null and ensure all typed parameters with = null use ?type syntax.

6. CI/CD does not test PHP 8.5

https://github.com/SimpleMachines/SMF/blob/7438c2b04807bca3b3160801a3d40fd2f0f0ca7b/.github/workflows/php.yml

The GitHub Actions workflow only runs phplint against PHP 7.1–8.4. This is syntax checking only — it will not catch:

• Runtime deprecations promoted to errors
• Type errors from null coercion
• Behavioral changes in internal functions

Fix:

1. Add PHP 8.5 to the lint matrix.
2. Ideally, add a runtime test suite (even minimal smoke tests) that exercises key code paths under PHP 8.5.

Summary of required changes

Recommended approach

1. Run PHPStan or Psalm at level 6+ against the release-2.1 branch with PHP 8.5 as the target to surface all null coercion and type issues systematically.
2. Fix the trigger_error(E_USER_ERROR) calls first — these are guaranteed ValueErrors.
3. Replace mysqli_ping with a query-based connection check.
4. Add return types to the session handler.
5. Add PHP 8.5 to CI.

Version/Git revision

release-2.1 (2.1.7, commit 7438c2b)

Database Engine

All

PHP Version

8.5

Additional Information

Several related issues already exist but are fragmented and incomplete:

• [2.1] Using E_USER_ERROR in trigger_error() deprecated in PHP 8.4 #9141 — E_USER_ERROR in trigger_error() (open, 2.1.8 milestone) — covers only the DB layer
• [3.0 & 2.1]: strtr(): Argument #1 ($string) must be of type string, array given #9173 — strtr() argument type error (open, no milestone)
• [2.1.7]: "Cannot use bool as array" Session.php:159 #9168 — Session.php Cannot use bool as array (closed/fixed)
• [2.1 & 3.0] "Wrong value type sent to the database. IPv4 or IPv6 expected." #9143 — IPv4/IPv6 wrong value type (open, 2.1.8 milestone)
• [2.1] uninitialized permissions should not give error spam #9219

None of these individually address the full scope of PHP 8.5 incompatibility. This issue is intended to serve as a comprehensive tracker.

This is an anonymous contribution made via gitGost.

The original author's identity has been anonymized to protect their privacy.