php-legacy-compat-strict.php

<?php
/**
 * Strict legacy compatibility layer for PHP 8.0 through PHP 8.3.
 *
 * Author: Ivijan-Stefan Stipic
 * Version: 1.0.0
 * Repository: https://github.com/InfinitumForm/php-legacy-compat
 *
 * This file is designed for early bootstrap loading in legacy WordPress themes,
 * plugins, mu-plugins, and custom PHP applications that still need removed
 * core behavior, but want a more conservative compatibility surface.
 *
 * Scope:
 * - Recreate removed functions where userland can do so honestly.
 * - Provide clearly prefixed migration helpers for stricter PHP 8 behavior.
 * - Offer opt-in diagnostics and soft error handling without side effects.
 *
 * Non-goals:
 * - Do not fake removed engine state such as magic quotes.
 * - Do not recreate removed extensions such as ext/mysql or ext/mcrypt.
 * - Do not suppress warnings globally unless the project explicitly opts in.
 */

if (defined('LEGACY_COMPAT_BOOTSTRAPPED')) {
    return;
}

define('LEGACY_COMPAT_BOOTSTRAPPED', true);
define('LEGACY_COMPAT_MODE', 'strict');

$GLOBALS['legacy_compat_runtime'] = [
    'mode' => LEGACY_COMPAT_MODE,
    'source' => __FILE__,
    'polyfills' => [],
    'helpers' => [],
    'limitations' => [],
];

/**
 * Register a loaded polyfill or helper in the diagnostics registry.
 *
 * Historical note:
 * - This is an internal utility for the compatibility layer itself.
 * - It does not map to a removed PHP core function.
 *
 * Compatibility type: internal utility.
 *
 * Return behavior:
 * - Returns void.
 *
 * Limitations:
 * - The registry exists only for the lifetime of the current request.
 */
function legacy_compat_internal_register($bucket, $name)
{
    if (!isset($GLOBALS['legacy_compat_runtime'][$bucket])) {
        $GLOBALS['legacy_compat_runtime'][$bucket] = [];
    }

    if (!in_array($name, $GLOBALS['legacy_compat_runtime'][$bucket], true)) {
        $GLOBALS['legacy_compat_runtime'][$bucket][] = $name;
    }
}

/**
 * Record a notable limitation or non-goal in the diagnostics registry.
 *
 * Historical note:
 * - This is an internal utility for the compatibility layer itself.
 * - It does not map to a removed PHP core function.
 *
 * Compatibility type: internal utility.
 *
 * Return behavior:
 * - Returns void.
 *
 * Limitations:
 * - Messages are informational only and are not emitted automatically.
 */
function legacy_compat_internal_note_limitation($message)
{
    if (!in_array($message, $GLOBALS['legacy_compat_runtime']['limitations'], true)) {
        $GLOBALS['legacy_compat_runtime']['limitations'][] = $message;
    }
}

/**
 * Convert a legacy-compatible scalar or stringable value to string.
 *
 * Historical note:
 * - This helper centralizes the loose scalar-to-string coercion that many
 *   internal PHP functions used before PHP 8 hardened type handling.
 * - It does not map to a removed PHP core function.
 *
 * Compatibility type: internal utility.
 *
 * Return behavior:
 * - Returns a string for strings, scalars, null when allowed, and objects that
 *   implement __toString().
 * - Returns null when the value cannot be represented honestly as a string.
 *
 * Limitations:
 * - Arrays and non-stringable objects are rejected instead of being converted.
 */
function legacy_compat_internal_stringify($value, $nullAsEmpty = true)
{
    if ($value === null) {
        return $nullAsEmpty ? '' : null;
    }

    if (is_string($value)) {
        return $value;
    }

    if (is_scalar($value)) {
        return (string) $value;
    }

    if (is_object($value) && method_exists($value, '__toString')) {
        return (string) $value;
    }

    return null;
}

/**
 * Convert an array or Traversable value to a concrete array.
 *
 * Historical note:
 * - This helper centralizes iterable normalization for the migration helpers.
 * - It does not map to a removed PHP core function.
 *
 * Compatibility type: internal utility.
 *
 * Return behavior:
 * - Returns an array when the input is already an array or Traversable.
 * - Returns null when the input is not iterable.
 *
 * Limitations:
 * - Traversable values are materialized into memory.
 */
function legacy_compat_internal_iterable_to_array($value, $preserveKeys = true)
{
    if (is_array($value)) {
        return $value;
    }

    if ($value instanceof Traversable) {
        return iterator_to_array($value, $preserveKeys);
    }

    return null;
}

/**
 * Escape the delimiter used by the internal POSIX-to-PCRE wrapper.
 *
 * Historical note:
 * - Removed ereg-style functions accepted undelimited POSIX patterns.
 * - This helper only prepares those patterns for PCRE wrapping.
 *
 * Compatibility type: internal utility.
 *
 * Return behavior:
 * - Returns the escaped pattern string.
 *
 * Limitations:
 * - The escaping is intentionally simple because it is only used to wrap a
 *   raw legacy pattern, not to rewrite POSIX syntax into a different grammar.
 */
function legacy_compat_internal_escape_regex_delimiter($pattern, $delimiter)
{
    return str_replace($delimiter, '\\' . $delimiter, $pattern);
}

/**
 * Wrap a legacy POSIX regular expression in a PCRE delimiter.
 *
 * Historical note:
 * - ereg(), eregi(), split(), and their related APIs used POSIX regex syntax.
 * - PHP removed that engine in PHP 7.0, so userland can only approximate it
 *   through PCRE.
 *
 * Compatibility type: internal utility.
 *
 * Return behavior:
 * - Returns a PCRE pattern string when the input is non-empty.
 * - Returns false when the pattern cannot be prepared honestly.
 *
 * Limitations:
 * - Obscure POSIX-only edge cases can behave differently under PCRE.
 */
function legacy_compat_internal_posix_pattern($pattern, $caseInsensitive = false)
{
    if (!is_string($pattern) || $pattern === '') {
        return false;
    }

    $delimiter = '~';
    $modifiers = $caseInsensitive ? 'i' : '';

    return $delimiter
        . legacy_compat_internal_escape_regex_delimiter($pattern, $delimiter)
        . $delimiter
        . $modifiers;
}

/**
 * Compute a strftime-style week number for Sunday- or Monday-based calendars.
 *
 * Historical note:
 * - strftime() and gmstrftime() expose week number tokens that date() does not
 *   reproduce directly in the same form.
 * - This helper exists solely to support the prefixed replacement helpers.
 *
 * Compatibility type: internal utility.
 *
 * Return behavior:
 * - Returns a two-digit week number string.
 *
 * Limitations:
 * - The calculation intentionally mirrors common strftime semantics for %U and
 *   %W, but exact libc parity can still differ across platforms.
 */
