ip2range() - Code Metrics - elkarte/Elkarte - Measure and Improve Code Quality continuously with Scrutinizer

ip2range() C
last analyzed 2026-01-24 21:07 UTC

↳ Parent: Project
Complexity

Conditions	13
Paths	18
Size

Total Lines	69
Code Lines	31
Duplication

Lines	0
Ratio	0 %
Code Coverage

Tests	11
CRAP Score	25.6195
Importance

Changes
Metric	Value
cc	13
eloc	31
c	0
b	0
f	0
nc	18
nop	1
dl	0
loc	69
rs	6.6166
ccs	11
cts	19
cp	0.5789
crap	25.6195
How to fix Long Method Complexity

<?php

/**
 * This file has all the main functions in it that relate to, well, everything.
 *
 * @package   ElkArte Forum
 * @copyright ElkArte Forum contributors
 * @license   BSD http://opensource.org/licenses/BSD-3-Clause (see accompanying LICENSE.txt file)
 *
 * This file contains code covered by:
 * copyright: 2011 Simple Machines (http://www.simplemachines.org)
 *
 * @version 2.0 Beta 1
 *
 */

use ElkArte\Cache\Cache;
use ElkArte\Database\AbstractResult;
use ElkArte\Debug;
use ElkArte\Helper\Censor;
use ElkArte\Helper\ConstructPageIndex;
use ElkArte\Helper\GenericList;
use ElkArte\Helper\TokenHash;
use ElkArte\Helper\Util;
use ElkArte\Hooks;
use ElkArte\Http\Headers;
use ElkArte\Languages\Loader;
use ElkArte\Menu\MenuContext;
use ElkArte\Notifications\Notifications;
use ElkArte\Request;
use ElkArte\Search\Search;
use ElkArte\Themes\DefaultTheme\Theme;
use ElkArte\UrlGenerator\UrlGenerator;
use ElkArte\User;

/**
 * Updates the settings table as well as $modSettings... only does one at a time if $update is true.
 *
 * What it does:
 *
 * - Updates both the settings table and $modSettings array.
 * - All of changeArray's indexes and values are assumed to have escaped apostrophes (')!
 * - If a variable is already set to what you want to change it to, that
 *   Variable will be skipped over; it would be unnecessary to reset.
 * - When update is true, UPDATEs will be used instead of REPLACE.
 * - When update is true, the value can be true or false to increment
 *  or decrement it, respectively.
 *
 * @param array $changeArray An associative array of what we're changing in 'setting' => 'value' format
 * @param bool $update Use an UPDATE query instead of a REPLACE query
 */
function updateSettings($changeArray, $update = false)
{
	global $modSettings;

	$db = database();
	$cache = Cache::instance();

	if (empty($changeArray) || !is_array($changeArray))
	{
		return;
	}

	// In some cases, this may be better and faster, but for large sets we don't want so many UPDATEs.
	if ($update)
	{
		foreach ($changeArray as $variable => $value)
		{
			$db->query('', '
				UPDATE {db_prefix}settings
				SET value = {' . ($value === false || $value === true ? 'raw' : 'string') . ':value}
				WHERE variable = {string:variable}',
				[
					'value' => $value === true ? 'value + 1' : ($value === false ? 'value - 1' : $value),
					'variable' => $variable,
				]
			);

			$modSettings[$variable] = $value === true ? $modSettings[$variable] + 1 : ($value === false ? $modSettings[$variable] - 1 : $value);
		}

		// Clean out the cache and make sure the cobwebs are gone too.
		$cache->remove('modSettings');

		return;
	}

	$replaceArray = [];
	foreach ($changeArray as $variable => $value)
	{
		// Don't bother if it's already like that ;).
		if (isset($modSettings[$variable]) && $modSettings[$variable] === $value)
		{
			continue;
		}

		// If the variable isn't set, but would only be set to nothing'ness, then don't bother setting it.
		if (!isset($modSettings[$variable]) && empty($value))
		{
			continue;
		}

		$replaceArray[] = [$variable, $value];

		$modSettings[$variable] = $value;
	}

	if (empty($replaceArray))
	{
		return;
	}

	$db->replace(
		'{db_prefix}settings',
		['variable' => 'string-255', 'value' => 'string-65534'],
		$replaceArray,
		['variable']
	);

	// Kill the cache - it needs redoing now, but we won't bother ourselves with that here.
	$cache->remove('modSettings');
}

/**
 * Deletes one setting from the settings table and takes care of $modSettings as well
 *
 * @param string|string[] $toRemove the setting or the settings to be removed
 */
function removeSettings($toRemove)
{
	global $modSettings;

	$db = database();

	if (empty($toRemove))
	{
		return;
	}

	if (!is_array($toRemove))
	{
		$toRemove = [$toRemove];
	}

	// Remove the setting from the db
	$db->query('', '
		DELETE FROM {db_prefix}settings
		WHERE variable IN ({array_string:setting_name})',
		[
			'setting_name' => $toRemove,
		]
	);

	// Remove it from $modSettings now so it does not persist
	foreach ($toRemove as $setting)
	{
		if (isset($modSettings[$setting]))
		{
			unset($modSettings[$setting]);
		}
	}

	// Kill the cache - it needs redoing now, but we won't bother ourselves with that here.
	Cache::instance()->remove('modSettings');
}

/**
 * Constructs a page list.
 *
 * @depreciated since 2.0
 *
 */
function constructPageIndex($base_url, &$start, $max_value, $num_per_page, $flexible_start = false, $show = [])
{
	$pageindex = new ConstructPageIndex($base_url, $start, $max_value, $num_per_page, $flexible_start, $show);
	return $pageindex->getPageIndex();
}

/**
 * Formats a number.
 *
 * What it does:
 *
 * - Uses the format of number_format to decide how to format the number -
 * for example, it might display "1 234,50".
 * - Caches the formatting data from the setting for optimization.
 *
 * @param float $number The float value to apply comma formatting
 * @param int|bool $override_decimal_count = false or number of decimals
 *
 * @return string
 */
function comma_format($number, $override_decimal_count = false)
{
	global $txt;
	static $thousands_separator = null, $decimal_separator = null, $decimal_count = null;

	// Cache these values...
	if ($decimal_separator === null)
	{
		// Not set for whatever reason?
		if (empty($txt['number_format']) || preg_match('~^1(\D*)?234(\D*)(0*?)$~', $txt['number_format'], $matches) !== 1)
		{
			return $number;
		}

		// Cache these each load...
		$thousands_separator = $matches[1];
		$decimal_separator = $matches[2];
		$decimal_count = strlen($matches[3]);
	}

	// Format the string with our friend, number_format.
	$decimals = ((float) $number === $number) ? ($override_decimal_count === false ? $decimal_count : $override_decimal_count) : 0;
	return number_format((float) $number, (int) $decimals, $decimal_separator, $thousands_separator);
}

/**
 * Formats a number to a multiple of thousands x, x k, x M, x G, x T
 *
 * @param float $number The value to format
 * @param int|bool $override_decimal_count = false or number of decimals
 *
 * @return string
 */
function thousands_format($number, $override_decimal_count = false)
{
	foreach (['', ' k', ' M', ' G', ' T'] as $kb)
	{
		if ($number < 1000)
		{
			break;
		}

		$number /= 1000;
	}

	return comma_format($number, $override_decimal_count) . $kb;

}

/**
 * Formats a number to a computer byte size value xB, xKB, xMB, xGB
 *
 * @param int $number
 *
 * @return string
 */
function byte_format($number)
{
	global $txt;

	foreach (['byte', 'kilobyte', 'megabyte', 'gigabyte'] as $kb)
	{
		if ($number < 1024)
		{
			break;
		}

		$number /= 1024;
	}

	return comma_format($number) . ' ' . $txt[$kb];

}

/**
 * Format a time to make it look purdy.
 *
 * What it does:
 *
 * - Returns a pretty formatted version of time based on the user's format in User::$info->time_format.
 * - Applies all necessary time offsets to the timestamp, unless offset_type is set.
 * - If todayMod is set and show_today was not specified or true, an
 *   alternate format string is used to show the date with something to show it is "today" or "yesterday".
 * - Performs localization (more than just strftime would do alone.)
 *
 * @param int $log_time A unix timestamp
 * @param string|bool $show_today = true show "Today"/"Yesterday",
 *   false shows the date, a string can force a date format to use %b %d, %Y
 * @param string|bool $offset_type = false If false, uses both user time offset and forum offset.
 *   If 'forum', uses only the forum offset. Otherwise, no offset is applied.
 *
 * @return string
 */