function legacy_compat_internal_week_number($timestamp, $gmt, $startDay)
{
    $formatter = $gmt ? 'gmdate' : 'date';
    $year = (int) $formatter('Y', $timestamp);
    $dayOfYear = (int) $formatter('z', $timestamp);
    $jan1Timestamp = $gmt
        ? gmmktime(0, 0, 0, 1, 1, $year)
        : mktime(0, 0, 0, 1, 1, $year);

    if ($startDay === 1) {
        $jan1Weekday = ((int) $formatter('N', $jan1Timestamp)) - 1;
    } else {
        $jan1Weekday = (int) $formatter('w', $jan1Timestamp);
    }

    $firstWeekStart = (7 - $jan1Weekday) % 7;

    if ($dayOfYear < $firstWeekStart) {
        return '00';
    }

    return sprintf('%02d', intdiv($dayOfYear - $firstWeekStart, 7) + 1);
}

/**
 * Approximate deprecated strftime-style formatting with date()/gmdate().
 *
 * Historical note:
 * - strftime() and gmstrftime() were deprecated in PHP 8.1 because they depend
 *   on platform locale APIs that vary by system.
 * - This helper provides a stable replacement for common legacy tokens.
 *
 * Compatibility type: compatibility approximation.
 *
 * Return behavior:
 * - Returns a formatted string.
 *
 * Limitations:
 * - Locale-sensitive textual tokens fall back to English date()/gmdate()
 *   output on PHP 8.1+ because userland cannot reproduce libc locale behavior
 *   exactly without delegating back to the deprecated native APIs.
 */
function legacy_compat_internal_format_strftime($format, $timestamp, $gmt)
{
    $formatter = $gmt ? 'gmdate' : 'date';
    $result = '';
    $length = strlen($format);

    for ($index = 0; $index < $length; $index++) {
        $character = $format[$index];

        if ($character !== '%') {
            $result .= $character;
            continue;
        }

        $index++;

        if ($index >= $length) {
            $result .= '%';
            break;
        }

        $token = $format[$index];

        switch ($token) {
            case '%':
                $result .= '%';
                break;
            case 'a':
                $result .= $formatter('D', $timestamp);
                break;
            case 'A':
                $result .= $formatter('l', $timestamp);
                break;
            case 'b':
            case 'h':
                $result .= $formatter('M', $timestamp);
                break;
            case 'B':
                $result .= $formatter('F', $timestamp);
                break;
            case 'c':
                $result .= $formatter('D M d H:i:s Y', $timestamp);
                break;
            case 'C':
                $result .= sprintf('%02d', (int) floor(((int) $formatter('Y', $timestamp)) / 100));
                break;
            case 'd':
                $result .= $formatter('d', $timestamp);
                break;
            case 'D':
                $result .= $formatter('m/d/y', $timestamp);
                break;
            case 'e':
                $result .= str_pad($formatter('j', $timestamp), 2, ' ', STR_PAD_LEFT);
                break;
            case 'F':
                $result .= $formatter('Y-m-d', $timestamp);
                break;
            case 'g':
                $result .= substr($formatter('o', $timestamp), -2);
                break;
            case 'G':
                $result .= $formatter('o', $timestamp);
                break;
            case 'H':
                $result .= $formatter('H', $timestamp);
                break;
            case 'I':
                $result .= $formatter('h', $timestamp);
                break;
            case 'j':
                $result .= sprintf('%03d', ((int) $formatter('z', $timestamp)) + 1);
                break;
            case 'k':
                $result .= str_pad($formatter('G', $timestamp), 2, ' ', STR_PAD_LEFT);
                break;
            case 'l':
                $result .= str_pad($formatter('g', $timestamp), 2, ' ', STR_PAD_LEFT);
                break;
            case 'm':
                $result .= $formatter('m', $timestamp);
                break;
            case 'M':
                $result .= $formatter('i', $timestamp);
                break;
            case 'n':
                $result .= "\n";
                break;
            case 'p':
                $result .= $formatter('A', $timestamp);
                break;
            case 'P':
                $result .= strtolower($formatter('A', $timestamp));
                break;
            case 'r':
                $result .= $formatter('h:i:s A', $timestamp);
                break;
            case 'R':
                $result .= $formatter('H:i', $timestamp);
                break;
            case 's':
                $result .= (string) $timestamp;
                break;
            case 'S':
                $result .= $formatter('s', $timestamp);
                break;
            case 't':
                $result .= "\t";
                break;
            case 'T':
                $result .= $formatter('H:i:s', $timestamp);
                break;
            case 'u':
                $result .= $formatter('N', $timestamp);
                break;
            case 'U':
                $result .= legacy_compat_internal_week_number($timestamp, $gmt, 0);
                break;
            case 'V':
                $result .= $formatter('W', $timestamp);
                break;
            case 'w':
                $result .= $formatter('w', $timestamp);
                break;
            case 'W':
                $result .= legacy_compat_internal_week_number($timestamp, $gmt, 1);
                break;
            case 'x':
                $result .= $formatter('m/d/y', $timestamp);
                break;
            case 'X':
                $result .= $formatter('H:i:s', $timestamp);
                break;
            case 'y':
                $result .= $formatter('y', $timestamp);
                break;
            case 'Y':
                $result .= $formatter('Y', $timestamp);
                break;
            case 'z':
                $result .= $formatter('O', $timestamp);
                break;
            case 'Z':
                $result .= $formatter('T', $timestamp);
                break;
            default:
                $result .= '%' . $token;
                break;
        }
    }

    return $result;
}

/**
 * Match an error message against a user-provided list of regular expressions.
 *
 * Historical note:
 * - This helper supports the opt-in soft error handler.
 * - It does not map to a removed PHP core function.
 *
 * Compatibility type: internal utility.
 *
 * Return behavior:
 * - Returns true when a pattern matches the message.
 * - Returns false when no pattern matches.
 *
 * Limitations:
 * - Invalid user-provided patterns are ignored after preg_match() reports them.
 */
function legacy_compat_internal_message_matches_any($message, array $patterns)
{
    foreach ($patterns as $pattern) {
        if (!is_string($pattern) || $pattern === '') {
            continue;
        }

        if (preg_match($pattern, $message) === 1) {
            return true;
        }
    }

    return false;
}

legacy_compat_internal_note_limitation(
    'Removed extensions such as ext/mysql, ext/mcrypt, and legacy crypto APIs are intentionally not recreated.'
);
legacy_compat_internal_note_limitation(
    'Only one compatibility file should be loaded per request; universal and strict variants are not meant to be stacked.'
);
legacy_compat_internal_note_limitation(
    'money_format() is intentionally omitted in strict mode because locale-equivalent output cannot be guaranteed.'
);

/*
|--------------------------------------------------------------------------
| Removed In PHP 7.x
|--------------------------------------------------------------------------
*/

/**
 * Call a user method on a specific object.
 *
 * Historically this function proxied a method call on an object instance.
 * It was deprecated in PHP 4.1.0 and removed in PHP 7.0.
 *
 * Compatibility type: true polyfill.
 *
 * Return behavior:
 * - Returns the underlying method return value.
 *
 * Limitations:
 * - None for normal callable object methods.
 */
if (!function_exists('call_user_method')) {
    function call_user_method($methodName, &$object, ...$arguments)
    {
        return call_user_func_array([$object, $methodName], $arguments);
    }

    legacy_compat_internal_register('polyfills', 'call_user_method');
}

/**
 * Call a user method with an array of parameters.
 *
 * Historically this function proxied a method call using an argument array.
 * It was deprecated in PHP 4.1.0 and removed in PHP 7.0.
 *
 * Compatibility type: true polyfill.
 *
 * Return behavior:
 * - Returns the underlying method return value.
 *
 * Limitations:
 * - Non-array parameter lists are normalized to an empty array or single-item
 *   array because call_user_func_array() requires an array.
 */
if (!function_exists('call_user_method_array')) {
    function call_user_method_array($methodName, &$object, $parameters)
    {
        if ($parameters === null) {
            $parameters = [];
        } elseif (!is_array($parameters)) {
            $parameters = [$parameters];
        }

        return call_user_func_array([$object, $methodName], $parameters);
    }

    legacy_compat_internal_register('polyfills', 'call_user_method_array');
}

/**
 * Match a POSIX regular expression.
 *
 * Historically ereg() searched a string with the POSIX regex engine and
 * returned the matched length or false. It was deprecated in PHP 5.3 and
 * removed in PHP 7.0.
 *
 * Compatibility type: compatibility approximation.
 *
 * Return behavior:
 * - Returns the byte length of the full match when found.
 * - Returns false when there is no match or the pattern cannot be compiled.
 *
 * Limitations:
 * - The removed POSIX regex engine no longer exists, so this implementation
 *   wraps the legacy pattern for PCRE use. Obscure POSIX edge cases can differ.
 */
if (!function_exists('ereg')) {
    function ereg($pattern, $string, &$registers = null)
    {
        $compiledPattern = legacy_compat_internal_posix_pattern($pattern, false);
        $subject = legacy_compat_internal_stringify($string);

        if ($compiledPattern === false || $subject === null) {
            if (func_num_args() > 2) {
                $registers = [];
            }

            return false;
        }

        $matches = [];
        $result = preg_match($compiledPattern, $subject, $matches);

        if ($result !== 1) {
            if (func_num_args() > 2) {
                $registers = [];
            }

            return false;
        }

        if (func_num_args() > 2) {
            $registers = $matches;
        }

        return strlen($matches[0]);
    }

    legacy_compat_internal_register('polyfills', 'ereg');
}

/**
 * Match a case-insensitive POSIX regular expression.
 *
 * Historically eregi() was the case-insensitive companion to ereg(). It was
 * deprecated in PHP 5.3 and removed in PHP 7.0.
 *
 * Compatibility type: compatibility approximation.
 *
 * Return behavior:
 * - Returns the byte length of the full match when found.
 * - Returns false when there is no match or the pattern cannot be compiled.
 *
 * Limitations:
 * - The removed POSIX regex engine no longer exists, so this implementation
 *   wraps the legacy pattern for PCRE use with the i modifier.
 */
if (!function_exists('eregi')) {
    function eregi($pattern, $string, &$registers = null)
    {
        $compiledPattern = legacy_compat_internal_posix_pattern($pattern, true);
        $subject = legacy_compat_internal_stringify($string);

        if ($compiledPattern === false || $subject === null) {
            if (func_num_args() > 2) {
                $registers = [];
            }

            return false;
        }

        $matches = [];
        $result = preg_match($compiledPattern, $subject, $matches);

        if ($result !== 1) {
            if (func_num_args() > 2) {
                $registers = [];
            }

            return false;
        }

        if (func_num_args() > 2) {
            $registers = $matches;
        }

        return strlen($matches[0]);
    }

    legacy_compat_internal_register('polyfills', 'eregi');
}

/**
 * Replace text matched by a POSIX regular expression.
 *
 * Historically ereg_replace() performed POSIX-regex substitution. It was
 * deprecated in PHP 5.3 and removed in PHP 7.0.
 *
 * Compatibility type: compatibility approximation.
 *
 * Return behavior:
 * - Returns the replaced string.
 * - Returns false when the pattern cannot be compiled or the subject cannot be
 *   represented honestly as a string.
 *
 * Limitations:
 * - The removed POSIX regex engine no longer exists, so this implementation
 *   delegates to preg_replace() with a wrapped PCRE pattern.
 */
if (!function_exists('ereg_replace')) {
    function ereg_replace($pattern, $replacement, $string)
    {
        $compiledPattern = legacy_compat_internal_posix_pattern($pattern, false);
        $subject = legacy_compat_internal_stringify($string);
        $replacement = legacy_compat_internal_stringify($replacement);

        if ($compiledPattern === false || $subject === null || $replacement === null) {
            return false;
        }

        return preg_replace($compiledPattern, $replacement, $subject);
    }

    legacy_compat_internal_register('polyfills', 'ereg_replace');
}

/**
 * Replace text matched by a case-insensitive POSIX regular expression.
 *
 * Historically eregi_replace() performed case-insensitive POSIX-regex
 * substitution. It was deprecated in PHP 5.3 and removed in PHP 7.0.
 *
 * Compatibility type: compatibility approximation.
 *
 * Return behavior:
 * - Returns the replaced string.
 * - Returns false when the pattern cannot be compiled or the subject cannot be
 *   represented honestly as a string.
 *
 * Limitations:
 * - The removed POSIX regex engine no longer exists, so this implementation
 *   delegates to preg_replace() with a wrapped PCRE pattern.
 */
if (!function_exists('eregi_replace')) {
    function eregi_replace($pattern, $replacement, $string)
    {
        $compiledPattern = legacy_compat_internal_posix_pattern($pattern, true);
        $subject = legacy_compat_internal_stringify($string);
        $replacement = legacy_compat_internal_stringify($replacement);

        if ($compiledPattern === false || $subject === null || $replacement === null) {
            return false;
        }

        return preg_replace($compiledPattern, $replacement, $subject);
    }

    legacy_compat_internal_register('polyfills', 'eregi_replace');
}

/**
 * Split a string by a POSIX regular expression.
 *
 * Historically split() tokenized a string with the POSIX regex engine. It was
 * deprecated in PHP 5.3 and removed in PHP 7.0.
 *
 * Compatibility type: compatibility approximation.
 *
 * Return behavior:
 * - Returns an array of string segments.
 * - Returns false when the pattern cannot be compiled or the subject cannot be
 *   represented honestly as a string.
 *
 * Limitations:
 * - The removed POSIX regex engine no longer exists, so this implementation
 *   delegates to preg_split() with a wrapped PCRE pattern.
 */
if (!function_exists('split')) {
    function split($pattern, $string, $limit = -1)
    {
        $compiledPattern = legacy_compat_internal_posix_pattern($pattern, false);
        $subject = legacy_compat_internal_stringify($string);

        if ($compiledPattern === false || $subject === null) {
            return false;
        }

        $limit = (int) $limit;

        if ($limit === 0) {
            $limit = 1;
        }

        return preg_split($compiledPattern, $subject, $limit);
    }

    legacy_compat_internal_register('polyfills', 'split');
}