function standardTime($log_time, $show_today = true, $offset_type = false)
{
	global $txt, $modSettings;
	static $non_twelve_hour, $is_win = null;

	if ($is_win === null)
	{
		$is_win = detectServer()->is('windows');
	}

	// Offset the time.
	if (!$offset_type)
	{
		$time = $log_time + (User::$info->time_offset + $modSettings['time_offset']) * 3600;

	}
	// Just the forum offset?
	elseif ($offset_type === 'forum')
	{
		$time = $log_time + $modSettings['time_offset'] * 3600;
	}
	else
	{
		$time = $log_time;
	}

	// We can't have a negative date (on Windows, at least.)
	if ($log_time < 0)
	{
		$log_time = 0;
	}

	// Today and Yesterday?
	if ($modSettings['todayMod'] >= 1 && $show_today === true)
	{
		// Get the current time.
		$nowtime = forum_time();

		$then = @getdate($time);
		$now = @getdate($nowtime);

		// Try to make something of a time format string...
		$s = !str_contains(User::$info->time_format, '%S') ? '' : ':%S';
		$s = !str_contains(/** @scrutinizer ignore-type */ User::$info->time_format, '%S') ? '' : ':%S';
		if (!str_contains(User::$info->time_format, '%H') && !str_contains(User::$info->time_format, '%T'))
		{
			$h = !str_contains(User::$info->time_format, '%l') ? '%I' : '%l';
			$today_fmt = $h . ':%M' . $s . ' %p';
		}
		else
		{
			$today_fmt = '%H:%M' . $s;
		}

		// Same day of the year, same year.... Today!
		if ($then['yday'] === $now['yday'] && $then['year'] === $now['year'])
		{
			return sprintf($txt['today'], standardTime($log_time, $today_fmt, $offset_type));
		}

		// Day-of-year is one less and the same year, or it's the first of the year and that's the last of the year...
		if ((int) $modSettings['todayMod'] === 2
			&& (($then['yday'] === $now['yday'] - 1 && $then['year'] === $now['year'])
				|| (($now['yday'] === 0 && $then['year'] === $now['year'] - 1) && $then['mon'] === 12 && $then['mday'] === 31)))
		{
			return sprintf($txt['yesterday'], standardTime($log_time, $today_fmt, $offset_type));
		}
	}

	$str = is_bool($show_today) ? User::$info->time_format : $show_today;

	// Windows requires a slightly different language code identifier (LCID).
	// https://msdn.microsoft.com/en-us/library/cc233982.aspx
	if ($is_win)
	{
		$txt['lang_locale'] = str_replace('_', '-', $txt['lang_locale']);
	}

	if (setlocale(LC_TIME, $txt['lang_locale']))
	{
		if (!isset($non_twelve_hour))
		{
			$non_twelve_hour = trim(Util::strftime('%p')) === '';
		}

		if ($non_twelve_hour && str_contains($str, '%p'))
		{
			$str = str_replace('%p', (Util::strftime('%H', $time) < 12 ? $txt['time_am'] : $txt['time_pm']), $str);
		}

		foreach (['%a', '%A', '%b', '%B'] as $token)
		{
			if (str_contains($str, $token))
			{
				$str = str_replace($token, empty($txt['lang_capitalize_dates']) ? Util::strftime($token, $time) : Util::ucwords(Util::strftime($token, $time)), $str);
			}
		}
	}
	else
	{
		// Do-it-yourself time localization.  Fun.
		foreach (['%a' => 'days_short', '%A' => 'days', '%b' => 'months_short', '%B' => 'months'] as $token => $text_label)
		{
			if (str_contains($str, $token))
			{
				$str = str_replace($token, $txt[$text_label][(int) Util::strftime($token === '%a' || $token === '%A' ? '%w' : '%m', $time)], $str);
			}
		}

		if (str_contains($str, '%p'))
		{
			$str = str_replace('%p', (Util::strftime('%H', $time) < 12 ? $txt['time_am'] : $txt['time_pm']), $str);
		}
	}

	// Windows doesn't support %e; on some versions, strftime fails altogether if used, so let's prevent that.
	if ($is_win && str_contains($str, '%e'))
	{
		$str = str_replace('%e', ltrim(Util::strftime('%d', $time), '0'), $str);
	}

	// Format any other characters.
	return Util::strftime($str, $time);
}

/**
 * Used to render a timestamp to html5 <time> tag format.
 *
 * @param int $timestamp A unix timestamp
 *
 * @return string
 */
function htmlTime($timestamp)
{
	global $txt, $context;

	if (empty($timestamp))
	{
		return '';
	}

	$forumtime = forum_time(false, $timestamp);
	$timestamp = forum_time(true, $timestamp);
	$time = date('Y-m-d H:i', $timestamp);
	$stdtime = standardTime($timestamp, true, true);

	// @todo maybe htmlspecialchars on the title attribute?
	return '<time title="' . (empty($context['using_relative_time']) ? $txt['last_post'] : $stdtime) . '" datetime="' . $time . '" data-timestamp="' . $timestamp . '" data-forumtime="' . $forumtime . '">' . $stdtime . '</time>';
}

/**
 * Convert a given timestamp to UTC time in the format of Atom date format.
 *
 * This method takes a unix timestamp as input and converts it to UTC time in the format of
 * Atom date format (YYYY-MM-DDTHH:MM:SS+00:00).
 *
 * It considers the user's time offset, system's time offset, and the default timezone setting
 * from the modifications/settings administration panel.
 *
 * @param int $timestamp The timestamp to convert to UTC time.
 * @param int $userAdjust The timestamp is not to be adjusted for user offset
 * @return string The UTC time in the format of Atom date format.
 */
function utcTime($timestamp, $userAdjust = false)
{
	global $modSettings;

	// Back out user time
	if ($userAdjust === true && !empty(User::$info->time_offset))

	{
		$timestamp -= ($modSettings['time_offset'] + User::$info->time_offset) * 3600;
	}

	// Using the system timezone offset, format the date
	try
	{
		$tz = empty($modSettings['default_timezone']) ? 'UTC' : $modSettings['default_timezone'];
		$date = new DateTime('@' . $timestamp, new DateTimeZone($tz));
	}
	catch (Exception)
	{
		return standardTime($timestamp);
	}

	// Something like 2012-12-21T11:11:00+00:00
	return $date->format(DateTimeInterface::ATOM);
}

/**
 * Gets the current time with offset.
 *
 * What it does:
 *
 * - Always applies the offset in the time_offset setting.
 *
 * @param bool $use_user_offset = true if use_user_offset is true, applies the user's offset as well
 * @param int|null $timestamp = null A unix timestamp (null to use current time)
 *
 * @return int seconds since the unix epoch
 */
function forum_time($use_user_offset = true, $timestamp = null): int
{
	global $modSettings;

	if ($timestamp === null)
	{
		$timestamp = time();
	}
	elseif ($timestamp === 0)
	{
		return 0;
	}

	return $timestamp + ($modSettings['time_offset'] + ($use_user_offset ? User::$info->time_offset : 0)) * 3600;

}

/**
 * Removes special entities from strings.  Compatibility...
 *
 * - Faster than html_entity_decode
 * - Removes the base entities (&amp; &quot; &#039; &lt; and &gt;.) from text with htmlspecialchars_decode
 * - Additionally, converts &nbsp with str_replace
 *
 * @param string $string The string to apply htmlspecialchars_decode
 *
 * @return string string without entities
 */
function un_htmlspecialchars($string)
{
	if (empty($string))
	{
		return $string;
	}

	$string = htmlspecialchars_decode($string, ENT_QUOTES);

	return str_replace('&nbsp;', ' ', $string);
}

/**
 * Lexicographic permutation function.
 *
 * This is a special type of permutation that involves the order of the set. The next
 * lexicographic permutation of '32541' is '34125'. Numerically, it is simply the smallest
 * set larger than the current one.
 *
 * The benefit of this over a recursive solution is that the whole list does NOT need
 * to be held in memory. So it's actually possible to run 30! permutations without
 * causing a memory overflow.
 *
 * Source: O'Reilly PHP Cookbook
 *
 * @param array $p The array keys to apply permutation
 * @param int $size The size of our permutation array
 *
 * @return array|bool the next permutation of the passed array $p
 */