/**
 * Split a string by a case-insensitive POSIX regular expression.
 *
 * Historically spliti() tokenized a string with a case-insensitive POSIX regex.
 * It was deprecated in PHP 5.3 and removed in PHP 7.0.
 *
 * Compatibility type: compatibility approximation.
 *
 * Return behavior:
 * - Returns an array of string segments.
 * - Returns false when the pattern cannot be compiled or the subject cannot be
 *   represented honestly as a string.
 *
 * Limitations:
 * - The removed POSIX regex engine no longer exists, so this implementation
 *   delegates to preg_split() with a wrapped PCRE pattern.
 */
if (!function_exists('spliti')) {
    function spliti($pattern, $string, $limit = -1)
    {
        $compiledPattern = legacy_compat_internal_posix_pattern($pattern, true);
        $subject = legacy_compat_internal_stringify($string);

        if ($compiledPattern === false || $subject === null) {
            return false;
        }

        $limit = (int) $limit;

        if ($limit === 0) {
            $limit = 1;
        }

        return preg_split($compiledPattern, $subject, $limit);
    }

    legacy_compat_internal_register('polyfills', 'spliti');
}

legacy_compat_internal_note_limitation(
    'POSIX regular-expression polyfills are implemented through PCRE because the original regex engine was removed in PHP 7.0.'
);

/**
 * Build a case-insensitive ASCII-ish regular expression fragment.
 *
 * Historically sql_regcase() converted alphabetic characters into bracket
 * expressions such as [Aa]. It was deprecated in PHP 5.3 and removed in 7.0.
 *
 * Compatibility type: safe fallback.
 *
 * Return behavior:
 * - Returns the transformed pattern string.
 *
 * Limitations:
 * - The historical function was byte-oriented and locale-sensitive. This
 *   fallback remains byte-oriented and is most faithful for Latin-1 style text.
 */
if (!function_exists('sql_regcase')) {
    function sql_regcase($string)
    {
        $subject = legacy_compat_internal_stringify($string);

        if ($subject === null) {
            return false;
        }

        $result = '';
        $length = strlen($subject);

        for ($index = 0; $index < $length; $index++) {
            $character = $subject[$index];

            if (ctype_alpha($character)) {
                $upper = strtoupper($character);
                $lower = strtolower($character);
                $result .= ($upper === $lower)
                    ? $character
                    : '[' . $upper . $lower . ']';
                continue;
            }

            $result .= $character;
        }

        return $result;
    }

    legacy_compat_internal_register('polyfills', 'sql_regcase');
}

/**
 * Register one or more globals with the active session.
 *
 * Historically session_register() exposed register_globals-era session usage by
 * binding global variables into $_SESSION. It was deprecated in PHP 5.3 and
 * removed in PHP 5.4.
 *
 * Compatibility type: partial polyfill.
 *
 * Return behavior:
 * - Returns true when every provided name was registered in the active session.
 * - Returns false when there is no active session or an invalid name is given.
 *
 * Limitations:
 * - Modern PHP no longer has register_globals, so this polyfill can only mirror
 *   the $_SESSION binding behavior inside the current request.
 * - Strict mode does not auto-start a session because that would introduce a
 *   side effect outside the immediate compatibility contract.
 */
if (!function_exists('session_register')) {
    function session_register(...$names)
    {
        if (!function_exists('session_status') || session_status() !== PHP_SESSION_ACTIVE) {
            return false;
        }

        if (!isset($_SESSION) || !is_array($_SESSION)) {
            $_SESSION = [];
        }

        $success = true;

        foreach ($names as $name) {
            if (!is_string($name) || $name === '') {
                $success = false;
                continue;
            }

            if (!array_key_exists($name, $GLOBALS)) {
                $GLOBALS[$name] = null;
            }

            $_SESSION[$name] =& $GLOBALS[$name];
        }

        return $success;
    }

    legacy_compat_internal_register('polyfills', 'session_register');
}

/**
 * Unregister a session variable by name.
 *
 * Historically session_unregister() removed a registered session variable. It
 * was deprecated in PHP 5.3 and removed in PHP 5.4.
 *
 * Compatibility type: partial polyfill.
 *
 * Return behavior:
 * - Returns true when the named key existed and was removed from $_SESSION.
 * - Returns false when there is no active session or the key was absent.
 *
 * Limitations:
 * - The associated global variable is intentionally left untouched because the
 *   removed register_globals engine behavior no longer exists.
 * - Strict mode does not auto-start a session because that would introduce a
 *   side effect outside the immediate compatibility contract.
 */
if (!function_exists('session_unregister')) {
    function session_unregister($name)
    {
        if (!function_exists('session_status') || session_status() !== PHP_SESSION_ACTIVE) {
            return false;
        }

        if (!is_string($name) || $name === '' || !isset($_SESSION) || !is_array($_SESSION)) {
            return false;
        }

        if (!array_key_exists($name, $_SESSION)) {
            return false;
        }

        unset($_SESSION[$name]);

        return true;
    }

    legacy_compat_internal_register('polyfills', 'session_unregister');
}

/**
 * Check whether a named session variable is registered.
 *
 * Historically session_is_registered() reported whether a session key had been
 * registered through the older session APIs. It was deprecated in PHP 5.3 and
 * removed in PHP 5.4.
 *
 * Compatibility type: partial polyfill.
 *
 * Return behavior:
 * - Returns true when the named key exists in the active session.
 * - Returns false otherwise.
 *
 * Limitations:
 * - Modern PHP no longer tracks "registered" session globals separately, so
 *   this polyfill checks key existence in $_SESSION directly.
 * - Strict mode does not auto-start a session because that would introduce a
 *   side effect outside the immediate compatibility contract.
 */
if (!function_exists('session_is_registered')) {
    function session_is_registered($name)
    {
        if (!function_exists('session_status') || session_status() !== PHP_SESSION_ACTIVE) {
            return false;
        }

        if (!is_string($name) || $name === '' || !isset($_SESSION) || !is_array($_SESSION)) {
            return false;
        }

        return array_key_exists($name, $_SESSION);
    }

    legacy_compat_internal_register('polyfills', 'session_is_registered');
}

legacy_compat_internal_note_limitation(
    'session_register() polyfills only the $_SESSION binding behavior because register_globals was removed from the engine; strict mode requires an already active session.'
);

/**
 * Create a dynamically named function from argument and body strings.
 *
 * Historically create_function() compiled runtime PHP code and returned a
 * generated function name string. It was deprecated in PHP 7.2 and removed in
 * PHP 8.0.
 *
 * Compatibility type: true polyfill.
 *
 * Return behavior:
 * - Returns the generated function name string on success.
 * - Returns false when the generated function cannot be compiled.
 *
 * Limitations:
 * - eval() is required because the historical API itself compiled runtime code.
 * - Generated functions remain defined until the request ends, just like the
 *   original implementation.
 */
if (!function_exists('create_function')) {
    function create_function($arguments, $code)
    {
        if (!is_string($arguments) || !is_string($code)) {
            return false;
        }

        static $counter = 0;

        do {
            $counter++;
            $functionName = '__legacy_create_function_' . $counter;
        } while (function_exists($functionName));

        $source = 'function ' . $functionName . '(' . $arguments . ') {' . "\n" . $code . "\n" . '}';

        try {
            eval($source);
        } catch (ParseError $exception) {
            return false;
        }

        return function_exists($functionName) ? $functionName : false;
    }

    legacy_compat_internal_register('polyfills', 'create_function');
    legacy_compat_internal_note_limitation(
        'create_function() uses eval() because the historical API compiled code at runtime; only load trusted legacy code.'
    );
}

/*
|--------------------------------------------------------------------------
| Removed In PHP 7.3 Through PHP 8.0
|--------------------------------------------------------------------------
*/

if (!defined('FILTER_FLAG_SCHEME_REQUIRED')) {
    define('FILTER_FLAG_SCHEME_REQUIRED', 65536);
}

if (!defined('FILTER_FLAG_HOST_REQUIRED')) {
    define('FILTER_FLAG_HOST_REQUIRED', 131072);
}

if (!defined('IMAGETYPE_WEBP')) {
    define('IMAGETYPE_WEBP', 18);
}

if (!defined('IMAGETYPE_ICO')) {
    define('IMAGETYPE_ICO', 17);
}

if (!defined('PHP_SESSION_NONE')) {
    define('PHP_SESSION_NONE', 1);
}

/**
 * Alias image2wbmp() to imagewbmp() when GD still provides the target API.
 *
 * Historically image2wbmp() was a named GD alias. It was deprecated in PHP 7.2
 * and removed in PHP 7.3.
 *
 * Compatibility type: true polyfill.
 *
 * Return behavior:
 * - Returns the result of imagewbmp().
 *
 * Limitations:
 * - The underlying GD extension must still be loaded.
 */
if (!function_exists('image2wbmp') && function_exists('imagewbmp')) {
    function image2wbmp($image, $file = null, $foreground = 0)
    {
        return imagewbmp($image, $file, $foreground);
    }

    legacy_compat_internal_register('polyfills', 'image2wbmp');
}

/**
 * Alias is_real() to is_float().
 *
 * Historically is_real() was an alias of is_float(). It was deprecated in PHP
 * 7.4 and removed in PHP 8.0.
 *
 * Compatibility type: true polyfill.
 *
 * Return behavior:
 * - Returns the result of is_float().
 *
 * Limitations:
 * - None.
 */
if (!function_exists('is_real')) {
    function is_real($value)
    {
        return is_float($value);
    }

    legacy_compat_internal_register('polyfills', 'is_real');
}

/**
 * Report whether magic_quotes_gpc is active.
 *
 * Historically this function exposed the magic_quotes_gpc runtime setting.
 * The feature itself was removed in PHP 5.4, the function was deprecated in
 * PHP 7.4, and the function was removed in PHP 8.0.
 *
 * Compatibility type: safe fallback.
 *
 * Return behavior:
 * - Always returns false because the engine feature no longer exists.
 *
 * Limitations:
 * - Userland cannot re-create or query a removed engine feature honestly.
 */
if (!function_exists('get_magic_quotes_gpc')) {
    function get_magic_quotes_gpc()
    {
        return false;
    }

    legacy_compat_internal_register('polyfills', 'get_magic_quotes_gpc');
}

/**
 * Report whether magic_quotes_runtime is active.
 *
 * Historically this function exposed the magic_quotes_runtime setting.
 * The feature itself was removed in PHP 5.4, and the function was removed in
 * PHP 8.0.
 *
 * Compatibility type: safe fallback.
 *
 * Return behavior:
 * - Always returns false because the engine feature no longer exists.
 *
 * Limitations:
 * - Userland cannot re-create or query a removed engine feature honestly.
 */
if (!function_exists('get_magic_quotes_runtime')) {
    function get_magic_quotes_runtime()
    {
        return false;
    }

    legacy_compat_internal_register('polyfills', 'get_magic_quotes_runtime');
}

/**
 * Attempt to enable or disable magic_quotes_runtime.
 *
 * Historically this function toggled magic_quotes_runtime. The feature itself
 * was removed in PHP 5.4, and the function was removed in PHP 8.0.
 *
 * Compatibility type: safe fallback.
 *
 * Return behavior:
 * - Always returns false because the removed engine feature cannot be enabled.
 *
 * Limitations:
 * - Userland cannot re-create or mutate a removed engine feature honestly.
 */
if (!function_exists('set_magic_quotes_runtime')) {
    function set_magic_quotes_runtime($newSetting)
    {
        return false;
    }

    legacy_compat_internal_register('polyfills', 'set_magic_quotes_runtime');
}

legacy_compat_internal_note_limitation(
    'Magic quotes functions report permanent absence only; the removed engine feature cannot be recreated honestly.'
);

/*
|--------------------------------------------------------------------------
| Removed In PHP 8.0
|--------------------------------------------------------------------------
*/

/**
 * Advance an array pointer and return the current key/value tuple.
 *
 * Historically each() returned the current key/value pair and advanced the
 * internal array pointer. It was deprecated in PHP 7.2 and removed in PHP 8.0.
 *
 * Compatibility type: true polyfill.
 *
 * Return behavior:
 * - Returns an array with numeric and associative key/value entries.
 * - Returns false when the pointer is past the end of the array.
 *
 * Limitations:
 * - The polyfill intentionally supports arrays only, which matches historical
 *   documented usage.
 */
if (!function_exists('each')) {
    function each(&$array)
    {
        if (!is_array($array)) {
            trigger_error('each() expects parameter 1 to be array.', E_USER_WARNING);
            return false;
        }

        $key = key($array);

        if ($key === null) {
            return false;
        }

        $value = current($array);
        next($array);

        return [
            1 => $value,
            'value' => $value,
            0 => $key,
            'key' => $key,
        ];
    }

    legacy_compat_internal_register('polyfills', 'each');
}

/*
|--------------------------------------------------------------------------
| Deprecated In PHP 8.1
|--------------------------------------------------------------------------
*/

/**
 * Non-deprecated helper that approximates strftime().
 *
 * Historically strftime() formatted timestamps through platform locale APIs.
 * It was deprecated in PHP 8.1.
 *
 * Compatibility type: compatibility approximation.
 *
 * Return behavior:
 * - Returns the native strftime() output on PHP 8.0 and earlier when available.
 * - Returns a date()-based approximation on PHP 8.1+.
 *
 * Limitations:
 * - Locale-sensitive tokens are only approximate on PHP 8.1+ because calling
 *   the native API would emit deprecation notices.
 */
function legacy_compat_strftime($format, $timestamp = null)
{
    $format = legacy_compat_internal_stringify($format);

    if ($format === null) {
        return false;
    }

    if ($timestamp === null) {
        $timestamp = time();
    }

    if (PHP_VERSION_ID < 80100 && function_exists('strftime')) {
        return strftime($format, (int) $timestamp);
    }

    return legacy_compat_internal_format_strftime($format, (int) $timestamp, false);
}

legacy_compat_internal_register('helpers', 'legacy_compat_strftime');