function pc_next_permutation($p, $size)
{
	// Slide down the array looking for where we're smaller than the next guy
	for ($i = $size - 1; isset($p[$i]) && $p[$i] >= $p[$i + 1]; --$i)
	{
		// Required to set $i
	}

	// If this doesn't occur, we've finished our permutations
	// the array is reversed: (1, 2, 3, 4) => (4, 3, 2, 1)
	if ($i === -1)
	{
		return false;
	}

	// Slide down the array looking for a bigger number than what we found before
	for ($j = $size; $p[$j] <= $p[$i]; --$j)
	{
		// Required to set $j
	}

	// Swap them
	$tmp = $p[$i];
	$p[$i] = $p[$j];
	$p[$j] = $tmp;

	// Now reverse the elements in between by swapping the ends
	for (++$i, $j = $size; $i < $j; ++$i, --$j)
	{
		$tmp = $p[$i];
		$p[$i] = $p[$j];
		$p[$j] = $tmp;
	}

	return $p;
}

/**
 * Ends execution and redirects the user to a new location
 *
 * What it does:
 *
 * - Makes sure the browser doesn't come back and repost the form data.
 * - Should be used whenever anything is posted.
 * - Diverts final execution to obExit() which means an end to processing and sending of final output
 *
 * @event integrate_redirect called before headers are sent
 * @param string $setLocation = '' The URL to redirect to
 *
 * Never returns.  However, it will return the $setLocation string when run via the testbed so that
 * controller tests can complete.
 */
function redirectexit($setLocation = ''): never
{
	global $db_show_debug;

	// Note to developers.  The testbed will automatically add the following, allowing phpunit test returns
	//if (defined("PHPUNITBOOTSTRAP") && defined("STDIN")){return $setLocation;} see setup-elkarte.sh

	// Send headers, call integration, do maintenance
	Headers::instance()
		->removeHeader('all')
		->redirect($setLocation)
		->send();

	// Debugging.
	if ($db_show_debug === true)
	{
		$_SESSION['debug_redirect'] = Debug::instance()->get_db();
	}

	obExit(false);
}

/**
 * Ends execution.
 *
 * What it does:
 *
 * - Takes care of template loading and remembering the previous URL.
 * - Calls ob_start() with ob_sessrewrite to fix URLs if necessary.
 *
 * @event integrate_invalid_old_url allows adding to "from" urls we don't save
 * @event integrate_exit inform portal, etc. that we're integrated with to exit
 * @param bool|null $header = null Output the header
 * @param bool|null $do_footer = null Output the footer
 * @param bool $from_index = false If we're coming from index.php
 * @param bool $from_fatal_error = false If we are exiting due to a fatal error
 * @throws \ElkArte\Exceptions\Exception
 */
function obExit($header = null, $do_footer = null, $from_index = false, $from_fatal_error = false): never
function obExit($header = null, $do_footer = null, /** @scrutinizer ignore-unused */ $from_index = false, $from_fatal_error = false): never
{
	global $context, $txt, $db_show_debug;

	static $header_done = false, $footer_done = false, $level = 0, $has_fatal_error = false;

	// Attempt to prevent a recursive loop.
	++$level;
	if ($level > 1 && !$from_fatal_error && !$has_fatal_error)
	{
		exit;

	}

	if ($from_fatal_error)
	{
		$has_fatal_error = true;
	}

	$do_header = $header ?? !$header_done;
	$do_footer = $do_footer ?? $do_header;

	// Has the template/header been done yet?
	if ($do_header)
	{
		handleMaintenance();

		// Was the page title set last minute? Also update the HTML safe one.
		if (!empty($context['page_title']) && empty($context['page_title_html_safe']))
		{
			$context['page_title_html_safe'] = Util::htmlspecialchars(un_htmlspecialchars($context['page_title'])) . (empty($context['current_page']) ? '' : ' - ' . $txt['page'] . ' ' . ($context['current_page'] + 1));
		}

		// Start up the session URL fixer.
		ob_start('ob_sessrewrite');

		call_integration_buffer();

		// Display the screen in the logical order.
		template_header();
		$header_done = true;
	}

	if ($do_footer)
	{
		// Show the footer.
		theme()->getTemplates()->loadSubTemplate($context['sub_template'] ?? 'main');

		// Just so we don't get caught in an endless loop of errors from the footer...
		if (!$footer_done)
		{
			$footer_done = true;
			template_footer();

			// Add $db_show_debug = true; to Settings.php if you want to show the debugging information.
			// (since this is just debugging... it's okay that it's after </html>.)
			if (($db_show_debug === true)
				&& !isset($_REQUEST['api'])
				&& ((!isset($_GET['action']) || $_GET['action'] !== 'viewquery') && !isset($_GET['api'])))
			{
				Debug::instance()->display();
			}
		}
	}

	// Need a user agent
	$req = Request::instance();

	setOldUrl();

	// For session check verification... don't switch browsers...
	$_SESSION['USER_AGENT'] = $req->user_agent();

	// Hand off the output to the portal, etc. we're integrated with.
	call_integration_hook('integrate_exit', [$do_footer]);

	// Note to developers.  The testbed will add the following, allowing phpunit test returns
	//if (defined("PHPUNITBOOTSTRAP") && defined("STDIN")){return;}

	exit;

}

/**
 * Takes care of a few dynamic maintenance items
 */
function handleMaintenance()
{
	global $context;

	// Clear out the stat cache.
	trackStats();

	// Send off any notifications accumulated
	Notifications::instance()->send();

	// Queue any mail that needs to be sent
	if (!empty($context['flush_mail']))
	{
		// @todo this relies on 'flush_mail' being only set in AddMailQueue itself... :\
		AddMailQueue(true);
	}
}

/**
 * Sets the old URL in the session for reference if certain conditions are met.
 *
 * This method tracks the current URL and stores it in the session under the provided index,
 * unless the URL matches a set of invalid patterns. A hook allows customization of the
 * invalid patterns.
 *
 * @param string $index The session index under which the URL will be stored. Defaults to 'old_url'.
 * @return void
 */
function setOldUrl($index = 'old_url'): void
{
	// Remember this URL in case someone doesn't like sending HTTP_REFERER.
	$invalid_old_url = [
		'action=dlattach',
		'action=jsoption',
		';api=xml',
		';api=json',
		'action=mentions',
	];
	call_integration_hook('integrate_invalid_old_url', [&$invalid_old_url]);
	$make_old = true;
	foreach ($invalid_old_url as $url)
	{
		if (str_contains($_SERVER['REQUEST_URL'], $url))
		{
			$make_old = false;
			break;
		}
	}

	if ($make_old)
	{
		$_SESSION[$index] = $_SERVER['REQUEST_URL'];
	}
}

/**
 * Sets the class of the current topic based on is_very_hot, veryhot, hot, etc.
 *
 * @param array $topic_context array of topic information
 */
function determineTopicClass(&$topic_context)
{
	$topic_context['class'] = empty($topic_context['is_poll']) ? 'i-normal' : 'i-poll';

	// Set a topic class depending on locked status and number of replies.
	if ($topic_context['is_very_hot'])
	{
		$topic_context['class'] = 'i-hot colorize-red';
	}
	elseif ($topic_context['is_hot'])
	{
		$topic_context['class'] = 'i-hot colorize-yellow';
	}

	if ($topic_context['is_sticky'])
	{
		$topic_context['class'] = 'i-sticky';
	}

	if ($topic_context['is_locked'])
	{
		$topic_context['class'] = 'i-locked';
	}
}

/**
 * Sets up the basic theme context stuff.
 *
 * @param bool $forceload defaults to false
 */
function setupThemeContext($forceload = false)
{
	theme()->setupThemeContext($forceload);
}

/**
 * Helper function to convert memory string settings to bytes
 *
 * @param string|bool $val The byte string, like 256M or 1G
 *
 * @return int The string converted to a proper integer in bytes
 */
function memoryReturnBytes($val)
{
	// Treat blank values as 0
	$val = is_bool($val) || empty($val) ? '0' : trim($val);

	// Separate the number from the designator, if any
	preg_match('~(\d+)(.*)~', $val, $matches);
	$num = (int) $matches[1];
	$last = strtolower(substr($matches[2] ?? '', 0, 1));

	// Convert to bytes
	switch ($last)
	{
		// fall through select g = 1024*1024*1024
		case 'g':
			$num *= 1024;
		// fall through select m = 1024*1024
		case 'm':
			$num *= 1024;
		// fall through select k = 1024
		case 'k':
			$num *= 1024;
	}

	return $num;
}