/**
 * Non-deprecated helper that approximates gmstrftime().
 *
 * Historically gmstrftime() formatted timestamps in GMT through platform locale
 * APIs. It was deprecated in PHP 8.1.
 *
 * Compatibility type: compatibility approximation.
 *
 * Return behavior:
 * - Returns the native gmstrftime() output on PHP 8.0 and earlier when
 *   available.
 * - Returns a gmdate()-based approximation on PHP 8.1+.
 *
 * Limitations:
 * - Locale-sensitive tokens are only approximate on PHP 8.1+ because calling
 *   the native API would emit deprecation notices.
 */
function legacy_compat_gmstrftime($format, $timestamp = null)
{
    $format = legacy_compat_internal_stringify($format);

    if ($format === null) {
        return false;
    }

    if ($timestamp === null) {
        $timestamp = time();
    }

    if (PHP_VERSION_ID < 80100 && function_exists('gmstrftime')) {
        return gmstrftime($format, (int) $timestamp);
    }

    return legacy_compat_internal_format_strftime($format, (int) $timestamp, true);
}

legacy_compat_internal_register('helpers', 'legacy_compat_gmstrftime');
legacy_compat_internal_note_limitation(
    'legacy_compat_strftime() and legacy_compat_gmstrftime() approximate locale-sensitive tokens on PHP 8.1+ to avoid deprecated native calls.'
);

/*
|--------------------------------------------------------------------------
| Deprecated In PHP 8.2
|--------------------------------------------------------------------------
*/

/**
 * Convert ISO-8859-1 bytes to UTF-8 without relying on deprecated core APIs.
 *
 * Historically utf8_encode() converted ISO-8859-1 input into UTF-8. It was
 * deprecated in PHP 8.2 and remains present in PHP 8.3.
 *
 * Compatibility type: true polyfill helper.
 *
 * Return behavior:
 * - Returns the converted UTF-8 string.
 * - Returns null after a warning when the input cannot be represented honestly
 *   as a byte string.
 *
 * Limitations:
 * - This helper intentionally preserves ISO-8859-1 behavior only; it does not
 *   guess Windows-1252 or any other source encoding.
 */
function legacy_compat_utf8_encode($string)
{
    $input = legacy_compat_internal_stringify($string);

    if ($input === null) {
        trigger_error('legacy_compat_utf8_encode() expects a string-compatible value.', E_USER_WARNING);
        return null;
    }

    $result = '';
    $length = strlen($input);

    for ($index = 0; $index < $length; $index++) {
        $byte = ord($input[$index]);

        if ($byte < 0x80) {
            $result .= $input[$index];
            continue;
        }

        $result .= chr(0xC0 | ($byte >> 6));
        $result .= chr(0x80 | ($byte & 0x3F));
    }

    return $result;
}

legacy_compat_internal_register('helpers', 'legacy_compat_utf8_encode');

/**
 * Convert UTF-8 bytes to ISO-8859-1 without relying on deprecated core APIs.
 *
 * Historically utf8_decode() converted UTF-8 input into ISO-8859-1 and
 * replaced code points outside Latin-1 with question marks. It was deprecated
 * in PHP 8.2 and remains present in PHP 8.3.
 *
 * Compatibility type: true polyfill helper.
 *
 * Return behavior:
 * - Returns the converted ISO-8859-1 string.
 * - Returns null after a warning when the input cannot be represented honestly
 *   as a byte string.
 *
 * Limitations:
 * - Characters outside ISO-8859-1 are replaced with ? because that is the
 *   historical behavior of utf8_decode().
 */
function legacy_compat_utf8_decode($string)
{
    $input = legacy_compat_internal_stringify($string);

    if ($input === null) {
        trigger_error('legacy_compat_utf8_decode() expects a string-compatible value.', E_USER_WARNING);
        return null;
    }

    $result = '';
    $length = strlen($input);

    for ($index = 0; $index < $length; $index++) {
        $byte = ord($input[$index]);

        if ($byte < 0x80) {
            $result .= chr($byte);
            continue;
        }

        if (($byte === 0xC2 || $byte === 0xC3) && isset($input[$index + 1])) {
            $next = ord($input[$index + 1]);

            if (($next & 0xC0) === 0x80) {
                $result .= chr((($byte & 0x1F) << 6) | ($next & 0x3F));
                $index++;
                continue;
            }
        }

        if ($byte >= 0xC0 && $byte <= 0xDF) {
            $continuations = 1;
        } elseif ($byte >= 0xE0 && $byte <= 0xEF) {
            $continuations = 2;
        } elseif ($byte >= 0xF0 && $byte <= 0xF7) {
            $continuations = 3;
        } else {
            $continuations = 0;
        }

        while ($continuations > 0 && isset($input[$index + 1])) {
            $next = ord($input[$index + 1]);

            if (($next & 0xC0) !== 0x80) {
                break;
            }

            $index++;
            $continuations--;
        }

        $result .= '?';
    }

    return $result;
}

legacy_compat_internal_register('helpers', 'legacy_compat_utf8_decode');

/**
 * Convert ISO-8859-1 bytes to UTF-8 bytes.
 *
 * Historically utf8_encode() converted ISO-8859-1 input into UTF-8. It was
 * deprecated in PHP 8.2 and remains present in PHP 8.3.
 *
 * Compatibility type: true polyfill.
 *
 * Return behavior:
 * - Returns the converted string.
 * - Returns null after a warning when the input cannot be represented honestly
 *   as a byte string.
 *
 * Limitations:
 * - This function intentionally preserves the historical ISO-8859-1-only
 *   behavior; it is not a general-purpose charset detector.
 */
if (!function_exists('utf8_encode')) {
    function utf8_encode($string)
    {
        return legacy_compat_utf8_encode($string);
    }

    legacy_compat_internal_register('polyfills', 'utf8_encode');
}

/**
 * Convert UTF-8 bytes to ISO-8859-1 bytes.
 *
 * Historically utf8_decode() converted UTF-8 input into ISO-8859-1 and
 * replaced code points outside Latin-1 with question marks. It was deprecated
 * in PHP 8.2 and remains present in PHP 8.3.
 *
 * Compatibility type: true polyfill.
 *
 * Return behavior:
 * - Returns the converted string.
 * - Returns null after a warning when the input cannot be represented honestly
 *   as a byte string.
 *
 * Limitations:
 * - Characters outside ISO-8859-1 are replaced with ? because that is the
 *   historical behavior of utf8_decode().
 */
if (!function_exists('utf8_decode')) {
    function utf8_decode($string)
    {
        return legacy_compat_utf8_decode($string);
    }

    legacy_compat_internal_register('polyfills', 'utf8_decode');
}

/*
|--------------------------------------------------------------------------
| PHP 8.x Migration Helpers
|--------------------------------------------------------------------------
*/

/**
 * Count values with PHP 5.x and early PHP 7.x style permissiveness.
 *
 * Historically count() returned 0 for null and 1 for most non-countable scalar
 * and object values. PHP 7.2 started warning, and PHP 8 throws TypeError.
 *
 * Compatibility type: migration helper.
 *
 * Return behavior:
 * - Returns count() for arrays and Countable objects.
 * - Returns 0 for null and other non-countable values.
 *
 * Limitations:
 * - The strict variant intentionally refuses to emulate count(scalar) = 1
 *   because that permissive behavior can silently hide real bugs.
 */