/**
 * This is the only template included in the sources.
 * @return void
 */
function template_rawdata()
{
	theme()->template_rawdata();
}

/**
 * The header template
 * @return void
 */
function template_header()
{
	theme()->template_header();
}

/**
 * Show the copyright.
 * @return void
 */
function theme_copyright()
{
	theme()->theme_copyright();
}

/**
 * The template footer
 * @return void
 */
function template_footer()
{
	theme()->template_footer();
}

/**
 * Output the JavaScript files
 *
 * @depreciated since 2.0, only for old theme support
 * @return void
 */
function template_javascript()
{
	theme()->themeJs()->template_javascript();
}

/**
 * Output the CSS files
 *
 * @depreciated since 2.0, only for old theme support
 * @return void
 */
function template_css()
{
	theme()->themeCss()->template_css();
}

/**
 * Calls on template_show_error from index.template.php to show warnings
 * and security errors for admins
 * @return void
 */
function template_admin_warning_above()
{
	theme()->template_admin_warning_above();
}

/**
 * Convert IP address to IP range
 *
 *  - Internal function used to convert a user-readable format to a format suitable for the database.
 *
 * @param string $fullip The IP address to convert
 * @return array The IP range in the format [ ['low' => 'low_value_1', 'high' => 'high_value_1'], ... ]
 * If the input IP address is invalid or cannot be converted, an empty array is returned.
 */
function ip2range($fullip)
{
	// If its IPv6, validate it first.
	if (isValidIPv6($fullip))
	{
		$ip_parts = explode(':', expandIPv6($fullip, false));
		$ip_parts = explode(':', /** @scrutinizer ignore-type */ expandIPv6($fullip, false));
		$ip_array = [];

		if (count($ip_parts) !== 8)
		{
			return [];
		}

		for ($i = 0; $i < 8; $i++)
		{
			if ($ip_parts[$i] === '*')
			{
				$ip_array[$i] = ['low' => '0', 'high' => hexdec('ffff')];
			}
			elseif (preg_match('/^([0-9A-Fa-f]{1,4})-([0-9A-Fa-f]{1,4})$/', $ip_parts[$i], $range) === 1)
			{
				$ip_array[$i] = ['low' => hexdec($range[1]), 'high' => hexdec($range[2])];
			}
			elseif (is_numeric(hexdec($ip_parts[$i])))
			{
				$ip_array[$i] = ['low' => hexdec($ip_parts[$i]), 'high' => hexdec($ip_parts[$i])];
			}
		}

		return $ip_array;
	}

	// Pretend that 'unknown' is 255.255.255.255. (since that can't be an IP anyway.)
	if ($fullip === 'unknown')
	{
		$fullip = '255.255.255.255';
	}

	$ip_parts = explode('.', $fullip);
	$ip_array = [];

	if (count($ip_parts) !== 4)
	{
		return [];
	}

	for ($i = 0; $i < 4; $i++)
	{
		if ($ip_parts[$i] === '*')
		{
			$ip_array[$i] = ['low' => '0', 'high' => '255'];
		}
		elseif (preg_match('/^(\d{1,3})-(\d{1,3})$/', $ip_parts[$i], $range) === 1)
		{
			$ip_array[$i] = ['low' => $range[1], 'high' => $range[2]];
		}
		elseif (is_numeric($ip_parts[$i]))
		{
			$ip_array[$i] = ['low' => $ip_parts[$i], 'high' => $ip_parts[$i]];
		}
	}

	// Makes it simpler to work with.
	$ip_array[4] = ['low' => 0, 'high' => 0];
	$ip_array[5] = ['low' => 0, 'high' => 0];
	$ip_array[6] = ['low' => 0, 'high' => 0];
	$ip_array[7] = ['low' => 0, 'high' => 0];

	return $ip_array;
}

/**
 * Look up an IP; try shell_exec first because we can do a timeout on it.
 *
 * @param string $ip A full dot notation IP address
 *
 * @return string
 */
function host_from_ip($ip)
{
	global $modSettings;

	$cache = Cache::instance();

	$host = '';
	if (empty($ip) || $cache->getVar($host, 'hostlookup-' . $ip, 600))
	{
		return $host;
	}

	$t = microtime(true);

	// Check if shell_exec is on the list of disabled functions.
	if (function_exists('shell_exec'))
	{
		// Try the Linux host command, perhaps?
		if (PHP_OS_FAMILY !== 'Windows' && mt_rand(0, 1) === 1)
		{
			if (!isset($modSettings['host_to_dis']))
			{
				$test = @shell_exec('host -W 1 ' . @escapeshellarg($ip));
			}
			else
			{
				$test = @shell_exec('host ' . @escapeshellarg($ip));
			}

			$test = $test ?? '';

			// Did the host say it didn't find anything?
			if (stripos($test, 'not found') !== false)
			if (stripos(/** @scrutinizer ignore-type */ $test, 'not found') !== false)
			{
				$host = '';
			}
			// Invalid server option?
			elseif ((stripos($test, 'invalid option') || stripos($test, 'Invalid query name 1')) && !isset($modSettings['host_to_dis']))
			{
				updateSettings(['host_to_dis' => 1]);
			}
			// Maybe it found something, after all?
			elseif (preg_match('~\s(\S+?)\.\s~', $test, $match) === 1)
			elseif (preg_match('~\s(\S+?)\.\s~', /** @scrutinizer ignore-type */ $test, $match) === 1)
			{
				$host = $match[1];
			}
		}

		// This is nslookup; usually default on Windows, and possibly some Unix with bind-utils
		if ((empty($host) || PHP_OS_FAMILY === 'Windows') && mt_rand(0, 1) === 1)
		{
			$test = @shell_exec('nslookup -timeout=1 ' . @escapeshellarg($ip));

			if (stripos($test, 'Non-existent domain') !== false)
			if (stripos(/** @scrutinizer ignore-type */ $test, 'Non-existent domain') !== false)
			{
				$host = '';
			}
			elseif (preg_match('~(?:Name:|Name =)\s+(\S+)~i', $test, $match) === 1)
			elseif (preg_match('~(?:Name:|Name =)\s+(\S+)~i', /** @scrutinizer ignore-type */ $test, $match) === 1)
			{
				$host = $match[1];
			}
		}
	}

	// This is the last try :/.
	if (!isset($host))
	{
		$host = @gethostbyaddr($ip);
	}

	// It took a long time, so let's cache it!
	if (microtime(true) - $t > 0.5)
	{
		$cache->put('hostlookup-' . $ip, $host, 600);
	}

	return $host;
}

/**
 * Chops a string into words and prepares them to be inserted into (or searched from) the database.
 *
 * @param string $text The string to process
 *     - If encrypt = true, this is the maximum number of bytes to use in integer hashes (for searching)
 *     - If encrypt = false, this is the maximum number of letters in each word
 * @param bool $encrypt = false Used for custom search indexes to return an int[] array representing the words
 *
 * @return array
 */
function text2words($text, $encrypt = false)
{
	// Step 0: prepare numbers so they are good for search & index 1000.45 -> 1000_45
	$words = preg_replace('~([\d]+)[.-/]+(?=[\d])~u', '$1_', $text);

	// Step 1: Remove entities/things we don't consider words:
	$words = preg_replace('~(?:[\x0B\0\x{A0}\t\r\s\n(){}\\[\\]<>!@$%^*.,:+=`\~\?/\\\\]+|&(?:amp|lt|gt|quot);)+~u', ' ', strtr($words, ['<br />' => ' ']));

	// Step 2: Entities we left to letters, where applicable, lowercase.
	$words = un_htmlspecialchars(Util::strtolower($words));

	// Step 3: Ready to split apart and index!
	$words = explode(' ', $words);

	if ($encrypt)
	{
		$blocklist = getBlocklist();
		$returned_ints = [];

		// Only index unique words
		$words = array_unique($words);
		foreach ($words as $word)
		{
			$word = trim($word, "-_'");
			if ($word !== '' && !in_array($word, $blocklist) && Util::strlen($word) > 2)
			{
				// Get a hex representation of this word using a database indexing hash
				// designed to be fast while maintaining a low collision rate
				$encrypted = hash('murmur3a', $word);

				// Create an integer representation, the hash is an 8-char hex,
				// so the largest int will be 4294967295 which fits in db int(10)
				$returned_ints[$word] = hexdec($encrypted);
			}
		}

		return $returned_ints;
	}

	// Trim characters before and after and add slashes for database insertion.
	$returned_words = [];
	foreach ($words as $word)
	{
		if (($word = trim($word, "-_'")) !== '')
		{
			$returned_words[] = substr($word, 0, 20);
		}
	}

	// Filter out all words that occur more than once.
	return array_unique($returned_words);
}

/**
 * Get the blocklist from the search controller.
 *
 * @return array
 */
function getBlocklist()
{
	static $blocklist;

	if (!isset($blocklist))
	{
		$search = new Search();
		$blocklist = $search->getBlockListedWords();
		unset($search);
	}

	return $blocklist;
}

/**
 * Sets up all the top menu buttons
 *
 * What it does:
 *
 * - Defines every master item in the menu, as well as any sub-items
 * - Ensures the chosen action is set so the menu is highlighted
 * - Saves them in the cache if it is available and on
 * - Places the results in $context
 */
function setupMenuContext()
{
	(new MenuContext())->setupMenuContext();
}

/**
 * Process functions of an integration hook.
 *
 * What it does:
 *
 * - Calls all functions of the given hook.
 * - Supports static class method calls.
 *
 * @param string $hook The name of the hook to call
 * @param array $parameters = array() Parameters to pass to the hook
 *
 * @return array the results of the functions
 */
function call_integration_hook($hook, $parameters = [])
{
	return Hooks::instance()->hook($hook, $parameters);
}

/**
 * Includes files for hooks that only do that (i.e., integrate_pre_include)
 *
 * @param string $hook The name to include
 */
function call_integration_include_hook($hook)
{
	Hooks::instance()->include_hook($hook);
}

/**
 * Special hook call executed during obExit
 */
function call_integration_buffer()
{
	Hooks::instance()->buffer_hook();
}

/**
 * Add a function for integration hook.
 *
 * - Does nothing if the function is already added.
 *
 * @param string $hook The name of the hook to add
 * @param string $function The function associated with the hook
 * @param string $file The file that contains the function
 * @param bool $permanent = true if true, updates the value in settings table
 */
function add_integration_function($hook, $function, $file = '', $permanent = true)
{
	Hooks::instance()->add($hook, $function, $file, $permanent);
}

/**
 * Remove an integration hook function.
 *
 * What it does:
 *
 * - Removes the given function from the given hook.
 * - Does nothing if the function is not available.
 *
 * @param string $hook The name of the hook to remove
 * @param string $function The name of the function
 * @param string $file The file is located in
 */
function remove_integration_function($hook, $function, $file = '')
{
	Hooks::instance()->remove($hook, $function, $file);
}

/**
 * Decode numeric HTML entities to their UTF8 equivalent character.
 *
 * What it does:
 *
 * - Callback function for preg_replace_callback in subs-members
 * - Uses capture group 2 in the supplied array
 * - Does basic scan to ensure characters are inside a valid range
 *
 * @param array $matches matches from a preg_match_all
 *
 * @return string $string
 */
function replaceEntities__callback($matches)
{
	if (!isset($matches[2]))
	{
		return '';
	}

	$num = $matches[2][0] === 'x' ? hexdec(substr($matches[2], 1)) : (int) $matches[2];
	$num = $matches[2][0] === 'x' ? hexdec(substr(/** @scrutinizer ignore-type */ $matches[2], 1)) : (int) $matches[2];

	// remove left to right / right to left overrides
	if ($num === 0x202D || $num === 0x202E)
	{
		return '';
	}

	// Quote, Ampersand, Apostrophe, Less/Greater Than get HTML replaced
	if (in_array($num, [0x22, 0x26, 0x27, 0x3C, 0x3E]))
	{
		return '&#' . $num . ';';
	}

	// <0x20 are control characters, 0x20 is a space, > 0x10FFFF is past the end of the utf8 character set
	// 0xD800 >= $num <= 0xDFFF are surrogate markers (not valid for utf8 text)
	if ($num < 0x20 || $num > 0x10FFFF || ($num >= 0xD800 && $num <= 0xDFFF))
	{
		return '';
	}

	// <0x80 (or less than 128) are standard ascii characters a-z A-Z 0-9 and punctuation
	if ($num < 0x80)
	{
		return chr($num);
		return chr(/** @scrutinizer ignore-type */ $num);
	}

	// <0x800 (2048)
	if ($num < 0x800)
	{
		return chr(($num >> 6) + 192) . chr(($num & 63) + 128);
	}

	// < 0x10000 (65536)
	if ($num < 0x10000)
	{
		return chr(($num >> 12) + 224) . chr((($num >> 6) & 63) + 128) . chr(($num & 63) + 128);
	}

	// <= 0x10FFFF (1114111)
	return chr(($num >> 18) + 240) . chr((($num >> 12) & 63) + 128) . chr((($num >> 6) & 63) + 128) . chr(($num & 63) + 128);
}

/**
 * Converts HTML entities to utf8 equivalents
 *
 * What it does:
 *
 * - Callback function for preg_replace_callback
 * - Uses capture group 1 in the supplied array
 * - Does basic checks to keep characters inside a viewable range.
 *
 * @param array $matches array of matches as output from preg_match_all
 *
 * @return string $string
 */
function fixchar__callback($matches)
{
	if (!isset($matches[1]))
	{
		return '';
	}

	$num = $matches[1][0] === 'x' ? hexdec(substr($matches[1], 1)) : (int) $matches[1];
	$num = $matches[1][0] === 'x' ? hexdec(substr(/** @scrutinizer ignore-type */ $matches[1], 1)) : (int) $matches[1];

	// <0x20 are control characters, > 0x10FFFF is past the end of the utf8 character set
	// 0xD800 >= $num <= 0xDFFF are surrogate markers (not valid for utf8 text), 0x202D-E are left to right overrides
	if ($num < 0x20 || $num > 0x10FFFF || ($num >= 0xD800 && $num <= 0xDFFF) || $num === 0x202D || $num === 0x202E)
	{
		return '';
	}

	// <0x80 (or less than 128) are standard ascii characters a-z A-Z 0-9 and punctuation
	if ($num < 0x80)
	{
		return chr($num);
		return chr(/** @scrutinizer ignore-type */ $num);
	}

	// <0x800 (2048)
	if ($num < 0x800)
	{
		return chr(($num >> 6) + 192) . chr(($num & 63) + 128);
	}

	// < 0x10000 (65536)
	if ($num < 0x10000)
	{
		return chr(($num >> 12) + 224) . chr((($num >> 6) & 63) + 128) . chr(($num & 63) + 128);
	}

	// <= 0x10FFFF (1114111)
	return chr(($num >> 18) + 240) . chr((($num >> 12) & 63) + 128) . chr((($num >> 6) & 63) + 128) . chr(($num & 63) + 128);
}

/**
 * Strips out invalid HTML entities, replaces others with HTML style &#123; codes
 *
 * What it does:
 *
 * - Callback function used of preg_replace_callback in various $ent_checks,
 * - For example, strpos, strlen, substr, etc.
 *
 * @param array $matches array of matches for a preg_match_all
 *
 * @return string
 */
function entity_fix__callback($matches)
{
	if (!isset($matches[2]))
	{
		return '';
	}

	$num = $matches[2][0] === 'x' ? hexdec(substr($matches[2], 1)) : (int) $matches[2];
	$num = $matches[2][0] === 'x' ? hexdec(substr(/** @scrutinizer ignore-type */ $matches[2], 1)) : (int) $matches[2];

	// We don't allow control characters, characters out of range, byte markers, etc.
	if ($num < 0x20 || $num > 0x10FFFF || ($num >= 0xD800 && $num <= 0xDFFF) || $num === 0x202D || $num === 0x202E)
	{
		return '';
	}

	return '&#' . $num . ';';
}

/**
 * Retrieve additional search engines if there are any, as an array.
 *
 * @return array array of engines
 */
function prepareSearchEngines()
{
	global $modSettings;

	$engines = [];
	if (!empty($modSettings['additional_search_engines']))
	{
		$search_engines = Util::unserialize($modSettings['additional_search_engines']);
		foreach ($search_engines as $engine)
		{
			$engines[strtolower(preg_replace('~[^A-Za-z0-9 ]~', '', $engine['name']))] = $engine;
		}
	}

	return $engines;
}