function legacy_safe_count($value, $mode = COUNT_NORMAL)
{
    if (is_array($value) || $value instanceof Countable) {
        return count($value, $mode);
    }

    return 0;
}

legacy_compat_internal_register('helpers', 'legacy_safe_count');

/**
 * Measure string length while tolerating null and scalar inputs.
 *
 * Historically many internal string functions accepted null and scalars through
 * loose coercion. PHP 8 hardens those calls.
 *
 * Compatibility type: migration helper.
 *
 * Return behavior:
 * - Returns strlen() for string-compatible values.
 * - Returns null when the value cannot be represented honestly as a string.
 *
 * Limitations:
 * - Arrays and non-stringable objects are rejected instead of being flattened.
 */
function legacy_safe_strlen($value)
{
    $string = legacy_compat_internal_stringify($value);

    return $string === null ? null : strlen($string);
}

legacy_compat_internal_register('helpers', 'legacy_safe_strlen');

/**
 * Extract a substring while tolerating null and scalar inputs.
 *
 * Historically substr() accepted null and scalars through loose coercion.
 * PHP 8 hardens those calls.
 *
 * Compatibility type: migration helper.
 *
 * Return behavior:
 * - Returns substr() output for string-compatible values.
 * - Returns null when the value cannot be represented honestly as a string.
 *
 * Limitations:
 * - Arrays and non-stringable objects are rejected instead of being flattened.
 */
function legacy_safe_substr($value, $offset, $length = null)
{
    $string = legacy_compat_internal_stringify($value);

    if ($string === null) {
        return null;
    }

    if ($length === null) {
        return substr($string, (int) $offset);
    }

    return substr($string, (int) $offset, (int) $length);
}

legacy_compat_internal_register('helpers', 'legacy_safe_substr');

/**
 * Check array-like key existence without crashing on legacy object usage.
 *
 * Historically some projects passed objects or null into array_key_exists().
 * PHP 8 now throws on invalid input.
 *
 * Compatibility type: migration helper.
 *
 * Return behavior:
 * - Returns true or false for arrays and plain objects.
 * - Returns false for unsupported values.
 *
 * Limitations:
 * - ArrayAccess is intentionally excluded because offsetExists() follows
 *   isset()-style semantics and can disagree for null values.
 */
function legacy_safe_array_key_exists($key, $value)
{
    if (is_array($value)) {
        return array_key_exists($key, $value);
    }

    if (is_object($value)) {
        return property_exists($value, (string) $key);
    }

    return false;
}

legacy_compat_internal_register('helpers', 'legacy_safe_array_key_exists');

/**
 * Run in_array() only when the haystack is truly iterable.
 *
 * Historically loose code paths often handed null or Traversable values into
 * array-only functions. PHP 8 now throws on invalid haystacks.
 *
 * Compatibility type: migration helper.
 *
 * Return behavior:
 * - Returns in_array() results for arrays and Traversable values.
 * - Returns false for unsupported haystacks.
 *
 * Limitations:
 * - Traversable haystacks are materialized into arrays.
 */
function legacy_safe_in_array($needle, $haystack, $strict = false)
{
    $values = legacy_compat_internal_iterable_to_array($haystack, true);

    if ($values === null) {
        return false;
    }

    return in_array($needle, $values, (bool) $strict);
}

legacy_compat_internal_register('helpers', 'legacy_safe_in_array');

/**
 * Implode legacy values without failing on reversed argument order.
 *
 * Historically implode() accepted both implode($glue, $pieces) and the older
 * reversed implode($pieces, $glue) order. PHP 8 removed the reversed order.
 *
 * Compatibility type: migration helper.
 *
 * Return behavior:
 * - Returns the imploded string for array and Traversable pieces.
 * - Returns null when the arguments cannot be represented honestly.
 *
 * Limitations:
 * - Strict mode does not coerce stray scalars into synthetic one-item arrays
 *   because that can silently distort data models.
 */
function legacy_safe_implode($first, $second = null)
{
    if (is_array($first) || $first instanceof Traversable) {
        $pieces = legacy_compat_internal_iterable_to_array($first, true);
        $glue = $second === null ? '' : legacy_compat_internal_stringify($second);
    } elseif (is_array($second) || $second instanceof Traversable) {
        $pieces = legacy_compat_internal_iterable_to_array($second, true);
        $glue = legacy_compat_internal_stringify($first);
    } else {
        return null;
    }

    if ($glue === null || $pieces === null) {
        return null;
    }

    return implode($glue, $pieces);
}

legacy_compat_internal_register('helpers', 'legacy_safe_implode');

/**
 * Explode a string while tolerating null subjects.
 *
 * Historically many internal string functions accepted null through loose
 * coercion. PHP 8 now throws ValueError or TypeError for bad separators.
 *
 * Compatibility type: migration helper.
 *
 * Return behavior:
 * - Returns explode() output for valid separators and string-compatible values.
 * - Returns false when the separator is empty or invalid.
 *
 * Limitations:
 * - Empty separators still fail because there is no honest split behavior for
 *   an empty delimiter.
 */
function legacy_safe_explode($separator, $string, $limit = PHP_INT_MAX)
{
    $separator = legacy_compat_internal_stringify($separator, false);
    $subject = legacy_compat_internal_stringify($string);

    if ($separator === null || $separator === '') {
        return false;
    }

    if ($subject === null) {
        return false;
    }

    $limit = (int) $limit;

    if ($limit === 0) {
        $limit = 1;
    }

    return explode($separator, $subject, $limit);
}

legacy_compat_internal_register('helpers', 'legacy_safe_explode');

/**
 * Trim a string-compatible value without crashing on null.
 *
 * Historically trim() accepted null through loose coercion. PHP 8 hardens
 * those calls.
 *
 * Compatibility type: migration helper.
 *
 * Return behavior:
 * - Returns trim() output for string-compatible values.
 * - Returns null when the subject cannot be represented honestly.
 *
 * Limitations:
 * - Arrays and non-stringable objects are rejected instead of being flattened.
 */
function legacy_safe_trim($value, $characters = " \n\r\t\v\0")
{
    $string = legacy_compat_internal_stringify($value);
    $characterMask = legacy_compat_internal_stringify($characters);

    if ($string === null || $characterMask === null) {
        return null;
    }

    return trim($string, $characterMask);
}

legacy_compat_internal_register('helpers', 'legacy_safe_trim');

/**
 * Return a boolean-safe strpos() result for old truthiness checks.
 *
 * Historically many legacy code bases used strpos() directly in boolean
 * contexts and accidentally treated offset 0 as false.
 *
 * Compatibility type: migration helper.
 *
 * Return behavior:
 * - Returns true when the needle is found, including at position 0.
 * - Returns false when the needle is absent or inputs are invalid.
 *
 * Limitations:
 * - This helper deliberately returns only a boolean and cannot expose the
 *   original numeric offset.
 */
function legacy_safe_strpos_bool($haystack, $needle, $offset = 0)
{
    $haystack = legacy_compat_internal_stringify($haystack);
    $needle = legacy_compat_internal_stringify($needle);

    if ($haystack === null || $needle === null) {
        return false;
    }

    if ($needle === '') {
        return true;
    }

    return strpos($haystack, $needle, (int) $offset) !== false;
}

legacy_compat_internal_register('helpers', 'legacy_safe_strpos_bool');

/**
 * Check whether a value is safe to hand into foreach as array-like data.
 *
 * Historically many legacy code paths assumed null and scalars were iterable.
 * PHP 8 now warns or throws more aggressively around invalid iteration.
 *
 * Compatibility type: migration helper.
 *
 * Return behavior:
 * - Returns true for arrays and Traversable values.
 * - Returns false otherwise.
 *
 * Limitations:
 * - This helper does not normalize values; it only reports whether iteration is
 *   safe to attempt.
 */
function legacy_safe_is_iterable_array($value)
{
    return is_array($value) || $value instanceof Traversable;
}

legacy_compat_internal_register('helpers', 'legacy_safe_is_iterable_array');

/**
 * Merge arrays and Traversable values without loose scalar coercion.
 *
 * Historically loose code often passed null or Traversable objects into
 * array_merge(). PHP 8 now throws TypeError on invalid inputs.
 *
 * Compatibility type: migration helper.
 *
 * Return behavior:
 * - Returns a merged array for arrays and Traversable values.
 * - Ignores null inputs.
 * - Returns null when a non-iterable input is encountered.
 *
 * Limitations:
 * - Strict mode refuses stray scalar inputs instead of guessing how they should
 *   be merged.
 */
function legacy_safe_array_merge(...$values)
{
    $result = [];

    foreach ($values as $value) {
        if ($value === null) {
            continue;
        }

        if (is_array($value)) {
            $result = array_merge($result, $value);
            continue;
        }

        if ($value instanceof Traversable) {
            $result = array_merge($result, iterator_to_array($value, true));
            continue;
        }

        return null;
    }

    return $result;
}

legacy_compat_internal_register('helpers', 'legacy_safe_array_merge');

/**
 * Run preg_match() after legacy-safe subject normalization.
 *
 * Historically null subjects were coerced to empty strings by many internal
 * functions. PHP 8 hardens those calls.
 *
 * Compatibility type: migration helper.
 *
 * Return behavior:
 * - Returns preg_match() output for valid pattern and string-compatible subject.
 * - Returns false when the subject cannot be represented honestly.
 *
 * Limitations:
 * - Pattern validation still belongs to PCRE and can emit its own warnings.
 */
function legacy_safe_preg_match($pattern, $subject, &$matches = null, $flags = 0, $offset = 0)
{
    $subject = legacy_compat_internal_stringify($subject);

    if ($subject === null) {
        if (func_num_args() > 2) {
            $matches = [];
        }

        return false;
    }

    return preg_match($pattern, $subject, $matches, (int) $flags, (int) $offset);
}

legacy_compat_internal_register('helpers', 'legacy_safe_preg_match');

/**
 * Run preg_replace() after legacy-safe subject normalization.
 *
 * Historically null subjects were coerced to empty strings by many internal
 * functions. PHP 8 hardens those calls.
 *
 * Compatibility type: migration helper.
 *
 * Return behavior:
 * - Returns preg_replace() output for valid pattern and normalized subject.
 * - Returns null when the subject cannot be represented honestly.
 *
 * Limitations:
 * - Pattern validation still belongs to PCRE and can emit its own warnings.
 */
function legacy_safe_preg_replace($pattern, $replacement, $subject, $limit = -1, &$count = 0)
{
    if (is_array($subject)) {
        $normalized = [];

        foreach ($subject as $key => $value) {
            $string = legacy_compat_internal_stringify($value);

            if ($string === null) {
                return null;
            }

            $normalized[$key] = $string;
        }

        return preg_replace($pattern, $replacement, $normalized, (int) $limit, $count);
    }

    $subject = legacy_compat_internal_stringify($subject);

    if ($subject === null) {
        return null;
    }

    return preg_replace($pattern, $replacement, $subject, (int) $limit, $count);
}

legacy_compat_internal_register('helpers', 'legacy_safe_preg_replace');

/*
|--------------------------------------------------------------------------
| Optional Diagnostics
|--------------------------------------------------------------------------
*/

/**
 * Return a structured report of the currently loaded compatibility layer.
 *
 * Historical note:
 * - This helper is new and exists to support operational visibility.
 * - It does not map to a removed PHP core function.
 *
 * Compatibility type: diagnostic helper.
 *
 * Return behavior:
 * - Returns an array describing the mode, PHP version, loaded polyfills,
 *   loaded helpers, and notable limitations.
 *
 * Limitations:
 * - The report reflects only the current request and only this compatibility
 *   file, not the entire application stack.
 */
function legacy_compat_get_report()
{
    $report = $GLOBALS['legacy_compat_runtime'];
    $report['php_version'] = PHP_VERSION;
    $report['php_version_id'] = PHP_VERSION_ID;

    sort($report['polyfills']);
    sort($report['helpers']);
    sort($report['limitations']);

    return $report;
}

legacy_compat_internal_register('helpers', 'legacy_compat_get_report');

/*
|--------------------------------------------------------------------------
| Optional Opt-In Error Softening
|--------------------------------------------------------------------------
*/

/**
 * Register a narrow soft error handler for explicit legacy migrations.
 *
 * Historical note:
 * - This helper is new and exists to make staged PHP 8 migrations easier.
 * - It does not map to a removed PHP core function.
 *
 * Compatibility type: optional migration helper.
 *
 * Return behavior:
 * - Returns the previously registered error handler from set_error_handler().
 *
 * Limitations:
 * - The handler is intentionally narrow and only suppresses messages matching
 *   the configured regex list and severity mask.
 * - It should be enabled only by projects that consciously accept the risk of
 *   hiding known non-fatal migration noise.
 */
function legacy_compat_register_soft_error_handler(array $options = [])
{
    $defaultPatterns = [
        '/Function (strftime|gmstrftime|utf8_encode|utf8_decode)\(\) is deprecated/i',
        '/Passing null to parameter #\d+ .* of type string is deprecated/i',
        '/Passing null to parameter #\d+ .* of type array is deprecated/i',
    ];

    $patterns = $defaultPatterns;

    if (isset($options['patterns']) && is_array($options['patterns'])) {
        $patterns = array_merge($patterns, $options['patterns']);
    }

    $severities = E_DEPRECATED | E_USER_DEPRECATED | E_WARNING | E_USER_WARNING;

    if (isset($options['severities']) && is_int($options['severities'])) {
        $severities = $options['severities'];
    }

    return set_error_handler(
        static function ($severity, $message, $file, $line) use ($patterns, $severities) {
            if (($severity & $severities) === 0) {
                return false;
            }

            if ((error_reporting() & $severity) === 0) {
                return false;
            }

            return legacy_compat_internal_message_matches_any($message, $patterns);
        },
        $severities
    );
}

legacy_compat_internal_register('helpers', 'legacy_compat_register_soft_error_handler');