/**
 * This function receives a request handle and attempts to retrieve the next result.
 *
 * What it does:
 *
 * - It is used by the controller callbacks from the template, such as
 * posts in topic display page, posts search results page, or personal messages.
 *
 * @param AbstractResult $messages_request holds a query result
 * @param bool $reset
 *
 * @return bool
 * @deprecate since 2.0
 */
function currentContext($messages_request, $reset = false)
{
	// Start from the beginning...
	if ($reset)
	{
		return $messages_request->data_seek(0);
	}

	// If the query has already returned false, get out of here
	if ($messages_request->hasResults())
	{
		return false;
	}

	// Attempt to get the next message.
	$message = $messages_request->fetch_assoc();
	if (!$message)
	{
		$messages_request->free_result();

		return false;
	}

	return $message;
}

/**
 * Helper function to insert an array in to an existing array
 *
 * What it does:
 *
 * - Intended for addon use to allow such things as
 * - Adding in a new menu item to an existing menu array
 *
 * @param array $input the array we will insert to
 * @param string $key the key in the array that we are looking to find for the insert action
 * @param array $insert the actual data to insert before or after the key
 * @param string $where adding before or after
 * @param bool $assoc if the array is an assoc array with named keys or a basic index array
 * @param bool $strict search for identical elements; this means it will also check the types of the needle.
 *
 * @return array
 */
function elk_array_insert($input, $key, $insert, $where = 'before', $assoc = true, $strict = false)
{
	$position = $assoc ? array_search($key, array_keys($input), $strict) : array_search($key, $input, $strict);

	// If the key is not found, just insert it at the end
	if ($position === false)

	{
		return array_merge($input, $insert);
	}

	if ($where === 'after')
	{
		$position++;
	}

	// Insert as first
	if (empty($position))
	{
		return array_merge($insert, $input);
	}

	return array_merge(array_slice($input, 0, $position), $insert, array_slice($input, $position));
	return array_merge(array_slice($input, 0, /** @scrutinizer ignore-type */ $position), $insert, array_slice($input, $position));
}

/**
 * Run a scheduled task now
 *
 * What it does:
 *
 * - From time to time it may be necessary to fire a scheduled task ASAP
 * - This function sets the scheduled task to be called before any other one
 *
 * @param string $task the name of a scheduled task
 */
function scheduleTaskImmediate($task)
{
	global $modSettings;

	if (!isset($modSettings['scheduleTaskImmediate']))
	{
		$scheduleTaskImmediate = [];
	}
	else
	{
		$scheduleTaskImmediate = Util::unserialize($modSettings['scheduleTaskImmediate']);
	}

	// If it has not been scheduled, they do so now
	if (!isset($scheduleTaskImmediate[$task]))
	{
		$scheduleTaskImmediate[$task] = 0;
		updateSettings(['scheduleTaskImmediate' => serialize($scheduleTaskImmediate)]);

		require_once(SUBSDIR . '/ScheduledTasks.subs.php');

		// Ensure the task is on
		toggleTaskStatusByName($task);

		// Before trying to run it **NOW** :P
		calculateNextTrigger($task, true);
	}
}

/**
 * For diligent people: remove scheduleTaskImmediate when done, otherwise
 * a maximum of 10 executions is allowed
 *
 * @param string $task the name of a scheduled task
 * @param bool $calculateNextTrigger if recalculate the next task to execute
 */
function removeScheduleTaskImmediate($task, $calculateNextTrigger = true)
{
	global $modSettings;

	// Not on then bail
	if (!isset($modSettings['scheduleTaskImmediate']))
	{
		return;
	}

	$scheduleTaskImmediate = Util::unserialize($modSettings['scheduleTaskImmediate']);

	// Clear / remove the task if it was set
	if (isset($scheduleTaskImmediate[$task]))
	{
		unset($scheduleTaskImmediate[$task]);
		updateSettings(['scheduleTaskImmediate' => serialize($scheduleTaskImmediate)]);

		// Recalculate the next task to execute
		if ($calculateNextTrigger)
		{
			require_once(SUBSDIR . '/ScheduledTasks.subs.php');
			calculateNextTrigger($task);
		}
	}
}

/**
 * Helper function to replace commonly used urls in text strings
 *
 * @event integrate_basic_url_replacement add additional placeholder replacements
 * @param string $string the string to inject URLs into
 *
 * @return string the input string with the place-holders replaced with
 *           the correct URLs
 */
function replaceBasicActionUrl($string)
{
	global $scripturl, $context, $boardurl;
	static $find_replace = null;

	if ($find_replace === null)
	{
		$find_replace = [
			'{forum_name}' => $context['forum_name'],
			'{forum_name_html_safe}' => $context['forum_name_html_safe'],
			'{forum_name_html_unsafe}' => un_htmlspecialchars($context['forum_name_html_safe']),
			'{script_url}' => $scripturl,
			'{board_url}' => $boardurl,
			'{login_url}' => getUrl('action', ['action' => 'login']),
			'{register_url}' => getUrl('action', ['action' => 'register']),
			'{activate_url}' => getUrl('action', ['action' => 'register', 'sa' => 'activate']),
			'{help_url}' => getUrl('action', ['action' => 'help']),
			'{admin_url}' => getUrl('admin', ['action' => 'admin']),
			'{moderate_url}' => getUrl('moderate', ['action' => 'moderate']),
			'{recent_url}' => getUrl('action', ['action' => 'recent']),
			'{search_url}' => getUrl('action', ['action' => 'search']),
			'{who_url}' => getUrl('action', ['action' => 'who']),
			'{credits_url}' => getUrl('action', ['action' => 'about', 'sa' => 'credits']),
			'{calendar_url}' => getUrl('action', ['action' => 'calendar']),
			'{memberlist_url}' => getUrl('action', ['action' => 'memberlist']),
			'{stats_url}' => getUrl('action', ['action' => 'stats']),
		];
		call_integration_hook('integrate_basic_url_replacement', [&$find_replace]);
	}

	return str_replace(array_keys($find_replace), array_values($find_replace), $string);
}

/**
 * This function creates a new GenericList from all the passed options.
 *
 * What it does:
 *
 * - Calls integration hook integrate_list_"unique_list_id" to allow easy modifying
 *
 * @event integrate_list_$listID called before every createlist to allow access to its listoptions
 * @param array $listOptions associative array of option => value
 */
function createList($listOptions)
{
	call_integration_hook('integrate_list_' . $listOptions['id'], [&$listOptions]);

	$list = new GenericList($listOptions);

	$list->buildList();
}

/**
 * This handy function retrieves a Request instance and passes it on.
 *
 * What it does:
 *
 * - To get hold of a Request, you can use this function or directly Request::instance().
 * - This is for convenience, it simply delegates to Request::instance().
 */
function request()
{
	return Request::instance();
}

/**
 * Meant to replace any usage of $db_last_error.
 *
 * What it does:
 *
 * - Reads the file db_last_error.txt, if a time() is present, returns it,
 * otherwise returns 0.
 */
function db_last_error()
{
	$time = trim(file_get_contents(BOARDDIR . '/db_last_error.txt'));

	if (preg_match('~^\d{10}$~', $time) === 1)
	{
		return $time;
	}

	return 0;
}

/**
 * This function has the only task to retrieve the correct prefix to be used
 * in responses.
 *
 * @return string - The prefix in the default language of the forum
 */
function response_prefix()
{
	global $language, $txt;
	static $response_prefix = null;

	$cache = Cache::instance();

	// Get a response prefix, but in the forum's default language.
	if ($response_prefix === null && (!$cache->getVar($response_prefix, 'response_prefix') || !$response_prefix))
	{
		if ($language === User::$info->language)

		{
			$response_prefix = $txt['response_prefix'];
		}
		else
		{
			$mtxt = [];
			$lang_loader = new Loader($language, $mtxt, database());
			$lang_loader->load('index');
			$response_prefix = $mtxt['response_prefix'];
		}

		$cache->put('response_prefix', $response_prefix, 600);
	}

	return $response_prefix;
}

/**
 * A very simple function to determine if an email address is "valid" for Elkarte.
 *
 * - A valid email for ElkArte is something that resembles an email (filter_var) and
 * is less than 255 characters (for database limits)
 *
 * @param string $value - The string to evaluate as valid email
 *
 * @return string|false - The email if valid, false if not a valid email
 */
function isValidEmail($value)
{
	$value = trim($value);
	if (!filter_var($value, FILTER_VALIDATE_EMAIL))
	{
		return false;
	}

	if (Util::strlen($value) >= 255)
	{
		return false;
	}

	return $value;
}

/**
 * Adds a protocol (http/s, ftp/mailto) to the beginning of a url if missing
 *
 * @param string $url - The url
 * @param string[] $protocols - A list of protocols to check, the first is
 *                 added if none is found (optional, default array('http://', 'https://'))
 *
 * @return string - The url with the protocol
 */
function addProtocol($url, $protocols = [])
{
	if (empty($protocols))
	{
		$pattern = '~^(http://|https://)~i';
		$protocols = ['http://'];
	}
	else
	{
		$pattern = '~^(' . implode('|', array_map(static fn($val) => preg_quote($val, '~'), $protocols)) . ')~i';
	}

	$found = false;
	$urlNew = preg_replace_callback($pattern, static function ($match) use (&$found) {
		$found = true;

		return strtolower($match[0]);
	}, $url);

	if ($found)
	{
		return $urlNew;
	}

	return $protocols[0] . $urlNew;
}

/**
 * Validate if a URL is allowed to be a "dofollow"
 *
 * @param string $checkUrl The URL to be checked
 * @return bool Returns true if the URL is allowed, false otherwise
 */
function validateURLAllowList($checkUrl)
{
	global $modSettings, $boardurl;
	static $allowList = null;

	if ($allowList === null)
	{
		$allowList = empty($modSettings['nofollow_allowlist']) ? [] : json_decode($modSettings['nofollow_allowlist']);

		// Always allow your own site
		$parse = parse_url($boardurl);
		$allowList[] = $parse['host'];

		$allowList = array_unique($allowList);
	}

	$parsed = parse_url($checkUrl);
	if (empty($parsed['host']))
	{
		return false;
	}

	foreach ($allowList as $validDomain)
	{
		if (str_ends_with($parsed['host'], $validDomain))
		{
			return true;
		}
	}

	return false;
}

/**
 * Removes all, or those over a limit, of nested quotes from a text string.
 *
 * @param string $text - The body we want to remove nested quotes from
 *
 * @return string - The same body, just without nested quotes
 */
function removeNestedQuotes($text)
{
	global $modSettings;

	if (!isset($modSettings['removeNestedQuotes']))
	{
		return $text;
	}

	// How many levels will we allow?
	$max_depth = (int) $modSettings['removeNestedQuotes'];

	// Remove quotes over our limit, then we need to find them all
	preg_match_all('~(\[/?quote(.*?)?])~i', $text, $matches, PREG_OFFSET_CAPTURE);
	$depth = 0;
	$remove = [];
	$start_pos = 0;

	// Mark ones that are in excess of the limit.  $match[0] will be the found tag
	// such as [quote=some author] or [/quote], $match[1] is the starting position of that tag.
	foreach ($matches[0] as $match)
	{
		// Closing quote
		if ($match[0][1] === '/')
		{
			--$depth;

			// To many, mark it for removal
			if ($depth === $max_depth)
			{
				// This quote position in the string, note [/quote] = 8
				$end_pos = $match[1] + 8;
				$length = $end_pos - $start_pos;
				$remove[] = [$start_pos, $length];
			}

			continue;
		}

		// Another quote level inward
		++$depth;
		if ($depth === $max_depth + 1)
		{
			$start_pos = $match[1];
		}
	}

	// Time to cull the herd
	foreach (array_reverse($remove) as [$start_pos, $length])
	{
		$text = substr_replace($text, '', $start_pos, $length);
	}

	return trim($text);
	return trim(/** @scrutinizer ignore-type */ $text);
}

/**
 * Change a \t to a span that will show a tab
 *
 * @param string $string
 *
 * @return string
 */
function tabToHtmlTab($string)
{
	return str_replace("\t", "<span class=\"tab\">\t</span>", $string);
}

/**
 * Remove <br />
 *
 * @param string $string
 *
 * @return string
 */
function removeBr($string)
{
	return str_replace('<br />', '', $string);
}

/**
 * Replace all vulgar words with respective proper words. (substring or whole words.)
 *
 * What it does:
 *  - It censors the passed string.
 *  - If the admin setting allow_no_censored is on, it does not censor unless force is also set.
 *  - If the admin setting allow_no_censored is off will censor words unless the user has set
 * it to not censor in their profile and force is off
 *  - It caches the list of censored words to reduce parsing.
 *  - Returns the censored text
 *
 * @param string $text
 * @param bool $force = false
 *
 * @return string
 */
function censor($text, $force = false)
{
	global $modSettings;
	static $censor = null;

	if ($censor === null)
	{
		$censor = new Censor(explode("\n", $modSettings['censor_vulgar']), explode("\n", $modSettings['censor_proper']), $modSettings);
	}

	return $censor->censor($text, $force);
}

/**
 * Helper function able to determine if the current member can see at least
 * one button of a button strip.
 *
 * @param array $button_strip
 *
 * @return bool
 */
function can_see_button_strip($button_strip)
{
	global $context;

	foreach ($button_strip as $value)
	{
		if (!isset($value['test']) || !empty($context[$value['test']]))
		{
			return true;
		}
	}

	return false;
}

/**
 * Get the current theme instance.
 *
 * @return Theme The current theme instance.
 */
function theme()
{
	return $GLOBALS['context']['theme_instance'];
}

/**
 * Set the JSON template for sending JSON response.
 *
 * This method prepares the template layers, loads the 'Json' template,
 * and sets the sub_template to 'send_json' in the global $context array.
 * The JSON data is initialized to null.
 *
 * @return void
 */
function setJsonTemplate()
{
	global $context;

	$template_layers = theme()->getLayers();
	$template_layers->removeAll();
	theme()->getTemplates()->load('Json');

	$context['sub_template'] = 'send_json';
	$context['json_data'] = null;
}

/**
 * Updates the PWA cache stale value to trigger a cache flush if needed.
 *
 * @param bool $refresh Determines whether to force a refresh of the PWA cache stale token.
 * @return void
 */
function setPWACacheStale($refresh = false)
{
	global $modSettings;

	// We need a PWA cache stale to keep things moving, changing this will trigger a PWA cache flush
	if (empty($modSettings['elk_pwa_cache_stale']) || $refresh)
	{
		$tokenizer = new TokenHash();
		$elk_pwa_cache_stale = $tokenizer->generate_hash(8);
		updateSettings(['elk_pwa_cache_stale' => $elk_pwa_cache_stale]);
	}
}

/**
 * Send a 1x1 GIF response and terminate the script execution
 *
 * @param bool $expired Flag to determine if header Expires should be sent
 *
 * @return never
 */
function dieGif($expired = false): never
{
	// The following is an attempt at stopping the behavior identified in #2391
	if (function_exists('fastcgi_finish_request'))
	{
		die();

	}

	$headers = Headers::instance();
	if ($expired)
	{
		$headers
			->header('Expires', 'Mon, 26 Jul 1997 05:00:00 GMT')
			->header('Last-Modified', gmdate('D, d M Y H:i:s') . ' GMT');
	}

	$headers->contentType('image/gif')->sendHeaders();
	die("\x47\x49\x46\x38\x39\x61\x01\x00\x01\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x21\xF9\x04\x01\x00\x00\x00\x00\x2C\x00\x00\x00\x00\x01\x00\x01\x00\x00\x02\x02\x44\x01\x00\x3B");

}

/**
 * Prepare ob_start with or without gzip compression
 *
 * @param bool $use_compression Starts compressed headers.
 */
function obStart($use_compression = false)
{
	// This is done to clear any output made before now.
	while (ob_get_level() > 0)
	{
		@ob_end_clean();
		/** @scrutinizer ignore-unhandled */ @ob_end_clean();
	}

	if ($use_compression)
	{
		ob_start('ob_gzhandler');
	}
	else
	{
		ob_start();
		Headers::instance()->header('Content-Encoding', 'none');
	}
}

/**
 * Returns a URL based on the parameters passed and the selected generator
 *
 * @param string $type The type of the URL (depending on the type, the
 *                     generator can act differently
 * @param array $params All the parameters of the URL
 *
 * @return string An URL
 */
function getUrl($type, $params)
{
	static $generator = null;

	if ($generator === null)
	{
		$generator = initUrlGenerator();
	}

	return $generator->get($type, $params);
}

/**
 * Returns the query part of a URL based on the parameters passed and the selected generator
 *
 * @param string $type The type of the URL (depending on the type, the
 *                     generator can act differently
 * @param array $params All the parameters of the URL
 *
 * @return string The query part of a URL
 */
function getUrlQuery($type, $params)
{
	static $generator = null;

	if ($generator === null)
	{
		$generator = initUrlGenerator();
	}

	return $generator->getQuery($type, $params);
}

/**
 * Initialize the URL generator
 *
 * @return object The URL generator object
 */
function initUrlGenerator()
{
	global $scripturl, $context, $url_format;

	$generator = new UrlGenerator([
		'generator' => ucfirst($url_format ?? 'standard'),
		'scripturl' => $scripturl,
		'replacements' => [
			'{session_data}' => isset($context['session_var']) ? $context['session_var'] . '=' . $context['session_id'] : ''
		]
	]);

	$generator->register('Topic');
	$generator->register('Board');
	$generator->register('Profile');

	return $generator;
}

/**
 * This function only checks if a certain feature (in core features)
 * is enabled or not.
 *
 * @param string $feature The abbreviated code of a core feature
 * @return bool true/false for enabled/disabled
 */
function featureEnabled($feature)
{
	global $modSettings, $context;
	static $features = null;

	if ($features === null)
	{
		// This allows us to change the way things look for the admin.
		$features = explode(',', $modSettings['admin_features'] ?? 'cd,cp,k,w,rg,ml,pm');

		// @deprecated since 2.0 - Next line is just for backward compatibility to remove before release
		$context['admin_features'] = $features;
	}

	return in_array($feature, $features, true);
}

/**
 * Clean up the XML to make sure it doesn't contain invalid characters.
 *
 * What it does:
 *
 * - Removes invalid XML characters to ensure the input string being parsed properly.
 *
 * @param string $string The string to clean
 *
 * @return string The clean string
 */
function cleanXml($string)
{
	// https://www.w3.org/TR/2008/REC-xml-20081126/#NT-Char
	$string = preg_replace('~[\x00-\x08\x0B\x0C\x0E-\x1F\x{FFFE}\x{FFFF}]~u', '', $string);

	// Discouraged
	return preg_replace('~[\x7F-\x84\x86-\x9F\x{FDD0}-\x{FDEF}\x{1FFFE}-\x{1FFFF}\x{2FFFE}-\x{2FFFF}\x{3FFFE}-\x{3FFFF}\x{4FFFE}-\x{4FFFF}\x{5FFFE}-\x{5FFFF}\x{6FFFE}-\x{6FFFF}\x{7FFFE}-\x{7FFFF}\x{8FFFE}-\x{8FFFF}\x{9FFFE}-\x{9FFFF}\x{AFFFE}-\x{AFFFF}\x{BFFFE}-\x{BFFFF}\x{CFFFE}-\x{CFFFF}\x{DFFFE}-\x{DFFFF}\x{EFFFE}-\x{EFFFF}\x{FFFFE}-\x{FFFFF}\x{10FFFE}-\x{10FFFF}]~u', '', $string);
}

/**
 * Validates an IPv6 address. Returns true if it is ipv6.
 *
 * @param string $ip ip address to be validated
 *
 * @return bool true|false
 */
function isValidIPv6($ip)
{
	return filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6) !== false;
}

/**
 * Converts IPv6s to numbers.  These make ban checks much easier.
 *
 * @param string $ip ip address to be converted
 *
 * @return int[] array
 */
function convertIPv6toInts($ip)
{
	static $expanded = [];

	// Check if we have done this already.
	if (isset($expanded[$ip]))
	{
		return $expanded[$ip];
	}

	// Expand the IP out.
	$expanded_ip = explode(':', expandIPv6($ip));
	$expanded_ip = explode(':', /** @scrutinizer ignore-type */ expandIPv6($ip));

	$new_ip = [];
	foreach ($expanded_ip as $int)
	{
		$new_ip[] = hexdec($int);
	}

	// Save this in case of repeated use.
	$expanded[$ip] = $new_ip;

	return $expanded[$ip];
}

/**
 * Expands an IPv6 address to its full form.
 *
 * @param string $addr ipv6 address string
 * @param bool $strict_check checks length to expanded address for compliance
 *
 * @return bool|string expanded ipv6 address.
 */
function expandIPv6($addr, $strict_check = true)
{
	static $converted = [];

	// Check if we have done this already.
	if (isset($converted[$addr]))
	{
		return $converted[$addr];
	}

	// Check if there are segments missing, insert if necessary.
	if (str_contains($addr, '::'))
	{
		$part = explode('::', $addr);
		$part[0] = explode(':', $part[0]);
		$part[1] = explode(':', $part[1]);
		$missing = [];

		// Looks like this is an IPv4 address
		if (isset($part[1][1]) && str_contains($part[1][1], '.'))
		{
			$ipoct = explode('.', $part[1][1]);
			$p1 = dechex($ipoct[0]) . dechex($ipoct[1]);
			$p1 = dechex(/** @scrutinizer ignore-type */ $ipoct[0]) . dechex($ipoct[1]);
			$p2 = dechex($ipoct[2]) . dechex($ipoct[3]);

			$part[1] = [
				$part[1][0],
				$p1,
				$p2
			];
		}

		$limit = count($part[0]) + count($part[1]);
		for ($i = 0; $i < (8 - $limit); $i++)
		{
			$missing[] = '0000';
		}

		$part = array_merge($part[0], $missing, $part[1]);
	}
	else
	{
		$part = explode(':', $addr);
	}

	// Pad each segment until it has 4 digits.
	foreach ($part as &$p)
	{
		while (strlen($p) < 4)
		{
			$p = '0' . $p;
		}
	}

	unset($p);

	// Join segments.
	$result = implode(':', $part);

	// Save this in case of repeated use.
	$converted[$addr] = $result;

	// Quick check to make sure the length is as expected.
	if (!$strict_check || strlen($result) === 39)
	{
		return $result;
	}

	return false;
}

/**
 * Extracts and normalizes the host of a URL to ASCII (Punycode) for reliable comparisons.
 * Returns "" if a host can’t be determined.
 */
function iri_host_ascii($url)
{
	if ($url === '')
	{
		return '';
	}

	// First attempt: normal parse
	$host = parse_url($url, PHP_URL_HOST);

	// If parse_url failed and the URL contains Unicode, try to salvage the authority
	if ($host === null || $host === false || $host === '')
	{
		if (preg_match('~^[a-z][a-z0-9+.-]*://([^/?#]+)~iu', $url, $m))
		{
			$host = $m[1];
		}
	}

	// Fallback for plain hostnames or IPs without http[s]:// scheme
	if ($host === null || $host === false || $host === '')
	{
		$parsed = parse_url('scheme://' . $url);
		if (isset($parsed['host']))
		{
			$host = $parsed['host'];
		}
	}

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

	// Strip userinfo and port if present before IDNA
	// e.g., user:pass@exämple.com:8080 -> exämple.com
	if (str_contains($host, '@'))
	{
		$host = substr($host, strrpos($host, '@') + 1);
	}

	if (str_contains($host, ':'))
	{
		$host = substr($host, 0, strpos($host, ':'));
	}

	// Convert Unicode hostname to ASCII using UTS#46 (browser-compatible)
	if (function_exists('idn_to_ascii'))
	{
		$ascii = idn_to_ascii($host, IDNA_DEFAULT, defined('INTL_IDNA_VARIANT_UTS46') ? INTL_IDNA_VARIANT_UTS46 : 0);
		if ($ascii !== false)
		{
			$host = $ascii;
		}
	}

	return strtolower($host);
}

/**
 * Removed in 2.0, always returns false.
 *
 * Logs the depreciation notice, returns false, sets context value such that
 * old themes don't go sour ;)
 *
 * @param string $browser the browser we are checking for.
 */
function isBrowser($browser)
function isBrowser(/** @scrutinizer ignore-unused */ $browser)
{
	global $context;

	\ElkArte\Errors::instance()->log_deprecated('isBrowser()', 'Nothing');

	$context['browser_body_id'] = 'elkarte';

	return false;
}

elkarte / Elkarte

ip2range() C last analyzed 2026-01-24 21:07 UTC

Complexity

Size

Duplication

Code Coverage

Importance

How to fix Long Method Complexity

Long Method

Duplication Side-by-Side

Filter issues like

ip2range() C
last analyzed 2026-01-24 21:07 UTC
