Global.cfc

component output="false" {

	public any function $doubleCheckedLock(
		required string name,
		required string condition,
		required string execute,
		struct conditionArgs = "#StructNew()#",
		struct executeArgs = "#StructNew()#",
		numeric timeout = 30
	) {
		local.rv = $invoke(method = arguments.condition, invokeArgs = arguments.conditionArgs);
		if (IsBoolean(local.rv) AND NOT local.rv) {
			lock timeout="#arguments.timeout#" name="#arguments.name#" {
				local.rv = $invoke(method = arguments.condition, invokeArgs = arguments.conditionArgs);
				if (IsBoolean(local.rv) AND NOT local.rv) {
					local.rv = $invoke(method = arguments.execute, invokeArgs = arguments.executeArgs)
				}
			}
		}
		return local.rv;
	}

	public any function $simpleLock(
		required string name,
		required string type,
		required string execute,
		struct executeArgs = "#StructNew()#",
		numeric timeout = 30
	) {
		if (StructKeyExists(arguments, "object")) {
			lock name="#arguments.name#" type="#arguments.type#" timeout="#arguments.timeout#" {
				local.rv = $invoke(
					component = "#arguments.object#",
					method = "#arguments.execute#",
					argumentCollection = "#arguments.executeArgs#"
				);
			}
		} else {
			arguments.executeArgs.$locked = true;
			lock name="#arguments.name#" type="#arguments.type#" timeout="#arguments.timeout#" {
				local.rv = $invoke(method = "#arguments.execute#", argumentCollection = "#arguments.executeArgs#");
			}
		}
		if (StructKeyExists(local, "rv")) {
			return local.rv;
		}
	}

	public struct function $image() {
		local.rv = {};
		if (arguments.action == "info") {
			local.rv = $engineAdapter().imageInfo(arguments.source);
		} else if ($engineAdapter().isBoxLang()) {
			Throw(
				type = "Wheels.Image.UnsupportedAction",
				message = "The `$image()` function in BoxLang currently supports only the 'info' action."
			);
		} else {
			// Adobe or Lucee: use cfimage
			arguments.structName = "rv";
			local.args = {};
			for (local.key in arguments) {
				local.args[local.key] = arguments[local.key];
			}
			cfimage(attributeCollection = local.args);
			local.rv = local.rv;
		}
		return local.rv;
	}

	public void function $mail() {
		if (StructKeyExists(arguments, "mailparts")) {
			local.mailparts = arguments.mailparts;
			StructDelete(arguments, "mailparts");
		}
		if (StructKeyExists(arguments, "mailparams")) {
			local.mailparams = arguments.mailparams;
			StructDelete(arguments, "mailparams");
		}
		if (StructKeyExists(arguments, "tagContent")) {
			local.tagContent = arguments.tagContent;
			StructDelete(arguments, "tagContent");
		}
		local.args = {};
		for (local.key in arguments) {
			local.args[local.key] = arguments[local.key];
		}
		cfmail(attributeCollection = "#local.args#") {
			if (StructKeyExists(local, "mailparams")) {
				for (local.i in local.mailparams) {
					cfmailparam(attributeCollection = "#local.i#");
				}
			}
			if (StructKeyExists(local, "mailparts")) {
				for (local.i in local.mailparts) {
					local.innerTagContent = local.i.tagContent;
					StructDelete(local.i, "tagContent");
					cfmailpart(attributeCollection = "#local.i#") {
						WriteOutput(local.innerTagContent)
					}
				}
			}
			if (StructKeyExists(local, "tagContent")) {
				WriteOutput(local.tagContent)
			}
		}
	}

	public any function $cache() {
		// If cache is found only the function is aborted, not page. --->
		variables.$instance.reCache = false;
		// Engines without the `cfcache` built-in (e.g. RustCFML) can't back
		// the template/static cache. Degrade to a no-op: leaving reCache=true
		// means the request still renders normally, just without this layer.
		if ($hasEngineAdapter() && !$engineAdapter().supportsCfcache()) {
			variables.$instance.reCache = true;
			return;
		}
		local.args = {};
		for (local.key in arguments) {
			local.args[local.key] = arguments[local.key];
		}
		cfcache(attributeCollection = "#local.args#");
		variables.$instance.reCache = true;
	}

	public void function $content() {
		local.args = {};
		for (local.key in arguments) {
			local.args[local.key] = arguments[local.key];
		}
		// Best-effort: cfcontent throws on a committed response (Adobe CF).
		if ($responseCommitted()) {
			return;
		}
		try {
			cfcontent(attributeCollection = "#local.args#");
		} catch (any e) {
			// Re-probe to handle the isCommitted/throw race; rethrow only when
			// the response is still uncommitted (a genuine caller error).
			if (!$responseCommitted()) {
				rethrow;
			}
		}
	}

	public void function $header() {
		// Plain-struct copy: Adobe CF 2023+ rejects `arguments` as
		// attributeCollection (#10 cross-engine invariant). `statusText` is
		// stripped because Adobe CF 2025 removed it.
		local.args = {};
		for (local.key in arguments) {
			if (local.key != "statusText") {
				local.args[local.key] = arguments[local.key];
			}
		}
		// Best-effort: cfheader throws on a committed response (Adobe CF). The
		// short-circuit is critical inside onError, where letting the exception
		// escape would replace the original error with the cfheader-failure stack.
		if ($responseCommitted()) {
			return;
		}
		try {
			cfheader(attributeCollection = "#local.args#");
		} catch (any e) {
			// Re-probe to handle the isCommitted/throw race; rethrow only when
			// the response is still uncommitted (a genuine caller error).
			if (!$responseCommitted()) {
				rethrow;
			}
		}
	}

	/**
	 * Returns true when the servlet response has been committed and headers
	 * can no longer be modified. Returns false on engines or contexts where
	 * the underlying servlet probe is unavailable.
	 */
	public boolean function $responseCommitted() {
		try {
			return GetPageContext().getResponse().isCommitted();
		} catch (any e) {
			return false;
		}
	}

	public void function $include(required string template) {
		include "#LCase(arguments.template)#";
	}

	public void function $includeAndOutput(required string template) {
		include "#LCase(arguments.template)#";
	}

	public string function $includeAndReturnOutput(required string $template) {
		// Make it so the developer can reference passed in arguments in the loc scope if they prefer.
		if (StructKeyExists(arguments, "$type") AND arguments.$type IS "partial") {
			local = arguments;
		}
		// Include the template and return the result.
		// Variable is set to $wheels to limit chances of it being overwritten in the included template.
		// cfformat-ignore-start
  	savecontent variable="local.$wheels" {
  	  include "#LCase(arguments.$template)#"
  	};
		// cfformat-ignore-end
return local.$wheels;
	}

	/**
	 * Includes a config file like /config/settings.cfm or /config/services.cfm
	 * during application start, capturing any output it produces.
	 *
	 * If the file fails to compile or run, the failure is logged and rethrown
	 * as a named `Wheels.ConfigIncludeFailed` error that carries the failing
	 * template path and the original engine message (original type/detail are
	 * preserved in `detail`). This is deliberate fail-closed behavior in EVERY
	 * environment: an app whose config did not load must not boot on framework
	 * defaults and serve traffic. The named error propagates out of
	 * onApplicationStart by design, and renders on the development error page
	 * now that onError no longer masks application-start errors.
	 *
	 * If the include succeeds but the captured output is non-empty — almost
	 * always a sign that the file is missing a cfscript wrapper, so Lucee/Adobe
	 * parse the body as markup and any cfscript-style code becomes literal
	 * output text that never executes — log a clear warning pointing the
	 * developer at the most likely cause, and discard the output so it doesn't
	 * leak into the response of whichever request happened to trigger
	 * onApplicationStart.
	 *
	 * Note for maintainers: deliberately avoids putting any literal cf-tags
	 * in this docblock — Lucee 7's tag scanner reads CFC comments before
	 * compilation and treats unclosed tags as an error.
	 *
	 * @template Mapping-relative path like "/config/services.cfm".
	 */
	public void function $includeConfig(required string template) {
		try {
			// cfformat-ignore-start
  		savecontent variable="local.$wheelsConfigOutput" {
  		  include "#LCase(arguments.template)#"
  		};
			// cfformat-ignore-end
		} catch (any e) {
			// Fail closed: a compile-time or runtime failure in a config template is a
			// boot-blocking configuration error in EVERY environment. Booting anyway
			// would silently run the app on framework defaults (no DI registrations,
			// default settings, …) and serve traffic fail-open — strictly worse than
			// a hard stop. Log the offending template, then rethrow a NAMED, located
			// error that says what broke, where, and why — instead of the old masked,
			// app-wide HTTP 500 whose secondary onError failure hid the real cause
			// (the canonical trigger is Adobe CF rejecting a top-level
			// `var di = injector();` in config/services.cfm — a compile error on
			// Adobe, accepted on Lucee — issue #3063). The throw is unconditional:
			// no environment branching, no swallowed path.
			try {
				writeLog(
					file = "wheels",
					type = "error",
					text = "Wheels: " & arguments.template & " failed to compile or run during"
						& " onApplicationStart — application start was aborted (fail-closed)."
						& " Error: " & e.message
				);
			} catch (any logErr) {
				// Logging is best-effort during application start.
			}
			Throw(
				type = "Wheels.ConfigIncludeFailed",
				message = "Failed to include config template '" & arguments.template & "': " & e.message,
				detail = "Original exception type: " & e.type & "."
					& (StructKeyExists(e, "detail") && Len(e.detail) ? " " & e.detail : "")
					& " Application start was aborted because this config file could not be"
					& " loaded — fix the file and restart (booting without it would run the"
					& " application on framework defaults)."
			);
		}
		if (Len(Trim(local.$wheelsConfigOutput))) {
			local.preview = Left(Trim(local.$wheelsConfigOutput), 200);
			local.scriptOpen = Chr(60) & "cfscript" & Chr(62);
			local.scriptClose = Chr(60) & "/cfscript" & Chr(62);
			try {
				writeLog(
					file = "wheels",
					type = "warning",
					text = "Wheels: " & arguments.template & " produced output during onApplicationStart"
						& " — this almost always means the file body is missing a "
						& local.scriptOpen & "..." & local.scriptClose & " wrapper, so the engine is"
						& " parsing CFScript-style code as literal markup (registrations like"
						& " var di = injector(); never execute, and the bare lines would leak onto"
						& " every response if not captured here)."
						& " First 200 chars of captured output: " & local.preview
				);
			} catch (any e) {
				// Logging is best-effort during application start.
			}
		}
	}

	public any function $directory() {
		local.rv = "";
		arguments.name = "rv";
		local.args = {};
		for (local.key in arguments) {
			local.args[local.key] = arguments[local.key];
		}
		cfdirectory(attributeCollection = "#local.args#");
		return local.rv;
	}

	public any function $file() {
		local.args = {};
		for (local.key in arguments) {
			local.args[local.key] = arguments[local.key];
		}
		cffile(attributeCollection = "#local.args#");
	}

	public any function $cfinvoke(required string component, required string method, struct invokeArguments) {
		cfinvoke
		component = "#arguments.component#"
		method = "#arguments.method#"
		returnVariable = "#arguments.returnVariable#"
		argumentCollection = "#arguments.invokeArguments#";
		return local.rv;
	}

	public any function $invoke() {
		arguments.returnVariable = "local.rv";
		if (StructKeyExists(arguments, "componentReference")) {
			arguments.component = arguments.componentReference;
			StructDelete(arguments, "componentReference");
		} else if (NOT StructKeyExists(variables, arguments.method)) {
			// this is done so that we can call dynamic methods via "onMissingMethod" on the object (we need to pass in the object for this so it can call methods on the "this" scope instead)
			arguments.component = this;
		}
		if (StructKeyExists(arguments, "invokeArgs")) {
			arguments.argumentCollection = arguments.invokeArgs;
			if (StructCount(arguments.argumentCollection) IS NOT ListLen(StructKeyList(arguments.argumentCollection))) {
				// work-around for fasthashremoved cf8 bug
				arguments.argumentCollection = StructNew();
				for (local.i in StructKeyList(arguments.invokeArgs)) {
					arguments.argumentCollection[local.i] = arguments.invokeArgs[local.i];
				}
			}


			if (StructKeyExists(arguments.invokeArgs, "componentReference")) {
				arguments.component = arguments.invokeArgs.componentReference;
			}


			StructDelete(arguments, "invokeArgs");
		}
		local.args = {};
		for (local.key in arguments) {
			local.args[local.key] = arguments[local.key];
		}
		cfinvoke(attributeCollection = "#local.args#");
		if (StructKeyExists(local, "rv")) {
			return local.rv;
		}
	}

	public void function $location(boolean delay = false) {
		StructDelete(arguments, "$args", false);
		if (NOT arguments.delay) {
			StructDelete(arguments, "delay", false);
			local.args = {};
			for (local.key in arguments) {
				local.args[local.key] = arguments[local.key];
			}
			cflocation(attributeCollection = "#local.args#");
		}
	}

	public void function $htmlhead() {
		local.args = {};
		for (local.key in arguments) {
			local.args[local.key] = arguments[local.key];
		}
		// Best-effort: cfhtmlhead throws "Unable to add text to HTML HEAD tag"
		// on a committed response (Adobe CF). Same defensive shape as $header().
		if ($responseCommitted()) {
			return;
		}
		try {
			cfhtmlhead(attributeCollection = "#local.args#");
		} catch (any e) {
			// Re-probe to handle the isCommitted/throw race; rethrow only when
			// the response is still uncommitted (a genuine caller error).
			if (!$responseCommitted()) {
				rethrow;
			}
		}
	}

	public any function $dbinfo() {
		arguments.name = "local.rv";
		if (StructKeyExists(arguments, "username") && !Len(arguments.username)) {
			StructDelete(arguments, "username");
		}
		if (StructKeyExists(arguments, "password") && !Len(arguments.password)) {
			StructDelete(arguments, "password");
		}

		// BoxLang specific fix for index queries (MSSQL/Oracle)
		if (
			$engineAdapter().isBoxLang() &&
			StructKeyExists(arguments, "type") && arguments.type == "index" &&
			StructKeyExists(arguments, "table")
		) {
			local.adapter = $get("adapterName");

			if (local.adapter == "MicrosoftSQLServerModel") {
				local.sql = "
					SELECT
						DB_NAME() AS TABLE_CAT,
						SCHEMA_NAME(t.schema_id) AS TABLE_SCHEM,
						t.name AS TABLE_NAME,
						CAST(CASE WHEN i.is_unique = 0 THEN 1 ELSE 0 END AS INT) AS NON_UNIQUE,
						t.name AS INDEX_QUALIFIER,
						i.name AS INDEX_NAME,
						CASE
							WHEN i.type = 1 THEN 'Clustered Index'
							WHEN i.type = 2 THEN 'Other Index'
							ELSE 'Other Index'
						END AS TYPE,
						CAST(ic.key_ordinal AS INT) AS ORDINAL_POSITION,
						c.name AS COLUMN_NAME,
						CASE WHEN ic.is_descending_key = 0 THEN 'A' ELSE 'D' END AS ASC_OR_DESC,
						CAST(0 AS INT) AS CARDINALITY,
						CAST(0 AS INT) AS PAGES,
						'' AS FILTER_CONDITION
					FROM sys.indexes i
					INNER JOIN sys.objects t ON i.object_id = t.object_id
					INNER JOIN sys.index_columns ic ON i.object_id = ic.object_id AND i.index_id = ic.index_id
					INNER JOIN sys.columns c ON ic.object_id = c.object_id AND ic.column_id = c.column_id
					WHERE t.name = '#arguments.table#'
						AND t.type = 'U'
						AND i.type_desc IN ('CLUSTERED', 'NONCLUSTERED')
					ORDER BY i.name, ic.key_ordinal
				";
				local.rv = $query(sql = local.sql, datasource = arguments.datasource);
				return local.rv;
			}

			if (local.adapter == "OracleModel") {
				local.sql = "
					SELECT
						NULL AS TABLE_CAT,
						ai.OWNER AS TABLE_SCHEM,
						ai.TABLE_NAME,
						CASE WHEN ai.UNIQUENESS = 'NONUNIQUE' THEN 1 ELSE 0 END AS NON_UNIQUE,
						ai.OWNER AS INDEX_QUALIFIER,
						ai.INDEX_NAME,
						'Other Index' AS TYPE,
						ac.COLUMN_POSITION AS ORDINAL_POSITION,
						ac.COLUMN_NAME,
						CASE WHEN ac.DESCEND = 'DESC' THEN 'D' ELSE 'A' END AS ASC_OR_DESC,
						0 AS CARDINALITY,
						0 AS PAGES,
						'' AS FILTER_CONDITION
					FROM ALL_INDEXES ai
					JOIN ALL_IND_COLUMNS ac ON ai.INDEX_NAME = ac.INDEX_NAME AND ai.OWNER = ac.INDEX_OWNER
					WHERE ai.TABLE_NAME = UPPER('#arguments.table#')
						AND ai.INDEX_TYPE != 'LOB'
					ORDER BY ai.INDEX_NAME, ac.COLUMN_POSITION
				";
				local.rv = $query(sql = local.sql, datasource = arguments.datasource);
				return local.rv;
			}
		}

		if (
			StructKeyExists(arguments, "type") &&
			arguments.type eq "index" &&
			$get("adapterName") eq "SQLiteModel"
		) {
			local.sql = "
				SELECT
					NULL AS TABLE_CAT,
					NULL AS TABLE_SCHEM,
					'#arguments.table#' AS TABLE_NAME,
					CASE WHEN il.""unique"" = 0 THEN 1 ELSE 0 END AS NON_UNIQUE,
					NULL AS INDEX_QUALIFIER,
					il.name AS INDEX_NAME,
					'Other Index' AS TYPE,
					ii.seqno + 1 AS ORDINAL_POSITION,
					ii.name AS COLUMN_NAME,
					'A' AS ASC_OR_DESC,
					0 AS CARDINALITY,
					0 AS PAGES,
					'' AS FILTER_CONDITION
				FROM pragma_index_list('#arguments.table#') il
				JOIN pragma_index_info(il.name) ii

				UNION ALL

				SELECT
					NULL AS TABLE_CAT,
					NULL AS TABLE_SCHEM,
					'#arguments.table#' AS TABLE_NAME,
					0 AS NON_UNIQUE,
					NULL AS INDEX_QUALIFIER,
					'PRIMARY' AS INDEX_NAME,
					'Primary Key' AS TYPE,
					pk AS ORDINAL_POSITION,
					name AS COLUMN_NAME,
					'A' AS ASC_OR_DESC,
					0 AS CARDINALITY,
					0 AS PAGES,
					'' AS FILTER_CONDITION
				FROM pragma_table_info('#arguments.table#')
				WHERE pk > 0

				ORDER BY INDEX_NAME, ORDINAL_POSITION;
			";
			local.rv = $query(sql = local.sql, datasource = arguments.datasource);
			return local.rv;
		}

		// If the cfdbinfo call fails we try it again, this time setting "dbname" explicitly.
		// Sometimes the call fails when using a custom database connection string.
		// In that case the database name is not known by the CF server and it will just use any of the databases that the data source has access to.
		// That can incorrectly be "information_schema" for example.
		try {
			local.args = {};
			for (local.key in arguments) {
				local.args[local.key] = arguments[local.key];
			}
			cfdbinfo(attributeCollection = local.args);
		} catch (any e) {
			local.args = {};
			for (local.key in arguments) {
				local.args[local.key] = arguments[local.key];
			}
			cfdbinfo(attributeCollection = local.args);
			local.type = arguments.type;
			arguments.type = "dbnames";
			local.args = {};
			for (local.key in arguments) {
				local.args[local.key] = arguments[local.key];
			}
			cfdbinfo(attributeCollection = local.args);
			if (local.rv.recordCount GT 1) {
				for (local.i in local.rv) {
					if (local.i.database_name IS NOT "information_schema") {
						arguments.dbname = local.i.database_name;
					}
				}
			}
			arguments.type = local.type;
			local.args = {};
			for (local.key in arguments) {
				local.args[local.key] = arguments[local.key];
			}
			cfdbinfo(attributeCollection = local.args);
		}

		// Override name for test mode
		if (
			arguments.type IS "version" AND
			StructKeyExists(url, "controller") AND
			StructKeyExists(url, "action") AND
			StructKeyExists(url, "view") AND
			StructKeyExists(url, "type") AND
			StructKeyExists(url, "adapter")
		) {
			if (url.controller IS "wheels" AND url.action IS "wheels" AND url.view IS "tests" AND url.type IS "core") {
				QuerySetCell(local.rv, "driver_name", url.adapter);
			}
		}

		return local.rv;
	}

	public any function $wddx(required any input, string action = "cfml2wddx", boolean useTimeZoneInfo = true) {
		arguments.output = "local.output";
		local.args = {};
		for (local.key in arguments) {
			local.args[local.key] = arguments[local.key];
		}
		cfwddx(attributeCollection = "#local.args#");
		if (StructKeyExists(local, "output")) {
			return local.output;
		}
	}

	public any function $zip() {
		$engineAdapter().prepareZipArgs(arguments);
		local.args = {};
		for (local.key in arguments) {
			local.args[local.key] = arguments[local.key];
		}
		cfzip(attributeCollection = "#local.args#");
	}

	public any function $query(required string sql) {
		StructDelete(arguments, "name");
		// allow the use of query of queries, caveat: Query must be called query. Eg: SELECT * from query
		if (StructKeyExists(arguments, "query") && IsQuery(arguments.query)) {
			var query = Duplicate(arguments.query);
		}
		local.rv = QueryExecute(PreserveSingleQuotes(arguments.sql), [], arguments);
		// some sql statements may not return a value
		if (StructKeyExists(local, "rv")) {
			return local.rv;
		}
	}

	/**
	 * Returns the current setting for the supplied Wheels setting or the current default for the supplied Wheels function argument.
	 *
	 * [section: Configuration]
	 * [category: Miscellaneous Functions]
	 *
	 * @name Variable name to get setting for.
	 * @functionName Function name to get setting for.
	 */
	public any function get(required string name, string functionName = "") {
		return $get(argumentCollection = arguments);
	}

	/**
	 * Returns the value of an environment variable. Checks application.env (loaded from .env files) first, then falls back to system environment variables (server.system.environment). Returns the default if the variable is not found in either location.
	 *
	 * [section: Configuration]
	 * [category: Miscellaneous Functions]
	 *
	 * @name The environment variable name to look up.
	 * @defaultValue Value to return if the variable is not found. The legacy
	 *   named argument `default` is also accepted for backwards compatibility
	 *   with pre-rename callers.
	 */
	public any function env(required string name, any defaultValue = "") {
		if (StructKeyExists(application, "env") && StructKeyExists(application.env, arguments.name)) {
			return application.env[arguments.name];
		}
		if (
			StructKeyExists(server, "system")
			&& StructKeyExists(server.system, "environment")
			&& StructKeyExists(server.system.environment, arguments.name)
		) {
			return server.system.environment[arguments.name];
		}
		// Back-compat for the legacy `default = "Y"` named-arg form. The
		// parameter was renamed from `default` (a CFML reserved word Adobe CF
		// refuses to bind) to `defaultValue`; named arguments still land in
		// `arguments` under their literal key on every engine.
		if (StructKeyExists(arguments, "default")) {
			return arguments.default;
		}
		return arguments.defaultValue;
	}

	/**
	 * Use to configure a global setting or set a default for a function.
	 *
	 * [section: Configuration]
	 * [category: Miscellaneous Functions]
	 */
	public void function set() {
		$set(argumentCollection = arguments);
	}

	/**
	 * Internal function.
	 * Called from get().
	 */
	public any function $get(required string name, string functionName = "") {
		// Multi-tenant config override: per-tenant settings take precedence
		// over application-level settings (non-function settings only).
		// Security-sensitive settings cannot be overridden per-tenant.
		// Use a StructKeyExists chain for safe nested scope traversal during app
		// startup (IsDefined string-parses its dotted-path argument on every call
		// and $get runs on every settings read so it's too expensive here).
		if (
			!Len(arguments.functionName)
			&& StructKeyExists(request, "wheels")
			&& StructKeyExists(request.wheels, "tenant")
			&& StructKeyExists(request.wheels.tenant, "config")
			&& StructKeyExists(request.wheels.tenant.config, arguments.name)
			&& !ListFindNoCase(
				"encryptionAlgorithm,encryptionSecretKey,encryptionEncoding,CSRFProtection,csrfStore,reloadPassword,obfuscateUrls",
				arguments.name
			)
		) {
			return request.wheels.tenant.config[arguments.name];
		}
		local.appKey = $appKey();
		if (Len(arguments.functionName)) {
			local.rv = application[local.appKey].functions[arguments.functionName][arguments.name];
		} else {
			local.rv = application[local.appKey][arguments.name];
		}
		return local.rv;
	}

	/**
	 * Internal function.
	 * Called from set().
	 */
	public void function $set() {
		local.appKey = $appKey();
		if (ArrayLen(arguments) > 1) {
			for (local.key in arguments) {
				if (local.key != "functionName") {
					local.functionNameArray = ListToArray(arguments.functionName);
					local.iEnd = ArrayLen(local.functionNameArray);
					for (local.i = 1; local.i <= local.iEnd; local.i++) {
						local.functionName = Trim(local.functionNameArray[local.i]);
						application[local.appKey].functions[local.functionName][local.key] = arguments[local.key];
					}
				}
			}
		} else {
			application[local.appKey][StructKeyList(arguments)] = arguments[1];
		}
	}

	// ======================================================================
	// MULTI-TENANCY FUNCTIONS
	// ======================================================================

	/**
	 * Returns the current tenant struct, or an empty struct if no tenant is active.
	 * The tenant struct contains: `id`, `dataSource`, `config`, and `$locked`.
	 *
	 * [section: Configuration]
	 * [category: Multi-Tenancy]
	 */
	public struct function tenant() {
		if (IsDefined("request.wheels.tenant")) {
			return request.wheels.tenant;
		}
		return {};
	}

	/**
	 * Returns the current tenant's datasource name, or the application default if no tenant is active.
	 *
	 * [section: Configuration]
	 * [category: Multi-Tenancy]
	 */
	public string function $tenantDataSource() {
		if (
			IsDefined("request.wheels.tenant.dataSource")
			&& Len(request.wheels.tenant.dataSource)
		) {
			return request.wheels.tenant.dataSource;
		}
		return $get("dataSourceName");
	}

	/**
	 * Switches the active tenant mid-request. Throws if the current tenant is locked
	 * (set by TenantResolver middleware) unless `force` is true.
	 *
	 * [section: Configuration]
	 * [category: Multi-Tenancy]
	 *
	 * @tenant Struct with at minimum a `dataSource` key. Optional: `id`, `config`.
	 * @force If true, overrides the lock set by TenantResolver middleware.
	 */
	public void function switchTenant(required struct tenant, boolean force = false) {
		if (!StructKeyExists(arguments.tenant, "dataSource") || !Len(arguments.tenant.dataSource)) {
			Throw(type = "Wheels.InvalidTenant", message = "The tenant struct must contain a non-empty `dataSource` key.");
		}
		if (!StructKeyExists(request, "wheels")) {
			request.wheels = {};
		}
		// Check if current tenant is locked
		if (
			!arguments.force
			&& IsDefined("request.wheels.tenant")
			&& StructKeyExists(request.wheels.tenant, "$locked")
			&& request.wheels.tenant["$locked"]
		) {
			Throw(
				type = "Wheels.TenantLocked",
				message = "Cannot switch tenants mid-request. The current tenant was set by middleware and is locked.",
				extendedInfo = "Use `switchTenant(tenant={...}, force=true)` to override, or remove the lock in your middleware configuration."
			);
		}
		// Set defaults
		if (!StructKeyExists(arguments.tenant, "id")) {
			arguments.tenant.id = "";
		}
		if (!StructKeyExists(arguments.tenant, "config")) {
			arguments.tenant.config = {};
		}
		request.wheels.tenant = arguments.tenant;
	}

	// ======================================================================
	// CACHE FUNCTIONS
	// ======================================================================

	/**
	 * Creates a unique string based on any arguments passed in (used as a key for caching mostly).
	 */
	public string function $hashedKey() {
		local.rv = "";

		// make all cache keys domain specific (do not use request scope below since it may not always be initialized)
		StructInsert(arguments, ListLen(StructKeyList(arguments)) + 1, cgi.http_host, true);

		// we need to make sure we are looping through the passed in arguments in the same order everytime
		local.values = [];
		local.keyList = ListSort(StructKeyList(arguments), "textnocase", "asc");
		local.keyArray = ListToArray(local.keyList);
		local.iEnd = ArrayLen(local.keyArray);
		for (local.i = 1; local.i <= local.iEnd; local.i++) {
			ArrayAppend(local.values, arguments[local.keyArray[local.i]]);
		}

		if (!ArrayIsEmpty(local.values)) {
			// this might fail if a query contains binary data so in those rare cases we fall back on using cfwddx (which is a little bit slower which is why we don't use it all the time)
			try {
				local.rv = SerializeJSON(local.values);
				local.rv = $engineAdapter().normalizeForHash(local.rv);
			} catch (any e) {
				local.rv = $wddx(input = local.values);
			}
		}
		return Hash(local.rv);
	}

	/**
	 * Internal function.
	 * Case-sensitive, constant-time string comparison. Both values are hashed with
	 * SHA-256 before being compared via MessageDigest.isEqual so the comparison
	 * neither leaks length information nor exits early on the first differing byte.
	 * Used by the reload/restart password gate and the environment-switch gate.
	 */
	public boolean function $secureCompare(required string candidate, required string comparedValue) {
		return CreateObject("java", "java.security.MessageDigest").isEqual(
			Hash(arguments.candidate, "SHA-256").getBytes("UTF-8"),
			Hash(arguments.comparedValue, "SHA-256").getBytes("UTF-8")
		);
	}

	/**
	 * Internal function.
	 */
	public any function $timeSpanForCache(
		required any cache,
		numeric defaultCacheTime = application.wheels.defaultCacheTime,
		string cacheDatePart = application.wheels.cacheDatePart
	) {
		local.cache = arguments.defaultCacheTime;
		if (IsNumeric(arguments.cache)) {
			local.cache = arguments.cache;
		}
		local.listArray = [0, 0, 0, 0];
		local.dateParts = "d,h,n,s";
		local.datePartsArray = ListToArray(local.dateParts);
		local.iEnd = ArrayLen(local.datePartsArray);
		for (local.i = 1; local.i <= local.iEnd; local.i++) {
			if (arguments.cacheDatePart == local.datePartsArray[local.i]) {
				local.listArray[local.i] = local.cache;
			}
		}
		local.rv = CreateTimespan(local.listArray[1], local.listArray[2], local.listArray[3], local.listArray[4]);
		return local.rv;
	}

	/**
	 * Internal function.
	 */
	public void function $addToCache(
		required string key,
		required any value,
		numeric time = application.wheels.defaultCacheTime,
		string category = "main"
	) {
		local.currentCount = $cacheCount();
		if (
			application.wheels.cacheCullPercentage > 0
			&& application.wheels.cacheLastCulledAt < DateAdd("n", -application.wheels.cacheCullInterval, Now())
			&& local.currentCount >= application.wheels.maximumItemsToCache
		) {
			// the cache is full so flush out expired items to make more room if possible
			// (the maximum applies to the cache as a whole so we cull across all categories,
			// otherwise a write to a small category would free nothing and get dropped)
			local.deletedItems = 0;
			if (application.wheels.cacheCullPercentage < 100) {
				local.maxItemsToDelete = Ceiling(local.currentCount * application.wheels.cacheCullPercentage / 100);
			} else {
				local.maxItemsToDelete = local.currentCount;
			}
			local.now = Now();
			local.categories = StructKeyArray(application.wheels.cache);
			local.iEnd = ArrayLen(local.categories);
			for (local.i = 1; local.i <= local.iEnd && local.deletedItems < local.maxItemsToDelete; local.i++) {
				local.cacheCategory = local.categories[local.i];
				// snapshot the keys so we never delete from the struct we are iterating over
				local.cacheKeys = StructKeyArray(application.wheels.cache[local.cacheCategory]);
				local.jEnd = ArrayLen(local.cacheKeys);
				for (local.j = 1; local.j <= local.jEnd && local.deletedItems < local.maxItemsToDelete; local.j++) {
					local.cacheKey = local.cacheKeys[local.j];
					if (
						StructKeyExists(application.wheels.cache[local.cacheCategory], local.cacheKey)
						&& local.now > application.wheels.cache[local.cacheCategory][local.cacheKey].expiresAt
					) {
						$removeFromCache(key = local.cacheKey, category = local.cacheCategory);
						local.deletedItems++;
					}
				}
			}
			local.currentCount -= local.deletedItems;
			application.wheels.cacheLastCulledAt = Now();
		}
		if (local.currentCount < application.wheels.maximumItemsToCache) {
			local.cacheItem = {};
			local.cacheItem.expiresAt = DateAdd(application.wheels.cacheDatePart, arguments.time, Now());
			if (IsSimpleValue(arguments.value)) {
				local.cacheItem.value = arguments.value;
			} else {
				local.cacheItem.value = Duplicate(arguments.value);
			}
			application.wheels.cache[arguments.category][arguments.key] = local.cacheItem;
		}
	}

	/**
	 * Internal function.
	 */
	public any function $getFromCache(required string key, string category = "main") {
		local.rv = false;
		try {
			if (StructKeyExists(application.wheels.cache[arguments.category], arguments.key)) {
				if (Now() > application.wheels.cache[arguments.category][arguments.key].expiresAt) {
					$removeFromCache(key = arguments.key, category = arguments.category);
				} else {
					if (IsSimpleValue(application.wheels.cache[arguments.category][arguments.key].value)) {
						local.rv = application.wheels.cache[arguments.category][arguments.key].value;
					} else {
						local.rv = Duplicate(application.wheels.cache[arguments.category][arguments.key].value);
					}
				}
			}
		} catch (any e) {
		}
		return local.rv;
	}

	/**
	 * Internal function.
	 */
	public void function $removeFromCache(required string key, string category = "main") {
		StructDelete(application.wheels.cache[arguments.category], arguments.key);
	}

	/**
	 * Internal function.
	 */
	public numeric function $cacheCount(string category = "") {
		if (Len(arguments.category)) {
			local.rv = StructCount(application.wheels.cache[arguments.category]);
		} else {
			local.rv = 0;
			for (local.key in application.wheels.cache) {
				local.rv += StructCount(application.wheels.cache[local.key]);
			}
		}
		return local.rv;
	}

	/**
	 * Internal function.
	 */
	public void function $clearCache(string category = "") {
		if (Len(arguments.category)) {
			StructClear(application.wheels.cache[arguments.category]);
		} else {
			StructClear(application.wheels.cache);
		}
	}

	// ======================================================================
	// FACTORY FUNCTIONS
	// ======================================================================

	/**
	 * Internal function.
	 */
	public any function $cachedModelClassExists(required string name) {
		local.rv = false;
		if (StructKeyExists(application.wheels.models, arguments.name)) {
			local.rv = application.wheels.models[arguments.name];
		}
		return local.rv;
	}

	/**
	 * Internal function.
	 *
	 * Lock-free warm fast-path lookup used by `model()` to bypass
	 * `$doubleCheckedLock` and its `$invoke` reflective dispatch on cache
	 * hits. The full `StructKeyExists` chain guards early-bootstrap and
	 * post-`?reload=true` windows where `application.wheels.models` may
	 * not yet exist. Returns the cached class on hit, `false` on miss
	 * (callers fall through to the slow path).
	 */
	public any function $cachedModelLookup(required string name) {
		if (
			StructKeyExists(application, "wheels")
			&& StructKeyExists(application.wheels, "models")
			&& StructKeyExists(application.wheels.models, arguments.name)
		) {
			return application.wheels.models[arguments.name];
		}
		return false;
	}

	/**
	 * Internal function.
	 */
	public any function $cachedControllerClassExists(required string name) {
		local.rv = false;
		if (StructKeyExists(application.wheels.controllers, arguments.name)) {
			local.rv = application.wheels.controllers[arguments.name];
		}
		return local.rv;
	}

	/**
	 * Internal function.
	 *
	 * Lock-free warm fast-path lookup used by `controller()`. Same
	 * shape and bootstrap guards as `$cachedModelLookup`.
	 */
	public any function $cachedControllerLookup(required string name) {
		if (
			StructKeyExists(application, "wheels")
			&& StructKeyExists(application.wheels, "controllers")
			&& StructKeyExists(application.wheels.controllers, arguments.name)
		) {
			return application.wheels.controllers[arguments.name];
		}
		return false;
	}

	/**
	 * Internal function.
	 */
	public any function $createObjectFromRoot(required string path, required string fileName, required string method) {
		local.method = arguments.method;
		local.component = ListChangeDelims(arguments.path, ".", "/") & "." & ListChangeDelims(arguments.fileName, ".", "/");
		local.argumentCollection = arguments;
		if (local.method EQ 'init') {
			local.rv = application.wheelsdi.getInstance(name = "#local.component#", initArguments = local.argumentCollection);
		} else {
			local.instance = application.wheelsdi.getInstance(name = "#local.component#");
			local.rv = Invoke(local.instance, local.method, local.argumentCollection);
		}
		return local.rv;
	}

	/**
	 * Internal function.
	 */
	public void function $debugPoint(required string name) {
		if (!StructKeyExists(request.wheels, "execution")) {
			request.wheels.execution = {};
		}
		local.nameArray = ListToArray(arguments.name);
		local.iEnd = ArrayLen(local.nameArray);
		for (local.i = 1; local.i <= local.iEnd; local.i++) {
			local.item = local.nameArray[local.i];
			if (StructKeyExists(request.wheels.execution, local.item)) {
				request.wheels.execution[local.item] = GetTickCount() - request.wheels.execution[local.item];
			} else {
				request.wheels.execution[local.item] = GetTickCount();
			}
		}
	}

	/**
	 * Internal function.
	 */
	public any function $fileExistsNoCase(required string absolutePath) {
		local.appKey = $appKey();
		// return false by default when the file does not exist in the directory
		local.rv = false;
		// break up the full path string in the path name only and the file name only
		local.path = GetDirectoryFromPath(arguments.absolutePath);
		local.file = Replace(arguments.absolutePath, local.path, "");
		// get all existing files in the directory and place them in a list in application scope
		local.pathHash = Hash(local.path);
		if (!StructKeyExists(application[local.appKey].directoryFiles, local.pathHash)) {
			local.dirInfo = $directory(directory = local.path);
			application[local.appKey].directoryFiles[local.pathHash] = ValueList(local.dirInfo.name);
		}
		local.fileList = application[local.appKey].directoryFiles[local.pathHash];
		// loop through the file list and return the file name if exists regardless of case (the == operator is case insensitive)
		local.fileArray = ListToArray(local.fileList);
		local.iEnd = ArrayLen(local.fileArray);
		for (local.i = 1; local.i <= local.iEnd; local.i++) {
			local.foundFile = local.fileArray[local.i];
			if (local.foundFile == local.file) {
				local.rv = local.foundFile;
				break;
			}
		}
		return local.rv;
	}

	/**
	 * Internal function.
	 */
	public string function $objectFileName(required string name, required string objectPath, required string type) {
		// by default we return Model or Controller so that the base component gets loaded
		local.rv = capitalize(arguments.type);

		// we are going to memoize the full controller / model path in the
		// existing / non-existing structs so we can have controllers / models
		// in multiple places (structs give O(1) lookups and atomic writes where
		// the comma lists used previously were O(n) scans per materialized object
		// and lost entries to unlocked concurrent ListAppend calls)
		//
		// The name coming into $objectFileName could have dot notation due to
		// nested controllers so we need to change delims here on the name
		local.fullObjectPath = arguments.objectPath & "/" & ListChangeDelims(arguments.name, '/', '.');

		if (
			!StructKeyExists(application.wheels.existingObjectFiles, local.fullObjectPath)
			&& !StructKeyExists(application.wheels.nonExistingObjectFiles, local.fullObjectPath)
		) {
			// we have not yet checked if this file exists or not so let's do that
			// here (the function below will return the file name with the correct
			// case if it exists, false if not)
			local.file = $fileExistsNoCase(ExpandPath(local.fullObjectPath) & ".cfc");

			if (IsBoolean(local.file) && !local.file) {
				// no file exists, let's store that if caching is on so we don't have to check it again
				if (application.wheels.cacheFileChecking) {
					application.wheels.nonExistingObjectFiles[local.fullObjectPath] = false;
				}
			} else {
				// the file exists, let's store the proper case of the file if caching is turned on
				local.file = SpanExcluding(local.file, ".");
				if (application.wheels.cacheFileChecking) {
					application.wheels.existingObjectFiles[local.fullObjectPath] = local.file;
				}
			}
		}

		// if the file exists we return the file name in its proper case
		if (StructKeyExists(application.wheels.existingObjectFiles, local.fullObjectPath)) {
			local.file = application.wheels.existingObjectFiles[local.fullObjectPath];
		}

		// we've found a file so we'll need to send back the corrected name
		// argument as it could have dot notation in it from the mapper
		if (StructKeyExists(local, "file") and !IsBoolean(local.file)) {
			local.rv = ListSetAt(arguments.name, ListLen(arguments.name, "."), local.file, ".");
		}

		return local.rv;
	}

	/**
	 * Internal function.
	 */
	public any function $createControllerClass(
		required string name,
		string controllerPaths = $get("controllerPath"),
		string type = "controller"
	) {
		// let's allow for multiple controller paths so that plugins can contain controllers
		// the last path is the one we will instantiate the base controller on if the controller is not found on any of the paths
		local.controllerPathsArray = ListToArray(arguments.controllerPaths);
		local.iEnd = ArrayLen(local.controllerPathsArray);
		for (local.i = 1; local.i <= local.iEnd; local.i++) {
			local.controllerPath = local.controllerPathsArray[local.i];
			local.fileName = $objectFileName(name = arguments.name, objectPath = local.controllerPath, type = arguments.type);
			if (local.fileName != "Controller" || local.i == ArrayLen(local.controllerPathsArray)) {
				application.wheels.controllers[arguments.name] = $createObjectFromRoot(
					path = local.controllerPath,
					fileName = local.fileName,
					method = "$initControllerClass",
					name = arguments.name
				);

				local.rv = application.wheels.controllers[arguments.name];
				break;
			}
		}
		return local.rv;
	}

	/**
	 * Internal function.
	 */
	public any function $createModelClass(
		required string name,
		string modelPaths = application.wheels.modelPath,
		string type = "model"
	) {
		// let's allow for multiple model paths so that plugins can contain models
		// the last path is the one we will instantiate the base model on if the model is not found on any of the paths
		local.modelPathsArray = ListToArray(arguments.modelPaths);
		local.iEnd = ArrayLen(local.modelPathsArray);
		for (local.i = 1; local.i <= local.iEnd; local.i++) {
			local.modelPath = local.modelPathsArray[local.i];
			local.fileName = $objectFileName(name = arguments.name, objectPath = local.modelPath, type = arguments.type);
			if (local.fileName != arguments.type || local.i == ArrayLen(local.modelPathsArray)) {
				application.wheels.models[arguments.name] = $createObjectFromRoot(
					path = local.modelPath,
					fileName = local.fileName,
					method = "$initModelClass",
					name = arguments.name
				);
				local.rv = application.wheels.models[arguments.name];
				break;
			}
		}
		return local.rv;
	}

	/**
	 * Internal function.
	 */
	public void function $clearModelInitializationCache() {
		StructClear(application.wheels.models);
	}

	/**
	 * Internal function.
	 */
	public void function $clearControllerInitializationCache() {
		StructClear(application.wheels.controllers);
	}

	/**
	 * Creates and returns a controller object with your own custom name and params.
	 * Used primarily for testing purposes.
	 *
	 * [section: Global Helpers]
	 * [category: Miscellaneous Functions]
	 *
	 * @name Name of the controller to create.
	 * @params The params struct (combination of form and URL variables).
	 */
	public any function controller(required string name, struct params = {}) {
		// Lock-free warm fast path: skip $doubleCheckedLock + $invoke
		// reflective dispatch on cache hits (issue #2897, Stage 1). Returns
		// the cached *class*; the params branch below still creates an
		// instance when params is non-empty.
		local.rv = $cachedControllerLookup(name = arguments.name);
		if (IsBoolean(local.rv) && !local.rv) {
			local.args = {};
			local.args.name = arguments.name;
			local.rv = $doubleCheckedLock(
				condition = "$cachedControllerClassExists",
				conditionArgs = local.args,
				execute = "$createControllerClass",
				executeArgs = local.args,
				name = "controllerLock#application.applicationName#"
			);
		}
		if (!StructIsEmpty(arguments.params)) {
			local.rv = local.rv.$createControllerObject(arguments.params);
		}
		return local.rv;
	}

	/**
	 * Returns a reference to the requested model so that class level methods can be called on it.
	 *
	 * [section: Global Helpers]
	 * [category: Miscellaneous Functions]
	 *
	 * @name Name of the model to get a reference to.
	 */
	public any function model(required string name) {
		// Lock-free warm fast path: skip $doubleCheckedLock + $invoke
		// reflective dispatch on cache hits (issue #2897, Stage 1).
		local.rv = $cachedModelLookup(name = arguments.name);
		if (IsBoolean(local.rv) && !local.rv) {
			return $doubleCheckedLock(
				condition = "$cachedModelClassExists",
				conditionArgs = arguments,
				execute = "$createModelClass",
				executeArgs = arguments,
				name = "modelLock#application.applicationName#"
			);
		}
		return local.rv;
	}

	/**
	 * Resolve a DI-registered service by name.
	 *
	 * [section: Global Helpers]
	 * [category: Miscellaneous Functions]
	 *
	 * @name The registered service name to resolve.
	 */
	public any function service(required string name) {
		if (!IsDefined("application.wheelsdi")) {
			Throw(
				type = "Wheels.DI.NotInitialized",
				message = "The DI container has not been initialized. Ensure your application has started properly."
			);
		}
		if (!application.wheelsdi.containsInstance(arguments.name)) {
			Throw(
				type = "Wheels.DI.ServiceNotFound",
				message = "No service registered with the name '#arguments.name#'. Check your config/services.cfm registrations."
			);
		}
		return application.wheelsdi.getInstance(arguments.name);
	}

	/**
	 * Return a reference to the DI container for direct configuration.
	 *
	 * [section: Global Helpers]
	 * [category: Miscellaneous Functions]
	 */
	public any function injector() {
		if (!IsDefined("application.wheelsdi")) {
			Throw(
				type = "Wheels.DI.NotInitialized",
				message = "The DI container has not been initialized. Ensure your application has started properly."
			);
		}
		return application.wheelsdi;
	}

	// ======================================================================
	// CHANNEL / PUB-SUB FUNCTIONS
	// ======================================================================

	/**
	 * Publish an event to a channel.
	 * Delegates to the in-memory Channel engine or the DatabaseAdapter
	 * depending on the adapter argument (or the global channelAdapter setting).
	 *
	 * Can be called from controllers, models, jobs, or anywhere with access
	 * to global helpers.
	 *
	 * [section: Global Helpers]
	 * [category: Channel Functions]
	 *
	 * @channel The channel name to publish to (e.g. "user.42").
	 * @event The event type (e.g. "notification", "update").
	 * @data The event data as a string (typically JSON).
	 * @adapter Adapter to use: "memory" (default) or "database".
	 */
	public struct function publish(
		required string channel,
		required string event,
		required string data,
		string adapter = ""
	) {
		local.engine = $getChannelEngine(arguments.adapter);
		return local.engine.publish(channel = arguments.channel, event = arguments.event, data = arguments.data);
	}

	/**
	 * Internal: Get or create the channel engine singleton for the given adapter type.
	 * Uses double-checked locking to ensure thread-safe lazy initialization.
	 *
	 * @adapter "memory" or "database". Defaults to application.wheels.channelAdapter or "memory".
	 */
	public any function $getChannelEngine(string adapter = "") {
		// Resolve adapter type
		if (!Len(arguments.adapter)) {
			if (StructKeyExists(application, "wheels") && StructKeyExists(application.wheels, "channelAdapter")) {
				local.adapterType = application.wheels.channelAdapter;
			} else {
				local.adapterType = "memory";
			}
		} else {
			local.adapterType = arguments.adapter;
		}

		if (local.adapterType == "database") {
			if (!StructKeyExists(application, "wheels") || !StructKeyExists(application.wheels, "channelDatabaseEngine")) {
				lock name="wheelsChannelDatabaseEngine" timeout="10" {
					if (!StructKeyExists(application, "wheels") || !StructKeyExists(application.wheels, "channelDatabaseEngine")) {
						application.wheels.channelDatabaseEngine = CreateObject("component", "wheels.channel.DatabaseAdapter").init();
					}
				}
			}
			return application.wheels.channelDatabaseEngine;
		}

		// Default: memory adapter
		if (!StructKeyExists(application, "wheels") || !StructKeyExists(application.wheels, "channelEngine")) {
			lock name="wheelsChannelEngine" timeout="10" {
				if (!StructKeyExists(application, "wheels") || !StructKeyExists(application.wheels, "channelEngine")) {
					application.wheels.channelEngine = CreateObject("component", "wheels.Channel").init();
				}
			}
		}
		return application.wheels.channelEngine;
	}

	// ======================================================================
	// ROUTING FUNCTIONS
	// ======================================================================

	/**
	 * Internal function.
	 */
	public string function $routeVariables() {
		return $findRoute(argumentCollection = arguments).foundvariables;
	}

	/**
	 * Internal function.
	 */
	public struct function $findRoute() {
		// Throw error if no route was found.
		if (!StructKeyExists(application.wheels.namedRoutePositions, arguments.route)) {
			$throwErrorOrShow404Page(
				type = "Wheels.RouteNotFound",
				message = "Could not find the `#arguments.route#` route.",
				extendedInfo = "Make sure there is a route configured in your `config/routes.cfm` file named `#arguments.route#`."
			);
		}
		local.routePos = application.wheels.namedRoutePositions[arguments.route];
		if (Find(",", local.routePos)) {
			// there are several routes with this name so we need to figure out which one to use by checking the passed in arguments
			local.iEnd = ListLen(local.routePos);
			for (local.i = 1; local.i <= local.iEnd; local.i++) {
				local.rv = application.wheels.routes[ListGetAt(local.routePos, local.i)];
				local.foundRoute = StructKeyExists(arguments, "method") && local.rv.methods == arguments.method;
				local.jEnd = ListLen(local.rv.foundvariables);
				for (local.j = 1; local.j <= local.jEnd; local.j++) {
					local.variable = ListGetAt(local.rv.foundvariables, local.j);
					if (!StructKeyExists(arguments, local.variable) || !Len(arguments[local.variable])) {
						local.foundRoute = false;
					}
				}
				if (local.foundRoute) {
					break;
				}
			}
		} else {
			local.rv = application.wheels.routes[local.routePos];
		}
		return local.rv;
	}

	/**
	 * Internal function.
	 */
	public any function $constructParams(
		required string params,
		boolean encode = true,
		boolean $encodeForHtmlAttribute = false,
		string $URLRewriting = application.wheels.URLRewriting
	) {
		// When rewriting is off we will already have "?controller=" etc in the url so we have to continue with an ampersand.
		if (arguments.$URLRewriting == "Off") {
			local.delim = "&";
		} else {
			local.delim = "?";
		}

		local.rv = "";
		local.paramsArray = ListToArray(arguments.params, "&");
		local.iEnd = ArrayLen(local.paramsArray);
		for (local.i = 1; local.i <= local.iEnd; local.i++) {
			local.params = ListToArray(local.paramsArray[local.i], "=");
			local.name = local.params[1];
			if (arguments.encode && $get("encodeURLs")) {
				local.name = EncodeForURL($canonicalize(local.name));
				if (arguments.$encodeForHtmlAttribute) {
					local.name = EncodeForHTMLAttribute(local.name);
				}
			}
			local.rv &= local.delim & local.name & "=";
			local.delim = "&";
			if (ArrayLen(local.params) == 2) {
				local.value = local.params[2];
				if (arguments.encode && $get("encodeURLs")) {
					local.value = EncodeForURL($canonicalize(local.value));
					if (arguments.$encodeForHtmlAttribute) {
						local.value = EncodeForHTMLAttribute(local.value);
					}
				}

				// Obfuscate the param if set globally and we're not processing cfid or cftoken (can't touch those).
				// Wrap in double quotes because in Lucee we have to pass it in as a string otherwise leading zeros are stripped.
				if (application.wheels.obfuscateUrls && !ListFindNoCase("cfid,cftoken", local.name)) {
					local.value = obfuscateParam("#local.value#");
				}

				local.rv &= local.value;
			}
		}
		return local.rv;
	}

	/**
	 * Internal function.
	 */
	public string function $prependUrl(required string path, string host = "", string protocol = "", numeric port = 0) {
		local.rv = arguments.path;
		if (arguments.port != 0) {
			// use the port that was passed in by the developer
			local.rv = ":" & arguments.port & local.rv;
		} else if (request.cgi.server_port != 80 && request.cgi.server_port != 443) {
			// if the port currently in use is not 80 or 443 we set it explicitly in the URL
			local.rv = ":" & request.cgi.server_port & local.rv;
		}
		if (Len(arguments.host)) {
			local.rv = arguments.host & local.rv;
		} else {
			local.rv = request.cgi.server_name & local.rv;
		}
		if (Len(arguments.protocol)) {
			local.rv = arguments.protocol & "://" & local.rv;
		} else if (request.cgi.http_x_forwarded_proto == "https" || request.cgi.server_port_secure == "true") {
			local.rv = "https://" & local.rv;
		} else {
			local.rv = "http://" & local.rv;
		}
		return local.rv;
	}

	/**
	 * Internal function.
	 */
	public void function $loadRoutes() {
		$simpleLock(name = "$mapperLoadRoutes", type = "exclusive", timeout = 5, execute = "$lockedLoadRoutes");
	}

	/**
	 * Internal function.
	 */
	public void function $lockedLoadRoutes() {
		local.appKey = $appKey();
		// clear out the route info (including the static-route index so a reload
		// can't serve stale first-write-wins entries from the previous route set)
		ArrayClear(application[local.appKey].routes);
		StructClear(application[local.appKey].namedRoutePositions);
		if (StructKeyExists(application[local.appKey], "staticRoutes")) {
			StructClear(application[local.appKey].staticRoutes);
		}
		// Drop the URLFor controller/action memo so cached lookups from the
		// previous route set (including negative-cached misses) can't leak
		// across a reload. `$addRoute` also clears the memo, but doing it
		// here guarantees a freshly-reloaded app starts with an empty cache
		// even before the first `$addRoute` call runs.
		if (StructKeyExists(application[local.appKey], "urlForCache")) {
			StructClear(application[local.appKey].urlForCache);
		}
		// load wheels internal gui routes
		// TODO skip this if mode != development|testing?
		$include(template = "/wheels/public/routes.cfm");
		// Browser-test fixture routes — opt-in, only mounted in testing/development.
		// See `vendor/wheels/public/browser-fixtures/routes.cfm` and issues #2135, #2138.
		// The fixture controllers live at `vendor/wheels/public/browser-fixtures/controllers/`
		// and render their own views via explicit `$include`, so only `controllerPath`
		// needs to be extended (viewPath is single-string and left alone).
		if (
			StructKeyExists(application[local.appKey], "loadBrowserTestFixtures")
			&& application[local.appKey].loadBrowserTestFixtures
			&& StructKeyExists(application[local.appKey], "environment")
			&& ListFindNoCase("testing,development", application[local.appKey].environment)
		) {
			local.fixtureControllerPath = "/wheels/public/browser-fixtures/controllers";
			if (!ListFindNoCase(application[local.appKey].controllerPath, local.fixtureControllerPath)) {
				application[local.appKey].controllerPath = ListAppend(
					application[local.appKey].controllerPath,
					local.fixtureControllerPath
				);
			}
			$include(template = "/wheels/public/browser-fixtures/routes.cfm");
		}
		// load developer routes next
		$include(template = "/config/routes.cfm");
		// set lookup info for the named routes
		$setNamedRoutePositions();
	}

	/**
	 * Internal function.
	 */
	public void function $setNamedRoutePositions() {
		local.appKey = $appKey();
		local.iEnd = ArrayLen(application[local.appKey].routes);
		for (local.i = 1; local.i <= local.iEnd; local.i++) {
			local.route = application[local.appKey].routes[local.i];
			if (StructKeyExists(local.route, "name") && Len(local.route.name)) {
				if (!StructKeyExists(application[local.appKey].namedRoutePositions, local.route.name)) {
					application[local.appKey].namedRoutePositions[local.route.name] = "";
				}
				application[local.appKey].namedRoutePositions[local.route.name] = ListAppend(
					application[local.appKey].namedRoutePositions[local.route.name],
					local.i
				);
			}
		}
	}

	/**
	 * Creates an internal URL based on supplied arguments.
	 *
	 * [section: Global Helpers]
	 * [category: Miscellaneous Functions]
	 *
	 * @route Name of a route that you have configured in `config/routes.cfm`.
	 * @controller Name of the controller to include in the URL.
	 * @action Name of the action to include in the URL.
	 * @key Key(s) to include in the URL.
	 * @params Any additional parameters to be set in the query string (example: `wheels=cool&x=y`). Please note that Wheels uses the `&` and `=` characters to split the parameters and encode them properly for you. However, if you need to pass in `&` or `=` as part of the value, then you need to encode them (and only them), example: `a=cats%26dogs%3Dtrouble!&b=1`.
	 * @anchor Sets an anchor name to be appended to the path.
	 * @onlyPath If `true`, returns only the relative URL (no protocol, host name or port).
	 * @host Set this to override the current host.
	 * @protocol Set this to override the current protocol.
	 * @port Set this to override the current port number.
	 * @encode Encode URL parameters using `EncodeForURL()`. Please note that this does not make the string safe for placement in HTML attributes, for that you need to wrap the result in `EncodeForHtmlAttribute()` or use `linkTo()`, `startFormTag()` etc instead.
	 */
	public string function URLFor(
		string route = "",
		string controller = "",
		string action = "",
		any key = "",
		string params = "",
		string anchor = "",
		boolean onlyPath,
		string host,
		string protocol,
		numeric port,
		boolean encode,
		boolean $encodeForHtmlAttribute = false,
		string $URLRewriting = application.wheels.URLRewriting
	) {
		$args(name = "URLFor", args = arguments);
		local.coreVariables = "controller,action,key,format";
		local.params = {};
		if (StructKeyExists(variables, "params")) {
			StructAppend(local.params, variables.params);
		}

		// Throw error if host or protocol are passed with onlyPath=true.
		local.hostOrProtocolNotEmpty = Len(arguments.host) || Len(arguments.protocol);
		if (application.wheels.showErrorInformation && arguments.onlyPath && local.hostOrProtocolNotEmpty) {
			Throw(
				type = "Wheels.IncorrectArguments",
				message = "Can't use the `host` or `protocol` arguments when `onlyPath` is `true`.",
				extendedInfo = "Set `onlyPath` to `false` so that `linkTo` will create absolute URLs and thus allowing you to set the `host` and `protocol` on the link."
			);
		}

		// Look up actual route paths instead of providing default Wheels path generation.
		// Loop over all routes to find matching one, break the loop on first match.
		// The (controller, action) → route-name memo lives in application scope and
		// negative-caches misses (empty string sentinel) so wildcard-`[controller]`
		// apps — where `$addRoute` strips the `controller` key, guaranteeing no
		// match — don't re-scan the route table for every link helper. The cache
		// is invalidated by `$addRoute` and `$lockedLoadRoutes`.
		if (!Len(arguments.route) && Len(arguments.action)) {
			if (!Len(arguments.controller)) {
				arguments.controller = local.params.controller;
			}
			local.appKey = $appKey();
			if (!StructKeyExists(application[local.appKey], "urlForCache")) {
				application[local.appKey].urlForCache = {};
			}
			local.cache = application[local.appKey].urlForCache;
			local.key = arguments.controller & "##" & arguments.action;
			if (!StructKeyExists(local.cache, local.key)) {
				local.found = "";
				local.iEnd = ArrayLen(application[local.appKey].routes);
				for (local.i = 1; local.i <= local.iEnd; local.i++) {
					local.route = application[local.appKey].routes[local.i];
					local.controllerMatch = StructKeyExists(local.route, "controller") && local.route.controller == arguments.controller;
					local.actionMatch = StructKeyExists(local.route, "action") && local.route.action == arguments.action;
					if (local.controllerMatch && local.actionMatch) {
						local.found = local.route.name;
						break;
					}
				}
				local.cache[local.key] = local.found;
			}
			if (Len(local.cache[local.key])) {
				arguments.route = local.cache[local.key];
			}
		}

		// Start building the URL to return by setting the sub folder path and script name portion.
		// Script name index.cfm will be removed later if applicable (e.g. when URL rewriting is on).
		local.rv = application.wheels.webPath & ListLast(request.cgi.script_name, "/");

		// Look up route pattern to use and add it to the URL to return.
		// Either from a passed in route or the Wheels default one.
		// For the Wheels default we set the controller and action arguments to what's in the params struct.
		if (Len(arguments.route)) {
			local.route = $findRoute(argumentCollection = arguments);
			local.foundVariables = local.route.foundvariables;

			if (arguments.$URLRewriting neq "Off") {
				local.rv &= local.route.pattern;
			} else {
				// Always include core variables when not rewriting
				local.foundVariables &= "," & local.coreVariables;
				local.rv &= "?controller=[controller]&action=[action]&key=[key]&format=[format]";
			}
		} else {
			local.route = {};
			local.foundVariables = local.coreVariables;
			local.rv &= "?controller=[controller]&action=[action]&key=[key]&format=[format]";
		}

		// Shared fallback logic for controller/action
		if (StructKeyExists(local, "params")) {
			// Handle action
			if (!Len(arguments.action)) {
				if (StructKeyExists(local.route, "action")) {
					arguments.action = local.route.action;
				} else if (Len(arguments.controller)) {
					arguments.action = "index";
				} else if (StructKeyExists(local.params, "action")) {
					arguments.action = local.params.action;
				}
			}

			// Handle controller
			if (!Len(arguments.controller)) {
				if (StructKeyExists(local.route, "controller")) {
					arguments.controller = local.route.controller;
				} else if (StructKeyExists(local.params, "controller")) {
					arguments.controller = local.params.controller;
				}
			}
		}

		// Replace each params variable with the correct value.
		for (local.i = 1; local.i <= ListLen(local.foundVariables); local.i++) {
			local.property = ListGetAt(local.foundVariables, local.i);
			local.reg = "\[\*?#local.property#\]";

			// Read necessary variables from different sources.
			if (StructKeyExists(arguments, local.property) && Len(arguments[local.property])) {
				local.value = arguments[local.property];
			} else if (StructKeyExists(local.route, local.property)) {
				local.value = local.route[local.property];
			} else if (Len(arguments.route) && arguments.$URLRewriting != "Off") {
				Throw(
					type = "Wheels.IncorrectRoutingArguments",
					message = "Incorrect Arguments",
					extendedInfo = "The route chosen by Wheels `#local.route.name#` requires the argument `#local.property#`. Pass the argument `#local.property#` or change your routes to reflect the proper variables needed."
				);
			} else {
				continue;
			}

			// If value is a model object, get its key value.
			if (IsObject(local.value)) {
				local.value = local.value.key();
			}

			// Any value we find from above, URL encode it here.
			if (arguments.encode && $get("encodeURLs")) {
				local.value = EncodeForURL($canonicalize(local.value));
				if (arguments.$encodeForHtmlAttribute) {
					local.value = EncodeForHTMLAttribute(local.value);
				}
			}

			// If property is not in pattern, store it in the params argument.
			if (!ReFind(local.reg, local.rv)) {
				if (!ListFindNoCase(local.coreVariables, local.property)) {
					arguments.params = ListAppend(arguments.params, "#local.property#=#local.value#", "&");
				}
				continue;
			}

			// Transform value before setting it in pattern.
			if (local.property == "controller" || local.property == "action") {
				local.value = hyphenize(local.value);
			} else if (application.wheels.obfuscateUrls) {
				local.value = obfuscateParam(local.value);
			}
			local.rv = ReReplace(local.rv, local.reg, local.value);
		}

		// Clean up unused keys in pattern.
		local.rv = ReReplace(local.rv, "((&|\?)\w+=|\/|\.)\[\*?\w+\]", "", "ALL");

		// When URL rewriting is on (or partially) we replace the "?controller="" stuff in the URL with just "/".
		if (arguments.$URLRewriting != "Off") {
			local.rv = Replace(local.rv, "?controller=", "/");
			local.rv = Replace(local.rv, "&action=", "/");
			local.rv = Replace(local.rv, "&key=", "/");
		}

		// When URL rewriting is on we remove the rewrite file name (e.g. index.cfm) from the URL so it doesn't show.
		// Also get rid of the double "/" that this removal typically causes.
		if (arguments.$URLRewriting == "On") {
			local.rv = Replace(local.rv, application.wheels.rewriteFile, "");
			local.rv = Replace(local.rv, "//", "/");
		}

		// Add params to the URL when supplied.
		if (Len(arguments.params)) {
			local.rv &= $constructParams(
				params = arguments.params,
				encode = arguments.encode,
				$encodeForHtmlAttribute = arguments.$encodeForHtmlAttribute,
				$URLRewriting = arguments.$URLRewriting
			);
		}

		// Add an anchor to the the URL when supplied.
		if (Len(arguments.anchor)) {
			local.rv &= "##" & arguments.anchor;
		}

		// Prepend the full URL if directed.
		if (!arguments.onlyPath) {
			local.rv = $prependUrl(path = local.rv, argumentCollection = arguments);
		}

		return local.rv;
	}

	/**
	 * Returns the mapper object used to configure your application's routes. Usually you will use this method in `config/routes.cfm` to start chaining route mapping methods like `resources`, `namespace`, etc.
	 *
	 * [section: Configuration]
	 * [category: Routing]
	 *
	 * @restful Whether to turn on RESTful routing or not. Not recommended to set. Will probably be removed in a future version of wheels, as RESTful routes are the default.
	 * @methods If not RESTful, then specify allowed routes. Not recommended to set. Will probably be removed in a future version of wheels, as RESTful routes are the default.
	 * @mapFormat This is useful for providing formats via URL like `json`, `xml`, `pdf`, etc. Set to false to disable automatic .[format] generation for resource based routes
	 */
	public struct function mapper(boolean restful = true, boolean methods = arguments.restful, boolean mapFormat = true) {
		return application[$appKey()].mapper.$draw(argumentCollection = arguments);
	}

	// ======================================================================
	// TEXT FUNCTIONS
	// ======================================================================

	/**
	 * Internal function.
	 */
	public string function $singularizeOrPluralize(
		required string text,
		required string which,
		numeric count = -1,
		boolean returnCount = true
	) {
		// by default we pluralize/singularize the entire string
		local.text = arguments.text;

		// keep track of the success of any rule matches
		local.ruleMatched = false;

		// when count is 1 we don't need to pluralize at all so just set the return value to the input string
		local.rv = local.text;

		if (arguments.count != 1) {
			if (ReFind("[A-Z]", local.text)) {
				// only pluralize/singularize the last part of a camelCased variable (e.g. in "websiteStatusUpdate" we only change the "update" part)
				// also set a variable with the unchanged part of the string (to be prepended before returning final result)
				local.upperCasePos = ReFind("[A-Z]", Reverse(local.text));
				local.prepend = Mid(local.text, 1, Len(local.text) - local.upperCasePos);
				local.text = Reverse(Mid(Reverse(local.text), 1, local.upperCasePos));
			}

			// Get global settings for uncountable and irregular words.
			// For the irregular ones we need to convert them from a struct to a list.
			local.uncountables = $listClean($get("uncountables"));
			local.irregulars = "";
			local.words = $get("irregulars");
			for (local.word in local.words) {
				local.irregulars = ListAppend(local.irregulars, LCase(local.word));
				local.irregulars = ListAppend(local.irregulars, local.words[local.word]);
			}

			if (ListFindNoCase(local.uncountables, local.text)) {
				local.rv = local.text;
				local.ruleMatched = true;
			} else if (ListFindNoCase(local.irregulars, local.text)) {
				local.pos = ListFindNoCase(local.irregulars, local.text);
				if (arguments.which == "singularize" && local.pos % 2 == 0) {
					local.rv = ListGetAt(local.irregulars, local.pos - 1);
				} else if (arguments.which == "pluralize" && local.pos % 2 != 0) {
					local.rv = ListGetAt(local.irregulars, local.pos + 1);
				} else {
					local.rv = local.text;
				}
				local.ruleMatched = true;
			} else {
				if (arguments.which == "pluralize") {
					local.ruleList = "(quiz)$,\1zes,^(ox)$,\1en,([m|l])ouse$,\1ice,(matr|vert|ind)ix|ex$,\1ices,(x|ch|ss|sh)$,\1es,([^aeiouy]|qu)y$,\1ies,(hive)$,\1s,(?:([^f])fe|([lr])f)$,\1\2ves,sis$,ses,([ti])um$,\1a,(buffal|tomat|potat|volcan|her)o$,\1oes,(bu)s$,\1ses,(alias|status)$,\1es,(octop|vir)us$,\1i,(ax|test)is$,\1es,s$,s,$,s";
				} else if (arguments.which == "singularize") {
					local.ruleList = "(quiz)zes$,\1,(matr)ices$,\1ix,(vert|ind)ices$,\1ex,^(ox)en,\1,(alias|status)es$,\1,([octop|vir])i$,\1us,(cris|ax|test)es$,\1is,(shoe)s$,\1,(o)es$,\1,(bus)es$,\1,([m|l])ice$,\1ouse,(x|ch|ss|sh)es$,\1,(m)ovies$,\1ovie,(s)eries$,\1eries,([^aeiouy]|qu)ies$,\1y,([lr])ves$,\1f,(tive)s$,\1,(hive)s$,\1,([^f])ves$,\1fe,(^analy)ses$,\1sis,((a)naly|(b)a|(d)iagno|(p)arenthe|(p)rogno|(s)ynop|(t)he)ses$,\1\2sis,([ti])a$,\1um,(n)ews$,\1ews,(.*)?ss$,\1ss,s$,#Chr(7)#";
				}
				local.rules = ArrayNew(2);
				local.count = 1;
				local.iEnd = ListLen(local.ruleList);
				for (local.i = 1; local.i <= local.iEnd; local.i = local.i + 2) {
					local.rules[local.count][1] = ListGetAt(local.ruleList, local.i);
					local.rules[local.count][2] = ListGetAt(local.ruleList, local.i + 1);
					local.count = local.count + 1;
				}
				local.iEnd = ArrayLen(local.rules);
				for (local.i = 1; local.i <= local.iEnd; local.i++) {
					if (ReFindNoCase(local.rules[local.i][1], local.text)) {
						local.rv = ReReplaceNoCase(local.text, local.rules[local.i][1], local.rules[local.i][2]);
						local.ruleMatched = true;
						break;
					}
				}
				local.rv = Replace(local.rv, Chr(7), "", "all");
			}

			// this was a camelCased string and we need to prepend the unchanged part to the result
			if (StructKeyExists(local, "prepend") && local.ruleMatched) {
				local.rv = local.prepend & local.rv;
			}
		}

		// return the count number in the string (e.g. "5 sites" instead of just "sites")
		if (arguments.returnCount && arguments.count != -1) {
			local.rv = LsNumberFormat(arguments.count) & " " & local.rv;
		}
		return local.rv;
	}

	/**
	 * Capitalizes the first character of the supplied string.
	 *
	 * [section: Global Helpers]
	 * [category: String Functions]
	 *
	 * @text String to capitalize.
	 */
	public string function capitalize(required string text) {
		local.rv = arguments.text;
		if (Len(local.rv)) {
			local.rv = UCase(Left(local.rv, 1)) & Mid(local.rv, 2, Len(local.rv) - 1);
		}
		return local.rv;
	}

	/**
	 * Returns readable text by capitalizing and converting camel casing to multiple words.
	 *
	 * [section: Global Helpers]
	 * [category: String Functions]
	 *
	 * @text Text to humanize.
	 * @except A list of strings (space separated) to replace within the output.
	 *
	 */
	public string function humanize(required string text, string except = "") {
		// add a space before every capitalized word
		local.rv = ReReplace(arguments.text, "([[:upper:]])", " \1", "all");

		// remove space after punctuation chars
		local.rv = ReReplace(local.rv, "([[:punct:]])([[:space:]])", "\1", "all");

		// fix abbreviations so they form a word again (example: aURLVariable)
		local.rv = ReReplace(local.rv, "([[:upper:]]) ([[:upper:]])(?:\s|\b)", "\1\2", "all");
		local.rv = ReReplace(local.rv, "([[:upper:]])([[:upper:]])([[:lower:]])", "\1\2 \3", "all");

		if (Len(arguments.except)) {
			local.exceptKeysArray = ListToArray(arguments.except, " ");
			local.iEnd = ArrayLen(local.exceptKeysArray);
			for (local.i = 1; local.i <= local.iEnd; local.i++) {
				local.item = local.exceptKeysArray[local.i];
				local.rv = ReReplaceNoCase(local.rv, "#local.item#(?:\b)", "#local.item#", "all");
			}
		}

		// support multiple word input by stripping out all double spaces created
		local.rv = Replace(local.rv, "  ", " ", "all");

		// capitalize the first letter and trim final result (which removes the leading space that happens if the string starts with an upper case character)
		local.rv = Trim(capitalize(local.rv));
		return local.rv;
	}

	/**
	 * Returns the plural form of the passed in word. Can also pluralize a word based on a value passed to the `count` argument. Wheels stores a list of words that are the same in both singular and plural form (e.g. "equipment", "information") and words that don't follow the regular pluralization rules (e.g. "child" / "children", "foot" / "feet"). Use `get("uncountables")` / `set("uncountables", newList)` and `get("irregulars")` / `set("irregulars", newList)` to modify them to suit your needs.
	 *
	 * [section: Global Helpers]
	 * [category: String Functions]
	 *
	 * @word The word to pluralize.
	 * @count Pluralization will occur when this value is not 1.
	 * @returnCount Will return count prepended to the pluralization when true and count is not -1.
	 */
	public string function pluralize(required string word, numeric count = "-1", boolean returnCount = "true") {
		return $singularizeOrPluralize(
			count = arguments.count,
			returnCount = arguments.returnCount,
			text = arguments.word,
			which = "pluralize"
		);
	}

	/**
	 * Returns the singular form of the passed in word.
	 *
	 * [section: Global Helpers]
	 * [category: String Functions]
	 *
	 * @word The word to singularize.
	 */
	public string function singularize(required string word) {
		return $singularizeOrPluralize(text = arguments.word, which = "singularize");
	}

	/**
	 * Converts camelCase strings to lowercase strings with hyphens as word delimiters instead. Example: myVariable becomes my-variable.
	 *
	 * [section: Global Helpers]
	 * [category: String Functions]
	 *
	 * @string The string to hyphenize.
	 */
	public string function hyphenize(required string string) {
		local.rv = ReReplace(arguments.string, "([A-Z][a-z])", "-\l\1", "all");
		local.rv = ReReplace(local.rv, "([a-z])([A-Z])", "\1-\l\2", "all");
		local.rv = ReReplace(local.rv, "^-", "", "one");
		local.rv = LCase(local.rv);
		return local.rv;
	}

	/**
	 * Capitalizes all words in the text to create a nicer looking title.
	 *
	 * [section: Global Helpers]
	 * [category: String Functions]
	 *
	 * @word The text to turn into a title.
	 */
	public string function titleize(required string word) {
		local.rv = "";
		local.iEnd = ListLen(arguments.word, " ");
		for (local.i = 1; local.i <= local.iEnd; local.i++) {
			local.rv = ListAppend(local.rv, capitalize(ListGetAt(arguments.word, local.i, " ")), " ");
		}
		return local.rv;
	}

	/**
	 * Truncates text to the specified length and replaces the last characters with the specified truncate string (which defaults to "...").
	 *
	 * [section: Global Helpers]
	 * [category: String Functions]
	 *
	 * @text The text to truncate.
	 * @length Length to truncate the text to.
	 * @truncateString String to replace the last characters with.
	 */
	public string function truncate(required string text, numeric length, string truncateString) {
		$args(name = "truncate", args = arguments);
		if (Len(arguments.text) > arguments.length) {
			local.rv = Left(arguments.text, arguments.length - Len(arguments.truncateString)) & arguments.truncateString;
		} else {
			local.rv = arguments.text;
		}
		return local.rv;
	}

	/**
	 * Truncates text to the specified length of words and replaces the remaining characters with the specified truncate string (which defaults to "...").
	 *
	 * [section: Global Helpers]
	 * [category: String Functions]
	 *
	 * @text The text to truncate.
	 * @length Number of words to truncate the text to.
	 * @truncateString String to replace the last characters with.
	 */
	public string function wordTruncate(required string text, numeric length, string truncateString) {
		$args(name = "wordTruncate", args = arguments);
		local.words = ListToArray(arguments.text, " ", false);

		// When there are fewer (or same) words in the string than the number to be truncated we can just return it unchanged.
		if (ArrayLen(local.words) <= arguments.length) {
			return arguments.text;
		}

		local.rv = "";
		local.iEnd = arguments.length;
		for (local.i = 1; local.i <= local.iEnd; local.i++) {
			local.rv = ListAppend(local.rv, local.words[local.i], " ");
		}
		local.rv &= arguments.truncateString;
		return local.rv;
	}

	/**
	 * Extracts an excerpt from text that matches the first instance of a given phrase.
	 *
	 * [section: Global Helpers]
	 * [category: String Functions]
	 *
	 * @text The text to extract an excerpt from.
	 * @phrase The phrase to extract.
	 * @radius Number of characters to extract surrounding the phrase.
	 * @excerptString String to replace first and / or last characters with.
	 */
	public string function excerpt(required string text, required string phrase, numeric radius, string excerptString) {
		$args(name = "excerpt", args = arguments);
		local.pos = FindNoCase(arguments.phrase, arguments.text, 1);

		// Return an empty value if the text wasn't found at all.
		if (!local.pos) {
			return "";
		}

		// Set start info based on whether the excerpt text found, including its radius, comes before the start of the string.
		if ((local.pos - arguments.radius) <= 1) {
			local.startPos = 1;
			local.truncateStart = "";
		} else {
			local.startPos = local.pos - arguments.radius;
			local.truncateStart = arguments.excerptString;
		}

		// Set end info based on whether the excerpt text found, including its radius, comes after the end of the string.
		if ((local.pos + Len(arguments.phrase) + arguments.radius) > Len(arguments.text)) {
			local.endPos = Len(arguments.text);
			local.truncateEnd = "";
		} else {
			local.endPos = local.pos + arguments.radius;
			local.truncateEnd = arguments.excerptString;
		}

		local.len = (local.endPos + Len(arguments.phrase)) - local.startPos;
		local.mid = Mid(arguments.text, local.startPos, local.len);
		local.rv = local.truncateStart & local.mid & local.truncateEnd;
		return local.rv;
	}

	// ======================================================================
	// DATETIME FUNCTIONS
	// ======================================================================

	/**
	 * Internal function.
	 */
	public string function $timestamp(string timeStampMode = application.wheels.timeStampMode) {
		switch (arguments.timeStampMode) {
			case "utc":
				local.rv = DateConvert("local2Utc", Now());
				break;
			case "local":
				local.rv = Now();
				break;
			case "epoch":
				local.rv = Now().getTime();
				break;
			default:
				Throw(type = "Wheels.InvalidTimeStampMode", message = "Timestamp mode #arguments.timeStampMode# is invalid");
		}

		// Ensure adapterName is set (may not be if no model has been called yet)
		if (!StructKeyExists(application[$appKey()], "adapterName")) {
			local.dbType = $getDBType();
			$set(adapterName = "#local.dbType#Model");
		}

		// SQLite stores datetimes as TEXT. Format as a clean ISO-8601 string
		// (no surrounding quotes — those are SQL-literal syntax, not data) so
		// the value lands in the TEXT column verbatim and round-trips through
		// IsDate/DateFormat without quote-stripping.
		if ($get("adapterName") == "SQLiteModel") {
			if (IsDate(local.rv)) {
				local.rv = DateFormat(local.rv, "yyyy-mm-dd") & " " & TimeFormat(local.rv, "HH:mm:ss");
			}
		}

		return local.rv;
	}

	/**
	 * Pass in two dates to this method, and it will return a string describing the difference between them.
	 *
	 * [section: Global Helpers]
	 * [category: Date Functions]
	 *
	 * @fromTime Date to compare from.
	 * @toTime Date to compare to.
	 * @includeSeconds Whether or not to include the number of seconds in the returned string.
	 */
	public string function distanceOfTimeInWords(required date fromTime, required date toTime, boolean includeSeconds) {
		$args(name = "distanceOfTimeInWords", args = arguments);
		local.minuteDiff = DateDiff("n", arguments.fromTime, arguments.toTime);
		local.secondDiff = DateDiff("s", arguments.fromTime, arguments.toTime);
		local.hours = 0;
		local.days = 0;
		local.rv = "";
		if (local.minuteDiff <= 1) {
			if (local.secondDiff < 60) {
				local.rv = "less than a minute";
			} else {
				local.rv = "1 minute";
			}
			if (arguments.includeSeconds) {
				if (local.secondDiff < 5) {
					local.rv = "less than 5 seconds";
				} else if (local.secondDiff < 10) {
					local.rv = "less than 10 seconds";
				} else if (local.secondDiff < 20) {
					local.rv = "less than 20 seconds";
				} else if (local.secondDiff < 40) {
					local.rv = "half a minute";
				}
			}
		} else if (local.minuteDiff < 45) {
			local.rv = local.minuteDiff & " minutes";
		} else if (local.minuteDiff < 90) {
			local.rv = "about 1 hour";
		} else if (local.minuteDiff < 1440) {
			local.hours = Ceiling(local.minuteDiff / 60);
			local.rv = "about " & local.hours & " hours";
		} else if (local.minuteDiff < 2880) {
			local.rv = "1 day";
		} else if (local.minuteDiff < 43200) {
			local.days = Int(local.minuteDiff / 1440);
			local.rv = local.days & " days";
		} else if (local.minuteDiff < 86400) {
			local.rv = "about 1 month";
		} else if (local.minuteDiff < 525600) {
			local.months = Int(local.minuteDiff / 43200);
			local.rv = local.months & " months";
		} else if (local.minuteDiff < 657000) {
			local.rv = "about 1 year";
		} else if (local.minuteDiff < 919800) {
			local.rv = "over 1 year";
		} else if (local.minuteDiff < 1051200) {
			local.rv = "almost 2 years";
		} else if (local.minuteDiff >= 1051200) {
			local.years = Int(local.minuteDiff / 525600);
			local.rv = "over " & local.years & " years";
		}
		return local.rv;
	}

	/**
	 * Returns a string describing the approximate time difference between the date passed in and the current date.
	 *
	 * [section: Global Helpers]
	 * [category: Date Functions]
	 *
	 * @fromTime Date to compare from.
	 * @includeSeconds Whether or not to include the number of seconds in the returned string.
	 * @toTime Date to compare to.
	 */
	public any function timeAgoInWords(required date fromTime, boolean includeSeconds, date toTime = Now()) {
		$args(name = "timeAgoInWords", args = arguments);
		return distanceOfTimeInWords(argumentCollection = arguments);
	}

	/**
	 * Returns a string describing the approximate time difference between the current date and the date passed in.
	 *
	 * [section: Global Helpers]
	 * [category: Date Functions]
	 *
	 * @toTime Date to compare to.
	 * @includeSeconds Whether or not to include the number of seconds in the returned string.
	 * @fromTime Date to compare from.
	 */
	public string function timeUntilInWords(required date toTime, boolean includeSeconds, date fromTime = Now()) {
		$args(name = "timeUntilInWords", args = arguments);
		return distanceOfTimeInWords(argumentCollection = arguments);
	}

	// ======================================================================
	// REQUEST FUNCTIONS
	// ======================================================================

	/**
	 * Internal function.
	 */
	public void function $initializeRequestScope() {
		if (!StructKeyExists(request, "wheels")) {
			request.wheels = {};
			request.wheels.params = {};
			request.wheels.cache = {};
			request.wheels.urlForCache = {};
			request.wheels.tickCountId = GetTickCount();

			// Copy HTTP request data (contains content, headers, method and protocol).
			// This makes internal testing easier since we can overwrite it temporarily from the test suite.
			request.wheels.httpRequestData = GetHTTPRequestData();

			// Create a structure to track the transaction status for all adapters.
			request.wheels.transactions = {};
		}
	}

	/**
	 * Get the status code (e.g. 200, 404 etc) of the response we're about to send.
	 */
	public string function $statusCode() {
		if ($hasEngineAdapter()) {
			return $engineAdapter().getStatusCode();
		}
		// Fallback when adapter not yet initialized (e.g. error during startup)
		if (StructKeyExists(server, "lucee") || StructKeyExists(server, "boxlang")) {
			return GetPageContext().getResponse().getStatus();
		}
		return GetPageContext()
			.getFusionContext()
			.getResponse()
			.getStatus();
	}

	/**
	 * Gets the value of the content type header (blank string if it doesn't exist) of the response we're about to send.
	 */
	public string function $contentType() {
		if ($hasEngineAdapter()) {
			return $engineAdapter().getContentType();
		}
		// Fallback when adapter not yet initialized
		local.rv = "";
		if (StructKeyExists(server, "lucee")) {
			local.response = GetPageContext().getResponse();
		} else if (StructKeyExists(server, "boxlang")) {
			local.response = GetPageContext();
		} else {
			local.response = GetPageContext().getFusionContext().getResponse();
		}
		try {
			if (StructKeyExists(server, "boxlang")) {
				local.header = local.response.getRequest().getHeader("Content-Type");
			} else {
				local.header = local.response.containsHeader("Content-Type") ? local.response.getHeader("Content-Type") : Javacast(
					"null",
					""
				);
			}
			if (!IsNull(local.header)) {
				local.rv = local.header;
			}
		} catch (any e) {
		}
		return local.rv;
	}

	/**
	 * This copies all the variables Wheels needs from the CGI scope to the request scope.
	 */
	public struct function $cgiScope(
		string keys = "request_method,http_x_requested_with,http_referer,server_name,path_info,script_name,query_string,remote_addr,server_port,server_port_secure,server_protocol,http_host,http_accept,content_type,http_x_rewrite_url,http_x_original_url,request_uri,redirect_url,http_x_forwarded_for,http_x_forwarded_proto",
		struct scope = cgi
	) {
		local.rv = {};
		local.keyArray = ListToArray(arguments.keys);
		local.iEnd = ArrayLen(local.keyArray);
		for (local.i = 1; local.i <= local.iEnd; local.i++) {
			local.item = local.keyArray[local.i];
			local.rv[local.item] = arguments.scope[local.item];
		}

		// fix path_info if it contains any characters that are not ascii (see issue 138)
		if (StructKeyExists(arguments.scope, "unencoded_url") && Len(arguments.scope.unencoded_url)) {
			local.requestUrl = UrlDecode(arguments.scope.unencoded_url);
		} else if (IsSimpleValue(GetPageContext().getRequest().getRequestURL())) {
			// remove protocol, domain, port etc from the url
			local.requestUrl = "/" & ListDeleteAt(
				ListDeleteAt(UrlDecode(GetPageContext().getRequest().getRequestURL()), 1, "/"),
				1,
				"/"
			);
		}
		if (StructKeyExists(local, "requestUrl") && ReFind("[^\x00-\x80]", local.requestUrl)) {
			// strip out the script_name and query_string leaving us with only the part of the string that should go in path_info
			local.rv.path_info = Replace(
				Replace(local.requestUrl, arguments.scope.script_name, ""),
				"?" & UrlDecode(arguments.scope.query_string),
				""
			);
		}

		// fixes IIS issue that returns a blank cgi.path_info
		if (!Len(local.rv.path_info) && Right(local.rv.script_name, 10) == "/index.cfm") {
			if (Len(local.rv.http_x_rewrite_url)) {
				// IIS6 1/ IIRF (Ionics Isapi Rewrite Filter)
				local.rv.path_info = ListFirst(local.rv.http_x_rewrite_url, "?");
			} else if (Len(local.rv.http_x_original_url)) {
				// IIS7 rewrite default
				local.rv.path_info = ListFirst(local.rv.http_x_original_url, "?");
			} else if (Len(local.rv.request_uri)) {
				// Apache default
				local.rv.path_info = ListFirst(local.rv.request_uri, "?");
			} else if (Len(local.rv.redirect_url)) {
				// Apache fallback
				local.rv.path_info = ListFirst(local.rv.redirect_url, "?");
			}

			// finally lets remove the index.cfm because some of the custom cgi variables don't bring it back
			// like this it means at the root we are working with / instead of /index.cfm
			if (Len(local.rv.path_info) >= 10 && Right(local.rv.path_info, 10) == "/index.cfm") {
				// this will remove the index.cfm and the trailing slash
				local.rv.path_info = Replace(local.rv.path_info, "/index.cfm", "");
				if (!Len(local.rv.path_info)) {
					// add back the forward slash if path_info was "/index.cfm"
					local.rv.path_info = "/";
				}
			}
		}

		// some web servers incorrectly place index.cfm in the path_info but since that should never be there we can safely remove it
		if (Find("index.cfm/", local.rv.path_info)) {
			Replace(local.rv.path_info, "index.cfm/", "");
		}
		return local.rv;
	}

	/**
	 * Internal function. Returns whether the application has opted into trusting `X-Forwarded-*`
	 * headers via `set(trustProxyHeaders=true)`. Guarded so it is safe to call on a cold start
	 * before `application.wheels` exists (resolves to `false`, i.e. do not trust).
	 */
	public boolean function $trustProxyHeaders() {
		return StructKeyExists(application, "wheels")
		&& StructKeyExists(application.wheels, "trustProxyHeaders")
		&& IsBoolean(application.wheels.trustProxyHeaders)
		&& application.wheels.trustProxyHeaders;
	}

	/**
	 * Internal function. Resolves the trusted client IP for security decisions.
	 * Returns `REMOTE_ADDR` (the socket address) unless `trustProxyHeaders` is enabled and
	 * `X-Forwarded-For` is non-empty, in which case the rightmost hop is used — that is the entry
	 * appended by the trusted proxy nearest the app; earlier entries are client-supplied and
	 * spoofable. For this to be safe the proxy must overwrite — never append to — the incoming
	 * header.
	 */
	public string function $trustedClientIp(string remoteAddr, string forwardedFor) {
		if (!StructKeyExists(arguments, "remoteAddr")) {
			arguments.remoteAddr = cgi.remote_addr;
		}
		if (!StructKeyExists(arguments, "forwardedFor")) {
			arguments.forwardedFor = cgi.http_x_forwarded_for;
		}
		local.rv = Trim(arguments.remoteAddr);
		if ($trustProxyHeaders() && Len(Trim(arguments.forwardedFor))) {
			local.rv = Trim(ListLast(arguments.forwardedFor));
		}
		return local.rv;
	}

	/**
	 * Internal function. Returns whether the current client is exempt from maintenance mode.
	 * The exception list comes from config only (`set(ipExceptions="...")`). A list containing
	 * letters is matched against the user agent (legacy behavior preserved verbatim); otherwise
	 * it is matched against the trusted client IP.
	 */
	public boolean function $maintenanceModeExempt(
		required string exceptions,
		required string userAgent,
		required string clientIp
	) {
		if (!Len(arguments.exceptions)) {
			return false;
		}
		if (ReFindNoCase("[a-z]", arguments.exceptions)) {
			return ListFindNoCase(arguments.exceptions, arguments.userAgent) > 0;
		}
		return ListFind(arguments.exceptions, arguments.clientIp) > 0;
	}

	/**
	 * Internal function. Derives `webPath`, `rootPath`, `rootcomponentPath`,
	 * and `wheelsComponentPath` from either an explicit URL `subpath`
	 * (issue #2968 — subfolder installs where `cgi.script_name` does not
	 * reflect the public mount) or, when no subpath is given, the existing
	 * `cgi.script_name` derivation. Returning a struct keeps the helper
	 * pure so it can be unit-tested in isolation.
	 */
	public struct function $resolveFrameworkPaths(required string scriptName, string subpath = "") {
		local.rv = {};
		local.normalized = Trim(arguments.subpath);
		if (Len(local.normalized) && Left(local.normalized, 1) != "/") {
			local.normalized = "/" & local.normalized;
		}
		// Strip trailing slash(es) without falling through to Left(str, 0),
		// which crashes Lucee 7 (see CLAUDE.md § "Cross-Engine Invariants").
		while (Len(local.normalized) > 1 && Right(local.normalized, 1) == "/") {
			local.normalized = Left(local.normalized, Len(local.normalized) - 1);
		}
		if (Len(local.normalized)) {
			local.rv.webPath = local.normalized == "/" ? "/" : local.normalized & "/";
		} else {
			local.rv.webPath = Replace(
				arguments.scriptName,
				Reverse(SpanExcluding(Reverse(arguments.scriptName), "/")),
				""
			);
		}
		local.rv.rootPath = "/" & ListChangeDelims(local.rv.webPath, "/", "/");
		local.rv.rootcomponentPath = ListChangeDelims(local.rv.webPath, ".", "/");
		local.rv.wheelsComponentPath = ListAppend(local.rv.rootcomponentPath, "wheels", ".");
		return local.rv;
	}

	/**
	 * Internal function.
	 */
	public void function $abortInvalidRequest() {
		local.applicationPath = Replace(GetCurrentTemplatePath(), "\", "/", "all");
		local.callingPath = Replace(GetBaseTemplatePath(), "\", "/", "all");
		if (
			!(GetFileFromPath(local.callingPath) == "runner.cfm")
			&&
			ListLen(local.callingPath, "/") > ListLen(local.applicationPath, "/")
		) {
			if (StructKeyExists(application, "wheels")) {
				if (StructKeyExists(application.wheels, "showErrorInformation") && !application.wheels.showErrorInformation) {
					$header(statusCode = 404);
				}
				if (StructKeyExists(application.wheels, "eventPath")) {
					$includeAndOutput(template = "#application.wheels.eventPath#/onmissingtemplate.cfm");
				}
			}
			$header(statusCode = 404);
			abort;
		}
	}

	/**
	 * Throw a developer friendly Wheels error if set (typically in development mode).
	 * Otherwise show the 404 page for end users (typically in production mode).
	 */
	public void function $throwErrorOrShow404Page(required string type, required string message, string extendedInfo = "") {
		$header(statusCode = 404);
		if ($get("showErrorInformation")) {
			Throw(type = arguments.type, message = arguments.message, extendedInfo = arguments.extendedInfo);
		} else {
			local.template = $get("eventPath") & "/onmissingtemplate.cfm";
			$includeAndOutput(template = local.template);
			abort;
		}
	}

	/**
	 * Returns the request timeout value in seconds.
	 * Must be safe to call during onError before application.wheels is initialized.
	 */
	public numeric function $getRequestTimeout() {
		if ($hasEngineAdapter()) {
			return $engineAdapter().getRequestTimeout();
		}
		// Fallback when adapter not yet initialized (e.g. error during startup)
		if (StructKeyExists(server, "boxlang")) {
			return 10000;
		} else if (StructKeyExists(server, "lucee")) {
			return (GetPageContext().getRequestTimeout() / 1000);
		} else {
			return CreateObject("java", "coldfusion.runtime.RequestMonitor").GetRequestTimeout();
		}
	}

	/**
	 * Returns the engine adapter instance for centralized cross-engine behavior.
	 * Checks both application.wheels (post-init) and application.$wheels (during init).
	 */
	public any function $engineAdapter() {
		if (
			StructKeyExists(application, "wheels") && IsStruct(application.wheels) && StructKeyExists(
				application.wheels,
				"engineAdapter"
			)
		) {
			return application.wheels.engineAdapter;
		}
		if (
			StructKeyExists(application, "$wheels") && IsStruct(application.$wheels) && StructKeyExists(
				application.$wheels,
				"engineAdapter"
			)
		) {
			return application.$wheels.engineAdapter;
		}
		Throw(type = "Wheels.EngineAdapterNotInitialized", message = "Engine adapter has not been initialized yet.");
	}

	/**
	 * Returns true if the engine adapter is available in application scope.
	 * Used by functions that may be called before onApplicationStart completes.
	 */
	public boolean function $hasEngineAdapter() {
		return (
			StructKeyExists(application, "wheels") && IsStruct(application.wheels) && StructKeyExists(
				application.wheels,
				"engineAdapter"
			)
		)
		|| (
			StructKeyExists(application, "$wheels") && IsStruct(application.$wheels) && StructKeyExists(
				application.$wheels,
				"engineAdapter"
			)
		);
	}

	// ======================================================================
	// PARAMS FUNCTIONS
	// ======================================================================

	/**
	 * Internal function.
	 */
	public any function $cleanInlist(required string where) {
		local.rv = arguments.where;
		local.regex = "IN\s?\(.*?,?\s?.*?\)";
		local.in = ReFind(local.regex, local.rv, 1, true);
		while (local.in.len[1]) {
			local.str = Mid(local.rv, local.in.pos[1], local.in.len[1]);
			local.rv = RemoveChars(local.rv, local.in.pos[1], local.in.len[1]);
			local.cleaned = $listClean(local.str);
			local.rv = Insert(local.cleaned, local.rv, local.in.pos[1] - 1);
			local.in = ReFind(local.regex, local.rv, local.in.pos[1] + Len(local.cleaned), true);
		}
		return local.rv;
	}

	/**
	 * Removes whitespace between list elements.
	 * Optional argument to return the list as an array.
	 */
	public any function $listClean(required string list, string delim = ",", string returnAs = "string") {
		local.rv = ListToArray(arguments.list, arguments.delim);
		local.iEnd = ArrayLen(local.rv);
		for (local.i = 1; local.i <= local.iEnd; local.i++) {
			local.rv[local.i] = Trim(local.rv[local.i]);
		}
		if (arguments.returnAs != "array") {
			local.rv = ArrayToList(local.rv, arguments.delim);
		}
		return local.rv;
	}

	/**
	 * Converts a comma delimted list to a struct
	 */
	public struct function $listToStruct(required string list, string value = 1) {
		local.rv = {};
		local.cleanList = $listClean(list = arguments.list, returnAs = "array");
		for (local.key in local.cleanList) {
			local.rv[local.key] = arguments.value;
		}
		return local.rv;
	}

	/**
	 * Internal function. Wheels's canonical plural-or-singular argument alias
	 * helper. If `args.<second>` is set, copy it to `args.<first>` and delete
	 * the original — so the function body can read `args.<first>` uniformly
	 * regardless of which name the caller used. With `required=true`, throws
	 * `Wheels.IncorrectArguments` when neither name is provided.
	 *
	 * Canonical examples:
	 *   - `combine = "columnNames,columnName"` — migrator column helpers in
	 *     vendor/wheels/migrator/TableDefinition.cfc
	 *   - `combine = "properties,property"` — model validations in
	 *     vendor/wheels/model/validations.cfc
	 *   - `combine = "formats,format"` — controller provides() in
	 *     vendor/wheels/controller/provides.cfc
	 *   - `combine = "referenceNames,columnNames"` — t.references() per #2781
	 *
	 * When adding a new helper that takes a list-or-single argument, follow
	 * this pattern: declare the plural form on the signature (NOT required),
	 * then call $combineArguments(required=true) at the top of the body so the
	 * alias works AND the required-ness is enforced at runtime.
	 */
	public void function $combineArguments(
		required struct args,
		required string combine,
		required boolean required = false,
		string extendedInfo = ""
	) {
		local.first = ListGetAt(arguments.combine, 1);
		local.second = ListGetAt(arguments.combine, 2);
		if (StructKeyExists(arguments.args, local.second)) {
			arguments.args[local.first] = arguments.args[local.second];
			StructDelete(arguments.args, local.second);
		}
		if (arguments.required && application.wheels.showErrorInformation) {
			if (!StructKeyExists(arguments.args, local.first) || !Len(arguments.args[local.first])) {
				Throw(
					type = "Wheels.IncorrectArguments",
					message = "The `#local.second#` or `#local.first#` argument is required but was not passed in.",
					extendedInfo = "#arguments.extendedInfo#"
				);
			}
		}
	}


	/**
	 * Check to see if all keys in the list exist for the structure and have length.
	 */
	public boolean function $structKeysExist(required struct struct, string keys = "") {
		local.rv = true;
		local.keyArray = ListToArray(arguments.keys);
		local.iEnd = ArrayLen(local.keyArray);
		for (local.i = 1; local.i <= local.iEnd; local.i++) {
			local.key = local.keyArray[local.i];
			if (
				!StructKeyExists(arguments.struct, local.key)
				|| (
					IsSimpleValue(arguments.struct[local.key])
					&& !Len(arguments.struct[local.key])
				)
			) {
				local.rv = false;
				break;
			}
		}
		return local.rv;
	}

	/**
	 * Creates a struct of the named arguments passed in to a function (i.e. the ones not explicitly defined in the arguments list).
	 *
	 * @defined List of already defined arguments that should not be added.
	 */
	public struct function $namedArguments(required string $defined) {
		local.rv = {};
		for (local.key in arguments) {
			if (!ListFindNoCase(arguments.$defined, local.key) && Left(local.key, 1) != "$") {
				local.rv[local.key] = arguments[local.key];
			}
		}
		return local.rv;
	}

	/**
	 * Internal function.
	 */
	public struct function $dollarify(required struct input, required string on) {
		for (local.key in arguments.input) {
			if (ListFindNoCase(arguments.on, local.key)) {
				arguments.input["$" & local.key] = arguments.input[local.key];
				StructDelete(arguments.input, local.key);
			}
		}
		return arguments.input;
	}

	/**
	 * Internal function.
	 */
	public void function $args(
		required struct args,
		required string name,
		string reserved = "",
		string combine = "",
		string required = ""
	) {
		if (Len(arguments.combine)) {
			local.combineKeysArray = ListToArray(arguments.combine);
			local.iEnd = ArrayLen(local.combineKeysArray);
			for (local.i = 1; local.i <= local.iEnd; local.i++) {
				local.item = local.combineKeysArray[local.i];
				local.first = ListGetAt(local.item, 1, "/");
				local.second = ListGetAt(local.item, 2, "/");
				local.required = false;
				if (ListLen(local.item, "/") > 2 || ListFindNoCase(local.first, arguments.required)) {
					local.required = true;
				}
				$combineArguments(args = arguments.args, combine = "#local.first#,#local.second#", required = local.required);
			}
		}
		if (application.wheels.showErrorInformation) {
			if (ListLen(arguments.reserved)) {
				local.iEnd = ListLen(arguments.reserved);
				for (local.i = 1; local.i <= local.iEnd; local.i++) {
					local.item = ListGetAt(arguments.reserved, local.i);
					if (StructKeyExists(arguments.args, local.item)) {
						Throw(
							type = "Wheels.IncorrectArguments",
							message = "The `#local.item#` argument cannot be passed in since it will be set automatically by Wheels."
						);
					}
				}
			}
		}
		if (StructKeyExists(application.wheels.functions, arguments.name)) {
			$engineAdapter().structAppendDefaults(arguments.args, application.wheels.functions[arguments.name]);
		}

		// make sure that the arguments marked as required exist
		if (Len(arguments.required)) {
			local.requiredKeysArray = ListToArray(arguments.required);
			local.iEnd = ArrayLen(local.requiredKeysArray);
			for (local.i = 1; local.i <= local.iEnd; local.i++) {
				local.arg = local.requiredKeysArray[local.i];
				if (!StructKeyExists(arguments.args, local.arg)) {
					Throw(
						type = "Wheels.IncorrectArguments",
						message = "The `#local.arg#` argument is required but not passed in."
					);
				}
			}
		}
	}

	// ======================================================================
	// MISC FUNCTIONS
	// ======================================================================

	/**
	 * Call CFML's canonicalize() function but set to blank string if the result is null (happens on Lucee 5).
	 */
	public string function $canonicalize(required string input) {
		try {
			local.rv = Canonicalize(arguments.input, false, false);
			if (IsNull(local.rv)) {
				local.rv = "";
			}
		} catch (any e) {
			// Lucee's Canonicalize() delegates to Java's URLDecoder, which throws
			// IllegalArgumentException for inputs containing malformed percent-encoded
			// sequences (e.g. %% or a lone % not followed by two hex digits).
			// Fall back to the raw input; it will still be HTML-encoded by the caller.
			local.rv = arguments.input;
		}
		return local.rv;
	}

	/**
	 * Internal function.
	 * Disambiguates a D1/D2/YYYY slash date: a component greater than 12 cannot
	 * be a month so the format is unambiguous; otherwise the engine adapter's
	 * locale preference decides (MM/DD/YYYY on Lucee / Adobe, DD/MM/YYYY on
	 * BoxLang). All slash-date parsing should funnel through this helper.
	 */
	public date function $parseSlashDate(required numeric d1, required numeric d2, required numeric year) {
		if (arguments.d1 > 12) {
			// the first component cannot be a month so it must be the day (DD/MM/YYYY)
			return CreateDate(arguments.year, arguments.d2, arguments.d1);
		} else if (arguments.d2 > 12) {
			// the second component cannot be a month so it must be the day (MM/DD/YYYY)
			return CreateDate(arguments.year, arguments.d1, arguments.d2);
		} else {
			return $engineAdapter().parseAmbiguousSlashDate(arguments.d1, arguments.d2, arguments.year);
		}
	}

	/**
	 * Internal function.
	 */
	public string function $convertToString(required any value, string type = "") {
		// Normalize inputs
		local.val = arguments.value;
		local.detectedType = arguments.type;

		// Coerce Oracle JDBC objects (TIMESTAMP, DATE) to CFML datetime values.
		if (IsObject(local.val)) {
			local.coerced = $engineAdapter().coerceOracleObject(local.val);
			if (!IsObject(local.coerced) || local.coerced.hashCode() != local.val.hashCode()) {
				local.val = local.coerced;
				if (IsDate(local.val)) {
					local.detectedType = "datetime";
				} else {
					local.detectedType = "string";
				}
			}
		}

		// If no explicit type passed, try to detect a sensible one
		if (!Len(detectedType)) {
			if (IsArray(val)) {
				detectedType = "array";
			} else if (IsStruct(val)) {
				detectedType = "struct";
			} else if (IsBinary(val)) {
				detectedType = "binary";
			} else if (IsNumeric(val)) {
				detectedType = "integer";
			} else if (IsDate(val)) {
				detectedType = "datetime";
			} else {
				detectedType = "string";
			}
		}

		// --- EARLY DATE/TIME PROMOTION ---
		// If the caller provided a non-datetime type (eg "string") but the value looks like a date/time,
		// promote it to datetime so the switch branch will canonicalize properly.
		if (
			detectedType NEQ "datetime"
			AND IsSimpleValue(val)
			AND Len(Trim(val))
		) {
			local.s = Trim(val);

			// Match patterns loosely so they work for plain dates too
			local.patternAMPM = '^\d{1,2}/\d{1,2}/\d{4}(\s+\d{1,2}:\d{2}(\s*(AM|PM))?)?$';
			local.patternISO = '^\d{4}-\d{2}-\d{2}([ T]\d{2}:\d{2}(:\d{2})?)?$';
			local.patternSlash = '^\s*\d{1,2}/\d{1,2}/\d{4}\s*$';


			// Day name or other verbose formats are ignored to avoid false positives
			if (
				ReFindNoCase(local.patternAMPM, local.s) OR ReFindNoCase(local.patternISO, local.s) OR ReFindNoCase(
					local.patternSlash,
					local.s
				)
			) {
				// Promote to datetime so the datetime branch will run below
				detectedType = "datetime";
			}
		}

		// Pre-process date strings with AM/PM that may be parsed differently per engine
		if (
			$engineAdapter().isBoxLang() && IsSimpleValue(arguments.value) && ReFindNoCase(
				"^\d{1,2}/\d{1,2}/\d{4} \d{1,2}:\d{2} (AM|PM)$",
				arguments.value
			)
		) {
			// Manually parse the slash date to avoid engine-specific interpretation,
			// disambiguating day/month through $parseSlashDate()
			local.parts = ListToArray(arguments.value, " ");
			local.datePart = local.parts[1];
			local.timePart = local.parts[2];
			local.amPm = local.parts[3];

			local.dateComponents = ListToArray(local.datePart, "/");
			local.timeComponents = ListToArray(local.timePart, ":");

			local.parsedDate = $parseSlashDate(
				d1 = Val(local.dateComponents[1]),
				d2 = Val(local.dateComponents[2]),
				year = Val(local.dateComponents[3])
			);
			local.hour = Val(local.timeComponents[1]);
			local.minute = Val(local.timeComponents[2]);

			if (local.amPm == "PM" && local.hour != 12) {
				local.hour += 12;
			} else if (local.amPm == "AM" && local.hour == 12) {
				local.hour = 0;
			}
			val = CreateDateTime(
				Year(local.parsedDate),
				Month(local.parsedDate),
				Day(local.parsedDate),
				local.hour,
				local.minute,
				0
			);
			detectedType = "datetime";
		}

		// --- SWITCH ON (possibly promoted) TYPE ---
		switch (detectedType) {
			case "array":
				return ArrayToList(val);
			case "struct":
				local.kList = ListSort(StructKeyList(val), "textnocase", "asc");
				local.out = "";
				for (local.k in ListToArray(local.kList)) {
					local.out = ListAppend(local.out, local.k & "=" & val[local.k]);
				}
				return local.out;
			case "binary":
				return ToString(val);
			case "float":
			case "integer":
				if (!Len(val)) {
					return "";
				}
				if (val == "true") {
					return "1";
				}
				return Val(val);
			case "boolean":
				if (Len(val)) {
					return (val IS true) ? "true" : "false";
				}
				return "";
			case "datetime":
				// If it's already a date object, canonicalize
				if (IsDate(val)) {
					return DateFormat(val, "yyyy-mm-dd") & " " & TimeFormat(val, "HH:mm:ss");
				}

				// If it is a string that looks like a date, try parsing
				if (IsSimpleValue(val)) {
					local.s2 = Trim(val);
					// Try ParseDateTime (which handles many formats)
					try {
						local.dt = ParseDateTime(local.s2);
						if (IsDate(local.dt)) {
							return DateFormat(local.dt, "yyyy-mm-dd") & " " & TimeFormat(local.dt, "HH:mm:ss");
						}
					} catch (any e) {
						// fallback parsing attempts for common formats

						// 1) ISO YYYY-MM-DD[ hh[:mm[:ss]]]
						// Single-backslash escapes: in CFML "\\d" is a literal
						// backslash + d in the compiled regex, which never matches a
						// digit — the branch was dead. Mirrors the already-fixed
						// slash-format branch below (#2933 carry-forward, #2977).
						if (ReFind("(?i)^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{1,2}):(\d{2})(?::(\d{2}))?)?$", local.s2)) {
							local.parts = ReReplace(local.s2, "^(\d{4})-(\d{2})-(\d{2}).*$", "\1-\2-\3", "all");
							local.timePart = ReReplace(local.s2, ".*[ T](\d{1,2}:\d{2}(?::\d{2})?).*$", "\1", "all");
							if (Len(local.timePart) AND local.timePart NEQ local.s2) {
								// has time
								local.dt = ParseDateTime(local.parts & " " & local.timePart);
								if (IsDate(local.dt)) {
									return DateFormat(local.dt, "yyyy-mm-dd") & " " & TimeFormat(local.dt, "HH:mm:ss");
								}
							} else {
								// date only
								local.dt = CreateDate(
									Val(ListGetAt(local.parts, 1, "-")),
									Val(ListGetAt(local.parts, 2, "-")),
									Val(ListGetAt(local.parts, 3, "-"))
								);
								return DateFormat(local.dt, "yyyy-mm-dd") & " 00:00:00";
							}
						}

						// 2) Slash format DD/MM/YYYY or MM/DD/YYYY — disambiguated by $parseSlashDate()
						if (ReFind("^\d{1,2}/\d{1,2}/\d{4}", local.s2)) {
							local.comps = ListToArray(local.s2, "/");
							local.dt = $parseSlashDate(
								d1 = Val(local.comps[1]),
								d2 = Val(local.comps[2]),
								year = Val(local.comps[3])
							);
							// if time exists in same string, try to parse it using ParseDateTime
							if (ReFind("\d{1,2}:\d{2}", local.s2)) {
								try {
									local.dt2 = ParseDateTime(local.s2);
									if (IsDate(local.dt2)) {
										return DateFormat(local.dt2, "yyyy-mm-dd") & " " & TimeFormat(local.dt2, "HH:mm:ss");
									}
								} catch (any e2) {
									// fallback to midnight
									return DateFormat(local.dt, "yyyy-mm-dd") & " 00:00:00";
								}
							}
							return DateFormat(local.dt, "yyyy-mm-dd") & " 00:00:00";
						}
					}
				}
				// If we reach here, parsing failed — return original string to allow comparison
				return val;
			default:
				// Default: return raw value as string (no conversion)
				return val;
		}
	}

	/**
	 * Internal function.
	 */
	public xml function $toXml(required any data) {
		// only instantiate the toXml object once per request
		if (!StructKeyExists(request.wheels, "toXml")) {
			request.wheels.toXml = $createObjectFromRoot(
				path = "#application.wheels.wheelsComponentPath#.vendor.toXml",
				fileName = "toXML",
				method = "init"
			);
		}

		return request.wheels.toXml.toXml(arguments.data);
	}

	/**
	 * Obfuscates a value. Typically used for hiding primary key values when passed along in the URL.
	 *
	 * [section: Global Helpers]
	 * [category: Miscellaneous Functions]
	 *
	 * @param The value to obfuscate.
	 */
	public string function obfuscateParam(required any param) {
		local.rv = arguments.param;
		local.param = ArrayToList(ReMatch("[0-9]+", arguments.param), "");
		if (Len(local.param) && local.param > 0 && Left(local.param, 1) != 0) {
			local.iEnd = Len(local.param);
			local.a = (10^local.iEnd) + Reverse(local.param);
			local.b = 0;
			for (local.i = 1; local.i <= local.iEnd; local.i++) {
				local.b += Left(Right(local.param, local.i), 1);
			}
			if (IsValid("integer", local.a)) {
				local.rv = FormatBaseN(local.b + 154, 16) & FormatBaseN(BitXor(local.a, 461), 16);
			}
		}
		return local.rv;
	}

	/**
	 * Deobfuscates a value.
	 *
	 * [section: Global Helpers]
	 * [category: Miscellaneous Functions]
	 *
	 * @param The value to deobfuscate.
	 */
	public string function deobfuscateParam(required string param) {
		if (Val(arguments.param) != arguments.param) {
			try {
				local.checksum = Left(arguments.param, 2);
				local.rv = Right(arguments.param, Len(arguments.param) - 2);
				local.z = BitXor(InputBaseN(local.rv, 16), 461);
				local.rv = "";
				local.iEnd = Len(local.z) - 1;
				for (local.i = 1; local.i <= local.iEnd; local.i++) {
					local.rv &= Left(Right(local.z, local.i), 1);
				}
				local.checkSumTest = 0;
				local.iEnd = Len(local.rv);
				for (local.i = 1; local.i <= local.iEnd; local.i++) {
					local.checkSumTest += Left(Right(local.rv, local.i), 1);
				}
				local.c1 = ToString(FormatBaseN(local.checkSumTest + 154, 10));
				local.c2 = InputBaseN(local.checksum, 16);
				if (local.c1 != local.c2) {
					local.rv = arguments.param;
				}
			} catch (any e) {
				local.rv = arguments.param;
			}
		} else {
			local.rv = arguments.param;
		}
		return local.rv;
	}

	/**
	 * Returns a list of the names of all installed plugins.
	 *
	 * [section: Global Helpers]
	 * [category: Miscellaneous Functions]
	 */
	public string function pluginNames() {
		return StructKeyList(application.wheels.plugins);
	}

	/**
	 * Returns an associated MIME type based on a file extension.
	 *
	 * [section: Global Helpers]
	 * [category: Miscellaneous Functions]
	 *
	 * @extension The extension to get the MIME type for.
	 * @fallback The fallback MIME type to return.
	 */
	public string function mimeTypes(required string extension, string fallback = "application/octet-stream") {
		local.rv = arguments.fallback;
		if (StructKeyExists(application.wheels.mimetypes, arguments.extension)) {
			local.rv = application.wheels.mimetypes[arguments.extension];
		}
		return local.rv;
	}

	/**
	 * Adds a new MIME type to your Wheels application for use with responding to multiple formats.
	 *
	 * [section: Configuration]
	 * [category: Miscellaneous Functions]
	 *
	 * @extension File extension to add.
	 * @mimeType Matching MIME type to associate with the file extension.
	 */
	public void function addFormat(required string extension, required string mimeType) {
		local.appKey = $appKey();
		application[local.appKey].formats[arguments.extension] = arguments.mimeType;
	}

	/**
	 * Internal function.
	 */
	public string function $appKey() {
		local.rv = "wheels";
		if (StructKeyExists(application, "$wheels")) {
			local.rv = "$wheels";
		}
		return local.rv;
	}

	/**
	 * Internal function. Returns the application-cached Plugins instance so the
	 * request-lifecycle call sites (onDIcomplete on controllers, models and the
	 * dispatcher, plus $runOnRequestStart) don't construct a throwaway
	 * wheels.Plugins — and its wheels.Global parent pseudo-constructor — per
	 * request / per materialized model row (issue 2897, Stage 3). Falls back to
	 * a fresh instance during bootstrap windows where the cache has not been
	 * populated yet, or where the application scope is undefined (CLI / test
	 * bootstrap). Sharing one instance is safe because $initializeMixins keeps
	 * its scratch state local-scoped.
	 */
	public any function $pluginObj() {
		if (IsDefined("application")) {
			local.appKey = StructKeyExists(application, "$wheels") ? "$wheels" : "wheels";
			if (StructKeyExists(application, local.appKey) && StructKeyExists(application[local.appKey], "PluginObj")) {
				return application[local.appKey].PluginObj;
			}
		}
		return CreateObject("component", "wheels.Plugins");
	}

	/**
	 * Internal function. Records a deprecation warning through a single shared
	 * policy: the first call for a given feature logs a warning to the standard
	 * wheels log and registers the warning in
	 * application[appKey].deprecationWarnings so running apps can surface it
	 * (debug panel, tooling). Subsequent calls for the same feature are no-ops,
	 * making the helper safe to call from per-request code paths. The dedup
	 * check, registration, and log write run atomically under an exclusive
	 * lock so concurrent first callers (e.g. parallel first requests hitting a
	 * deprecated per-request helper) register and log exactly once. If the
	 * Wheels application struct does not exist yet, the helper is a silent
	 * no-op: with no registry to dedup against, logging would fire on every
	 * call, and all framework callers run after the struct is established.
	 *
	 * @feature Stable identifier for the deprecated feature (e.g. "plugins-directory", "paginationLinks").
	 * @message Human-readable message: what is deprecated, what replaces it, and when it goes away.
	 * @docUrl Optional URL of the migration guide, appended to the logged message.
	 */
	public void function $deprecated(required string feature, required string message, string docUrl = "") {
		try {
			local.appKey = $appKey();
			if (StructKeyExists(application, local.appKey)) {
				// One app-wide lock (rather than per-feature) also serializes the lazy
				// creation of the registry array itself; contention is a non-issue at
				// once-per-feature-per-application frequency.
				lock name="wheels_deprecated_registry" type="exclusive" timeout="5" {
					if (!StructKeyExists(application[local.appKey], "deprecationWarnings")) {
						application[local.appKey].deprecationWarnings = [];
					}
					for (local.existing in application[local.appKey].deprecationWarnings) {
						if (local.existing.feature == arguments.feature) {
							return;
						}
					}
					ArrayAppend(application[local.appKey].deprecationWarnings, {
						feature = arguments.feature,
						message = arguments.message,
						url = arguments.docUrl
					});
					// Log if-and-only-if the registration above just succeeded; the
					// registry is what enforces the warn-once policy for the log too.
					try {
						local.text = "[Wheels] Deprecation: " & arguments.message;
						if (Len(arguments.docUrl)) {
							local.text &= " See: " & arguments.docUrl;
						}
						WriteLog(type = "warning", text = local.text, file = "wheels");
					} catch (any e) {
						// Logging is best-effort; the registry entry above already records the warning.
					}
				}
			}
		} catch (any e) {
			// Best-effort by design (including lock timeouts); never let a
			// deprecation notice break the caller.
		}
	}

	// Returns the running framework version. Delegates to BuildInfo.cfc, which
	// is the authoritative version source. The historical box.json-reading
	// implementation (with monorepo / wheels-base-template fallback chain)
	// was retired when BuildInfo became the source of truth — see the BuildInfo
	// header for migration context. Kept as a thin wrapper because callers
	// upstream of onapplicationstart (e.g. PackageLoader, Plugins) and tests
	// reference $readFrameworkVersion by name.
	public string function $readFrameworkVersion() {
		return new wheels.BuildInfo().version();
	}

	public string function $checkMinimumVersion(required string engine, required string version) {
		local.rv = "";
		local.version = Replace(arguments.version, ".", ",", "all");
		local.major = Val(ListGetAt(local.version, 1));
		local.minor = 0;
		local.patch = 0;
		local.build = 0;
		if (ListLen(local.version) > 1) {
			local.minor = Val(ListGetAt(local.version, 2));
		}
		if (ListLen(local.version) > 2) {
			local.patch = Val(ListGetAt(local.version, 3));
		}
		if (ListLen(local.version) > 3) {
			local.build = Val(ListGetAt(local.version, 4));
		}
		if (arguments.engine == "BoxLang") {
			local.minimumMajor = "1";
			local.minimumMinor = "0";
			local.minimumPatch = "0";
			local.maximumMajor = "1";
			local.maximumMinor = "15";
			local.maximumPatch = "999";

			// Check minimum version
			if (
				local.major < local.minimumMajor
				|| (local.major == local.minimumMajor && local.minor < local.minimumMinor)
				|| (local.major == local.minimumMajor && local.minor == local.minimumMinor && local.patch < local.minimumPatch)
			) {
				local.rv = "The Wheels framework requires BoxLang version #local.minimumMajor#.#local.minimumMinor#.#local.minimumPatch# or higher. You are currently running version #arguments.version#.";
			}

			// Check maximum version (optional - for major version compatibility)
			if (
				local.major > local.maximumMajor
				|| (local.major == local.maximumMajor && local.minor > local.maximumMinor)
				|| (local.major == local.maximumMajor && local.minor == local.maximumMinor && local.patch > local.maximumPatch)
			) {
				local.rv = "The Wheels framework has been tested up to BoxLang version #local.maximumMajor#.#local.maximumMinor#.#local.maximumPatch#. You are currently running version #arguments.version#. Please check for framework updates or compatibility issues.";
			}
		} else if (arguments.engine == "Lucee") {
			local.minimumMajor = "5";
			local.minimumMinor = "3";
			local.minimumPatch = "2";
			local.minimumBuild = "77";
			// per-major-release floor consumed by the `StructKeyExists(local, local.major)`
			// check below (keyed by the running engine's major version number)
			local.5 = {minimumMinor = 2, minimumPatch = 1, minimumBuild = 9};
		} else if (arguments.engine == "Adobe ColdFusion") {
			// Adobe ColdFusion 2018 is the oldest supported Adobe engine
			// (CF 11 / 2016 are end-of-life and no longer supported)
			local.minimumMajor = "2018";
			local.minimumMinor = "0";
			local.minimumPatch = "0";
			local.minimumBuild = "";
		} else if (arguments.engine == "RustCFML") {
			// RustCFML is a pre-1.0, rapidly evolving experimental engine that
			// Wheels supports on a best-effort basis. Accept any version (leave
			// local.rv = "") rather than enforcing a minimum; per-version
			// divergences are tracked via the RustCFMLAdapter capabilities.
			local.rv = "";
		} else {
			local.rv = false;
		}
		if (StructKeyExists(local, "minimumMajor")) {
			if (
				local.major < local.minimumMajor
				|| (local.major == local.minimumMajor && local.minor < local.minimumMinor)
				|| (local.major == local.minimumMajor && local.minor == local.minimumMinor && local.patch < local.minimumPatch)
				|| (
					local.major == local.minimumMajor
					&& local.minor == local.minimumMinor
					&& local.patch == local.minimumPatch
					&& Len(local.minimumBuild)
					&& local.build < local.minimumBuild
				)
			) {
				local.rv = local.minimumMajor & "." & local.minimumMinor & "." & local.minimumPatch;
				if (Len(local.minimumBuild)) {
					local.rv &= "." & local.minimumBuild;
				}
			}
			if (StructKeyExists(local, local.major)) {
				// special requirements for having a specific minor or patch version within a major release exists
				if (
					local.minor < local[local.major].minimumMinor
					|| (local.minor == local[local.major].minimumMinor && local.patch < local[local.major].minimumPatch)
				) {
					local.rv = local.major & "." & local[local.major].minimumMinor & "." & local[local.major].minimumPatch;
				}
			}
		}
		return local.rv;
	}

	/**
	 * Internal function. Normalizes mixin-collision records to a single
	 * shared shape: {target, method, firstProvider, secondProvider,
	 * acknowledged, source}. Plugins.cfc emits legacy-shaped records
	 * ({existingPlugin, overridingPlugin}) while PackageLoader.cfc and the
	 * cross-system merge in $loadPackages emit the shared shape directly;
	 * all of them end up in the same application.wheels.mixinCollisions
	 * array, which /wheels/plugins and the development debug footer consume
	 * unconditionally — a mixed-shape array crashes those surfaces with a
	 * "key doesn't exist" error.
	 */
	public array function $normalizeMixinCollisions(required array collisions) {
		local.rv = [];
		for (local.c in arguments.collisions) {
			ArrayAppend(local.rv, {
				target = local.c.target,
				method = local.c.method,
				firstProvider = StructKeyExists(local.c, "firstProvider") ? local.c.firstProvider : local.c.existingPlugin,
				secondProvider = StructKeyExists(local.c, "secondProvider") ? local.c.secondProvider : local.c.overridingPlugin,
				acknowledged = StructKeyExists(local.c, "acknowledged") ? local.c.acknowledged : false,
				source = StructKeyExists(local.c, "source") ? local.c.source : "plugin"
			});
		}
		return local.rv;
	}

	/**
	 * Internal function.
	 */
	public void function $loadPlugins() {
		local.appKey = $appKey();
		local.pluginPath = application[local.appKey].webPath & application[local.appKey].pluginPath;
		application[local.appKey].PluginObj = $createObjectFromRoot(
			path = "wheels",
			fileName = "Plugins",
			method = "$init",
			pluginPath = local.pluginPath,
			deletePluginDirectories = application[local.appKey].deletePluginDirectories,
			overwritePlugins = application[local.appKey].overwritePlugins,
			loadIncompatiblePlugins = application[local.appKey].loadIncompatiblePlugins,
			wheelsEnvironment = application[local.appKey].environment,
			wheelsVersion = application[local.appKey].version
		);
		application[local.appKey].plugins = application[local.appKey].PluginObj.getPlugins();
		application[local.appKey].pluginMeta = application[local.appKey].PluginObj.getPluginMeta();
		application[local.appKey].incompatiblePlugins = application[local.appKey].PluginObj.getIncompatiblePlugins();
		application[local.appKey].dependantPlugins = application[local.appKey].PluginObj.getDependantPlugins();
		application[local.appKey].versionMismatchPlugins = application[local.appKey].PluginObj.getVersionMismatchPlugins();
		// Plugins.cfc emits legacy-shaped collision records ({existingPlugin,
		// overridingPlugin}); normalize them to the shared shape at the merge
		// point so package- and cross-system records (which already use
		// {firstProvider, secondProvider}) can live in the same array without
		// crashing the consumers (/wheels/plugins and the debug footer).
		application[local.appKey].mixinCollisions = $normalizeMixinCollisions(
			application[local.appKey].PluginObj.getMixinCollisions()
		);
		application[local.appKey].mixins = application[local.appKey].PluginObj.getMixins();
		application[local.appKey].pluginMiddleware = application[local.appKey].PluginObj.getPluginMiddleware();
		// Invoke register(container) on ServiceProviderInterface plugins before activation
		if (IsDefined("application.wheelsdi") && ArrayLen(application[local.appKey].PluginObj.getServiceProviders())) {
			application[local.appKey].PluginObj.$invokeServiceProviderRegister(application.wheelsdi);
			// Boot after all register() calls complete — plugins can now resolve services
			application[local.appKey].PluginObj.$invokeServiceProviderBoot(application[local.appKey]);
		}
		// Invoke onPluginActivate lifecycle hook on all plugins now that everything is in the application scope
		application[local.appKey].PluginObj.$invokeOnPluginActivate();
	}

	/**
	 * Discovers and loads packages from the vendor/ directory via PackageLoader.
	 * Merges package mixins into the existing application mixins struct so they
	 * participate in the standard $initializeMixins injection pipeline.
	 */
	public void function $loadPackages() {
		local.appKey = $appKey();
		local.vendorPath = ExpandPath(application[local.appKey].packagePath);

		application[local.appKey].PackageLoaderObj = $createObjectFromRoot(
			path = "wheels",
			fileName = "PackageLoader",
			method = "init",
			vendorPath = local.vendorPath,
			wheelsVersion = application[local.appKey].version,
			wheelsEnvironment = application[local.appKey].environment
		);

		application[local.appKey].packages = application[local.appKey].PackageLoaderObj.getPackages();
		application[local.appKey].packageMeta = application[local.appKey].PackageLoaderObj.getPackageMeta();
		application[local.appKey].failedPackages = application[local.appKey].PackageLoaderObj.getFailedPackages();

		// Ensure mixinCollisions exists (unset when no plugins loaded before packages)
		if (!StructKeyExists(application[local.appKey], "mixinCollisions")) {
			application[local.appKey].mixinCollisions = [];
		}

		// Carry forward any collisions the PackageLoader detected internally
		for (local.c in application[local.appKey].PackageLoaderObj.getMixinCollisions()) {
			ArrayAppend(application[local.appKey].mixinCollisions, local.c);
		}

		// Merge package mixins into the existing mixins struct (plugins loaded first, packages overlay).
		// Detect cross-system collisions — a package method that shadows a plugin method on the
		// same target — before StructAppend silently overwrites.
		local.pkgMixins = application[local.appKey].PackageLoaderObj.getMixins();
		local.pluginProviders = StructKeyExists(application[local.appKey], "PluginObj")
			? application[local.appKey].PluginObj.getMethodProviders()
			: {};
		local.pkgProviders = application[local.appKey].PackageLoaderObj.getMethodProviders();
		for (local.target in local.pkgMixins) {
			if (!StructKeyExists(application[local.appKey].mixins, local.target)) {
				application[local.appKey].mixins[local.target] = {};
			}
			for (local.methodName in local.pkgMixins[local.target]) {
				if (StructKeyExists(application[local.appKey].mixins[local.target], local.methodName)) {
					// Only treat this as a cross-system collision when the existing entry
					// came from a known plugin. Without an attributable plugin provider
					// the prior entry could be framework-internal or pre-seeded, and a
					// "migrate the plugin" recommendation would be misleading.
					local.pluginAttributable = StructKeyExists(local.pluginProviders, local.target)
						&& StructKeyExists(local.pluginProviders[local.target], local.methodName);
					if (!local.pluginAttributable) {
						continue;
					}
					local.pluginName = local.pluginProviders[local.target][local.methodName];
					local.pkgName = StructKeyExists(local.pkgProviders, local.target)
						&& StructKeyExists(local.pkgProviders[local.target], local.methodName)
						? local.pkgProviders[local.target][local.methodName]
						: "(unknown package)";
					ArrayAppend(application[local.appKey].mixinCollisions, {
						target = local.target,
						method = local.methodName,
						firstProvider = local.pluginName,
						secondProvider = local.pkgName,
						acknowledged = false,
						source = "cross"
					});
					WriteLog(
						type = "warning",
						text = "[Wheels] Cross-system mixin collision: method '#local.methodName#' on target '#local.target#' provided by plugin '#local.pluginName#' is being overwritten by package '#local.pkgName#'. Migrate the plugin to a package or remove the duplicate to resolve."
					);
				}
			}
			StructAppend(application[local.appKey].mixins[local.target], local.pkgMixins[local.target]);
		}

		// Merge package middleware into pluginMiddleware (shared pipeline)
		local.pkgMiddleware = application[local.appKey].PackageLoaderObj.getPackageMiddleware();
		for (local.mw in local.pkgMiddleware) {
			ArrayAppend(application[local.appKey].pluginMiddleware, local.mw);
		}

		// Invoke ServiceProvider register/boot if DI container exists. The
		// gate asks the loader (not just getServiceProviders()) because lazy
		// service-hinted packages aren't instantiated yet at this point —
		// $invokeServiceProviderRegister pulls them into the lifecycle, so a
		// vendor tree containing only lazy service packages still needs the
		// lifecycle invoked.
		if (IsDefined("application.wheelsdi") && application[local.appKey].PackageLoaderObj.$hasServiceProviderWork()) {
			application[local.appKey].PackageLoaderObj.$invokeServiceProviderRegister(application.wheelsdi);
			application[local.appKey].PackageLoaderObj.$invokeServiceProviderBoot(application[local.appKey]);
			// Re-sync the application-scope copy so register()/boot() failure
			// records are visible there too. Adobe CF copies arrays by value on
			// assignment, so the copy taken above (pre-invoke) never receives
			// lifecycle-phase entries on those engines — only Lucee/BoxLang share
			// the reference. Re-assigning is harmless on Lucee/BoxLang (same
			// reference) and required on Adobe (fresh copy including new entries).
			application[local.appKey].failedPackages = application[local.appKey].PackageLoaderObj.getFailedPackages();
		}

		// Surface an aggregate summary when any packages failed to load. Without
		// this, PackageLoader records each failure in variables.failedPackages and
		// emits per-package WriteLog calls — but a developer who hits a downstream
		// "No matching function [BASECOATINCLUDES]" error has no obvious place to
		// look. Logging a single high-visibility WARN to wheels.log + a stronger
		// one to wheels-errors.log gives a clear breadcrumb back to the root cause.
		// Runs after the ServiceProvider lifecycle invoke so register()/boot()
		// failures appear in the same summary as load-phase failures.
		if (ArrayLen(application[local.appKey].failedPackages)) {
			local.failNames = "";
			local.failDetail = "";
			for (local.fp in application[local.appKey].failedPackages) {
				local.failNames = ListAppend(local.failNames, local.fp.name);
				local.failDetail &= "  - " & local.fp.name & ": " & local.fp.error & Chr(10);
			}
			try {
				writeLog(
					file = "wheels",
					type = "warning",
					text = "Wheels: " & ArrayLen(application[local.appKey].failedPackages)
						& " package(s) failed to load: " & local.failNames
						& ". Helpers / services these packages provide will be unavailable —"
						& " calling code typically surfaces this as 'No matching function [...]"
						& "' or 'No service registered with the name [...]'."
						& " Per-package detail in wheels-errors.log."
				);
				writeLog(
					file = "wheels-errors",
					type = "error",
					text = "Wheels: " & ArrayLen(application[local.appKey].failedPackages)
						& " package(s) failed to load:" & Chr(10) & local.failDetail
				);
			} catch (any e) {
				// Logging is best-effort during application start.
			}
		}
	}

	/**
	 * NB: url rewriting files need to be removed from here.
	 */
	public string function $buildReleaseZip(
		string version = application.wheels.version,
		string directory = ExpandPath("/")
	) {
		local.name = "wheels-" & LCase(Replace(arguments.version, " ", "-", "all"));
		local.name = Replace(local.name, "alpha-", "alpha.");
		local.name = Replace(local.name, "beta-", "beta.");
		local.name = Replace(local.name, "rc-", "rc.");
		local.path = arguments.directory & local.name & ".zip";

		// directories & files to add to the zip
		local.include = [
			"/config",
			"/app/controllers",
			"/app/events",
			"/app/lib",
			"/app/migrator",
			"files",
			"/app/global",
			"images",
			"javascripts",
			"miscellaneous",
			"/app/models",
			"/plugins",
			"stylesheets",
			"/tests",
			"/app/views",
			"/vendor/wheels",
			"Application.cfc",
			"../wheels.json",
			"../box.json",
			"index.cfm"
		];

		// directories & files to be removed
		local.exclude = ["/wheels/rocketunit_tests", "/wheels/public/build.cfm", "/wheels/tests"];

		// filter out these bad boys
		local.filter = "*.settings, *.classpath, *.project, *.DS_Store";

		// The change log and license are copied to the wheels directory only for the build.
		// FileCopy(ExpandPath("CHANGELOG.md"), ExpandPath("/wheels/CHANGELOG.md"));
		// FileCopy(ExpandPath("LICENSE"), ExpandPath("/wheels/LICENSE"));

		// Entries starting with "/" or ".." → treat as project-root paths (keep original folder structure)
		// Entries without "/" → treat as webroot (/public) paths
		for (local.i in local.include) {
			if (FileExists(ExpandPath(local.i))) {
				if (Left(local.i, 1) neq "/" && Left(local.i, 2) neq "..") {
					$zip(file = local.path, source = ExpandPath(local.i), prefix = "/public");
				} else {
					$zip(file = local.path, source = ExpandPath(local.i));
				}
			} else if (DirectoryExists(ExpandPath(local.i))) {
				if (Left(local.i, 1) neq "/" && Left(local.i, 2) neq "..") {
					$zip(file = local.path, source = ExpandPath(local.i), prefix = "/public/#local.i#");
				} else {
					$zip(file = local.path, source = ExpandPath(local.i), prefix = local.i);
				}
			} else {
				Throw(
					type = "Wheels.Build",
					message = "#ExpandPath(local.i)# not found",
					detail = "All paths specified in local.include must exist"
				);
			}
		};

		for (local.i in local.exclude) {
			$zip(file = local.path, action = "delete", entrypath = local.i);
		};
		$zip(file = local.path, action = "delete", filter = local.filter, recurse = true);

		// Clean up.
		/* Might not need this because the wheels folder is outside the app now */
		// FileDelete(ExpandPath("/wheels/CHANGELOG.md"));
		// FileDelete(ExpandPath("/wheels/LICENSE"));

		return local.path;
	}

	/**
	 * Generates a 36-character UUID compatible with SQL Server's uniqueidentifier.
	 *
	 * [section: Global Helpers]
	 * [category: UUID Functions]
	 *
	 * @return A valid 36-character UUID string (e.g., 123e4567-e89b-12d3-a456-426614174000)
	 */
	public string function generateUUID() {
		// Use Java UUID generator for a 36-character format
		return CreateObject("java", "java.util.UUID").randomUUID().toString();
	}

	/**
	 * Returns a struct with information about the specified paginated query.
	 * The keys that will be included in the struct are `currentPage`, `totalPages` and `totalRecords`.
	 *
	 * [section: Controller]
	 * [category: Pagination Functions]
	 *
	 * @handle The handle given to the query to return pagination information for.
	 */
	public struct function pagination(string handle = "query") {
		if ($get("showErrorInformation")) {
			if (!StructKeyExists(request.wheels, arguments.handle)) {
				Throw(
					type = "Wheels.QueryHandleNotFound",
					message = "Wheels couldn't find a query with the handle of `#arguments.handle#`.",
					extendedInfo = "Make sure your `findAll` call has the `page` argument specified and matching `handle` argument if specified."
				);
			}
		}
		return request.wheels[arguments.handle];
	}

	/**
	 * Allows you to set a pagination handle for a custom query so you can perform pagination on it in your view with `paginationLinks`.
	 *
	 * [section: Controller]
	 * [category: Pagination Functions]
	 *
	 * @totalRecords Total count of records that should be represented by the paginated links.
	 * @currentPage Page number that should be represented by the data being fetched and the paginated links.
	 * @perPage Number of records that should be represented on each page of data.
	 * @handle Name of handle to reference in `paginationLinks`.
	 */
	public void function setPagination(
		required numeric totalRecords,
		numeric currentPage = 1,
		numeric perPage = 25,
		string handle = "query"
	) {
		// NOTE: this should be documented as a controller function but needs to be placed here because the findAll() method calls it.

		// All numeric values must be integers.
		arguments.totalRecords = Fix(arguments.totalRecords);
		arguments.currentPage = Fix(arguments.currentPage);
		arguments.perPage = Fix(arguments.perPage);

		// The totalRecords argument cannot be negative.
		if (arguments.totalRecords < 0) {
			arguments.totalRecords = 0;
		}

		// Default perPage to 25 if it's less then zero.
		if (arguments.perPage <= 0) {
			arguments.perPage = 25;
		}

		// Calculate the total pages the query will have.
		arguments.totalPages = Ceiling(arguments.totalRecords / arguments.perPage);

		// The currentPage argument shouldn't be less then 1 or greater then the number of pages.
		if (arguments.currentPage >= arguments.totalPages) {
			arguments.currentPage = arguments.totalPages;
		}
		if (arguments.currentPage < 1) {
			arguments.currentPage = 1;
		}

		// As a convenience for cfquery and cfloop when doing oldschool type pagination.
		// Set startrow for cfquery and cfloop.
		arguments.startRow = (arguments.currentPage * arguments.perPage) - arguments.perPage + 1;

		// Set maxrows for cfquery.
		arguments.maxRows = arguments.perPage;

		// Set endrow for cfloop.
		arguments.endRow = (arguments.startRow - 1) + arguments.perPage;

		// The endRow argument shouldn't be greater then the totalRecords or less than startRow.
		if (arguments.endRow >= arguments.totalRecords) {
			arguments.endRow = arguments.totalRecords;
		}
		if (arguments.endRow < arguments.startRow) {
			arguments.endRow = arguments.startRow;
		}

		local.args = Duplicate(arguments);
		StructDelete(local.args, "handle");
		request.wheels[arguments.handle] = local.args;
	}

	/**
	 * Creates a controller and calls an action on it.
	 * Which controller and action that's called is determined by the params passed in.
	 * Returns the result of the request either as a string or in a struct with `body`, `emails`, `files`, `flash`, `redirect`, `status`, and `type`.
	 * Primarily used for testing purposes.
	 *
	 * [section: Controller]
	 * [category: Miscellaneous Functions]
	 *
	 * @params The params struct to use in the request (make sure that at least `controller` and `action` are set).
	 * @method The HTTP method to use in the request (`get`, `post` etc).
	 * @returnAs Pass in `struct` to return all information about the request instead of just the final output (`body`).
	 * @rollback Pass in `true` to roll back all database transactions made during the request.
	 * @includeFilters Set to `before` to only execute "before" filters, `after` to only execute "after" filters or `false` to skip all filters.
	 */
	public any function processRequest(
		required struct params,
		string method,
		string returnAs,
		string rollback,
		string includeFilters = true
	) {
		$args(name = "processRequest", args = arguments);

		// Set the global transaction mode to rollback when specified.
		// Also save the current state so we can set it back after the tests have run.
		if (arguments.rollback) {
			local.transactionMode = $get("transactionMode");
			$set(transactionMode = "rollback");
		}

		// Before proceeding we set the request method to our internal CGI scope if passed in.
		// This way it's possible to mock a POST request so that an isPost() call in the action works as expected for example.
		if (arguments.method != "get") {
			request.cgi.request_method = arguments.method;
		}

		// Look up controller & action via route name and method
		if (StructKeyExists(arguments.params, "route")) {
			local.route = $findRoute(argumentCollection = arguments.params, method = arguments.method);
			arguments.params.controller = local.route.controller;
			arguments.params.action = local.route.action;
		}

		// Never deliver email or send files during test.
		local.deliverEmail = $get(functionName = "sendEmail", name = "deliver");
		$set(functionName = "sendEmail", deliver = false);
		local.deliverFile = $get(functionName = "sendFile", name = "deliver");
		$set(functionName = "sendFile", deliver = false);

		local.controller = controller(name = arguments.params.controller, params = arguments.params);

		// Set to ignore CSRF errors during testing.
		local.controller.protectsFromForgery(with = "ignore");

		local.controller.processAction(includeFilters = arguments.includeFilters);
		local.response = local.controller.response();

		// Get redirect info.
		// If a delayed redirect was made we use the status code for that and set the body to a blank string.
		// If not we use the current status code and response and set the redirect info to a blank string.
		local.redirectDetails = local.controller.getRedirect();
		if (StructCount(local.redirectDetails)) {
			local.body = "";
			local.redirect = local.redirectDetails.url;
			local.status = local.redirectDetails.statusCode;
		} else {
			local.status = $statusCode();
			local.body = local.response;
			local.redirect = "";
		}

		if (arguments.returnAs == "struct") {
			local.rv = {
				body = local.body,
				emails = local.controller.getEmails(),
				files = local.controller.getFiles(),
				flash = local.controller.flash(),
				redirect = local.redirect,
				status = local.status,
				type = $contentType()
			};
		} else {
			local.rv = local.body;
		}

		// Clear the Flash so we can run several processAction calls without the Flash sticking around.
		local.controller.$flashClear();

		// Set back the global transaction mode to the previous value if it has been changed.
		if (arguments.rollback) {
			$set(transactionMode = local.transactionMode);
		}

		// Set back the request method to GET (this is fine since the test suite is always run using GET).
		request.cgi.request_method = "get";

		// Set back email delivery setting to previous value.
		$set(functionName = "sendEmail", deliver = local.deliverEmail);
		$set(functionName = "sendFile", deliver = local.deliverFile);

		// Set back the status code to 200 so the test suite does not use the same code that the action that was tested did.
		// If the test suite fails it will set the status code to 500 later.
		$header(statusCode = 200);

		// Set the Content-Type header in case it was set to something else (e.g. application/json) during processing.
		// It's fine to do this because we always want to return the test page as text/html.
		$header(name = "Content-Type", value = "text/html", charset = "UTF-8");

		return local.rv;
	}

	public array function $splitOutsideFunctions(required string list, required string splitBy) {
		local.rv = [];
		local.temp = "";
		local.insideFunction = false;
		local.bracketCount = 0;

		for (local.i = 1; i <= Len(arguments.list); i++) {
			local.char = Mid(arguments.list, i, 1);

			// Check if we are entering or exiting a function's parentheses
			if (local.char == "(") {
				local.bracketCount++;
			} else if (local.char == ")") {
				local.bracketCount--;
			}

			// Determine if we are inside a function (any content enclosed by parentheses)
			if (local.bracketCount > 0) {
				local.insideFunction = true;
			} else if (local.bracketCount == 0) {
				local.insideFunction = false;
			}

			// Split based on commas outside functions
			if (local.char == arguments.splitBy && !local.insideFunction) {
				ArrayAppend(local.rv, Trim(local.temp));
				local.temp = "";
			} else {
				local.temp &= local.char;
			}
		}

		// Append the final segment
		if (Len(Trim(local.temp))) {
			ArrayAppend(local.rv, Trim(local.temp));
		}

		return local.rv;
	}

	/**
	 * Normalizes a nested key path by converting bracket notation (e.g., `form[user][email]`) to dot notation (e.g., `form.user.email`).
	 *
	 * [section: Global Helpers]
	 * [category: String Functions]
	 *
	 * @path The key path to normalize.
	 */
	public string function $normalizePath(required string path) {
		local.norm = arguments.path;
		local.norm = ReReplace(local.norm, "\[(.*?)\]", ".\1", "all");
		local.norm = ReReplace(local.norm, "^\.", "", "one");
		return local.norm;
	}

	// ======================================================================
	// CORS FUNCTIONS
	// ======================================================================

	/**
	 * Wildcard domain match: check if the current cgi.server_name and port satisfies
	 * the passed in domain string whilst checking for wildcards
	 *
	 * @domain string to test against e.g *.foo.com
	 * @cgi Fake CGI Scope for Testing; will default to normal cgi scope
	 */
	public boolean function $wildcardDomainMatchCGI(required string domain, struct cgi) {
		local.domain = arguments.domain;
		local.cgi = StructKeyExists(arguments, "cgi") ? arguments.cgi : $cgiScope();

		return $wildcardDomainMatch($fullDomainString(local.domain), $fullCgiDomainString(local.cgi));
	}

	/**
	 * Wildcard domain match: domain satisfies wildcard
	 *
	 * @domain string to test against e.g *.foo.com
	 * @origin string to test against e.g bar.foo.com
	 */
	public boolean function $wildcardDomainMatch(required string domain, required string origin) {
		local.rv = false;
		local.domainfull = $fullDomainString(arguments.domain);
		local.originfull = $fullDomainString(arguments.origin);

		// Do we have a wildcard subdomain?
		local.hasWildcard = ListContainsNoCase(local.domainfull, "*", '.') && Len(local.domainfull > 1);

		// If not, is it an exact match?
		if (!local.hasWildcard && local.domainfull == local.originfull) {
			local.rv = true;
		}

		// Loop over domain backwards and test the corresponding position in the other array
		if (local.hasWildcard) {
			local.domainReversed = ListToArray(Reverse(SpanExcluding(Reverse(local.domainfull), ".")));
			local.serverNameReversed = ListToArray(Reverse(SpanExcluding(Reverse(local.originfull), ".")));
			local.wildcardPassed = true;
			// Check each part with corresponding part in other array
			for (local.i = 1; i LTE ArrayLen(local.domainReversed); i = i + 1) {
				if (local.domainReversed[i] != local.serverNameReversed[i] && local.domainReversed[i] DOES NOT CONTAIN '*') {
					local.wildcardPassed = false;
					break;
				}
			}
			local.rv = local.wildcardPassed;
		}

		return local.rv;
	}

	/**
	 * Get full domain string from cgi scope: includes protocol and port
	 * e.g https://www.wheels.dev:443
	 *
	 * @cgi Fake CGI Scope for Testing; will default to normal cgi scope
	 **/
	public string function $fullCgiDomainString(struct cgi) {
		local.cgi = StructKeyExists(arguments, "cgi") ? arguments.cgi : $cgiScope();
		local.server_name = local.cgi.server_name;
		local.server_port = local.cgi.server_port;
		local.server_protocol =
		(
			(StructKeyExists(local.cgi, 'http_x_forwarded_proto') && local.cgi.http_x_forwarded_proto == "https")
			|| (StructKeyExists(local.cgi, 'server_port_secure') && local.cgi.server_port_secure)
		)
		 ? "https" : "http";
		return local.server_protocol & '://' & local.server_name & ':' & local.server_port;
	}

	/**
	 * Get full domain string from a passed in string: includes protocol and port
	 * e.g https://www.wheels.dev -> https://www.wheels.dev:443
	 * e.g www.wheels.dev -> http://www.wheels.dev:80
	 *
	 * @domain The string to look at
	 **/
	public string function $fullDomainString(required string domain) {
		local.domain = arguments.domain;
		local.protocol = ListFirst(local.domain, "://");
		local.port = ListLast(local.domain, ":");

		if (!ListFindNoCase("http,https", local.protocol)) {
			if (local.port == 443) {
				local.protocol = "https";
			} else {
				local.protocol = "http";
			}
			local.domain = local.protocol & '://' & local.domain;
		}
		if (!IsNumeric(local.port)) {
			if (local.protocol == 'http') {
				local.port = 80;
			} else if (local.protocol == 'https') {
				local.port = 443;
			}
			local.domain &= ':' & local.port;
		}
		return local.domain;
	}

	/**
	 * Set CORS Headers: only triggered if application.wheels.allowCorsRequests = true
	 */
	public void function $setCORSHeaders(
		string allowOrigin = "",
		string allowCredentials = false,
		string allowHeaders = "Origin, Content-Type, X-Auth-Token, X-Requested-By, X-Requested-With",
		string allowMethods = "GET, POST, PATCH, PUT, DELETE, OPTIONS",
		boolean allowMethodsByRoute = false,
		string pathInfo = request.cgi.PATH_INFO,
		string scriptName = request.cgi.script_name
	) {
		local.incomingOrigin = StructKeyExists(request.wheels.httprequestdata.headers, "origin") ? request.wheels.httprequestdata.headers.origin : false;

		// No origins configured — skip all CORS headers (deny all by default)
		if (!Len(arguments.allowOrigin)) {
			return;
		}

		// Either a wildcard, or if a specific domain is set, we need to ensure the incoming request matches it
		if (arguments.allowOrigin == "*") {
			$header(name = "Access-Control-Allow-Origin", value = arguments.allowOrigin);
		} else {
			// Passed value may be a list or just a single entry
			local.originArr = ListToArray(arguments.allowOrigin);

			// Is this origin in the allowed Array?
			for (local.o in local.originArr) {
				if ($wildcardDomainMatch(local.o, local.incomingOrigin)) {
					$header(name = "Access-Control-Allow-Origin", value = local.incomingOrigin);
					$header(name = "Vary", value = "Origin");
					break;
				}
			}
		}

		// Set Origin, Content-Type, X-Auth-Token, X-Requested-By, X-Requested-With Allow Headers
		$header(name = "Access-Control-Allow-Headers", value = arguments.allowHeaders);

		// Either Look up Route specific allowed methods, or just use default
		if (arguments.allowMethodsByRoute) {
			local.permittedMethods = [];

			// NB this is basically duplicate logic: needs refactoring
			if (arguments.pathInfo == arguments.scriptName || arguments.pathInfo == "/" || !Len(arguments.pathInfo)) {
				local.path = "";
			} else {
				local.path = Right(arguments.pathInfo, Len(arguments.pathInfo) - 1);
			}

			// Attempt to match the requested route and only display the allowed methods for that route
			// Does this info already exist in scope? It seems silly to have to look it up again
			for (local.route in application.wheels.routes) {
				// Make sure route has been converted to regular expression.
				if (!StructKeyExists(local.route, "regex")) {
					local.route.regex = application.wheels.mapper.$patternToRegex(local.route.pattern);
				}

				// If route matches regular expression, get the methods
				if (ReFindNoCase(local.route.regex, local.path)) {
					ArrayAppend(local.permittedMethods, local.route.methods);
				}
			}
			if (ArrayLen(local.permittedMethods)) {
				$header(name = "Access-Control-Allow-Methods", value = UCase(ArrayToList(local.permittedMethods, ', ')));
			}
		} else {
			$header(name = "Access-Control-Allow-Methods", value = arguments.allowMethods);
		}

		// Only add this header if requested (false is an invalid value)
		if (arguments.allowCredentials) {
			$header(name = "Access-Control-Allow-Credentials", value = true);
		}
	}

	/**
	 * Internal. Returns true when a `wheels.middleware.Cors` instance (or its
	 * component path) is registered in `application.wheels.middleware`. When it
	 * is, the dispatch-level Cors middleware is the single source of truth for
	 * CORS headers and OPTIONS preflight, so the legacy global path
	 * (`$setCORSHeaders` + the `onRequestStart` OPTIONS abort) must step aside.
	 * Running both stacks duplicate `Access-Control-Allow-*` headers; a
	 * duplicate `Access-Control-Allow-Origin` makes browsers reject the
	 * response per the Fetch spec. Mirrors the detection in
	 * `Dispatch.$computePreflightCapable()`. (#3114)
	 */
	public boolean function $corsMiddlewareActive() {
		if (
			!StructKeyExists(application, "wheels")
			|| !StructKeyExists(application.wheels, "middleware")
			|| !IsArray(application.wheels.middleware)
		) {
			return false;
		}
		for (local.mw in application.wheels.middleware) {
			if (IsSimpleValue(local.mw)) {
				if (local.mw == "wheels.middleware.Cors") {
					return true;
				}
			} else if (IsObject(local.mw) && IsInstanceOf(local.mw, "wheels.middleware.Cors")) {
				return true;
			}
		}
		return false;
	}

	/**
	 * Internal. Logs a one-time warning when the legacy global CORS path is
	 * suppressed in favour of a registered `wheels.middleware.Cors` instance,
	 * so operators notice the redundant `allowCorsRequests=true` setting. (#3114)
	 */
	public void function $warnGlobalCorsDeferred() {
		if (StructKeyExists(application.wheels, "$corsGlobalDeferredWarned")) {
			return;
		}
		cflock(name = "wheels.corsGlobalDeferred.#application.applicationName#", type = "exclusive", timeout = 5) {
			if (!StructKeyExists(application.wheels, "$corsGlobalDeferredWarned")) {
				application.wheels.$corsGlobalDeferredWarned = true;
				cflog(
					type = "warning",
					file = "wheels",
					text = "CORS configuration conflict: both allowCorsRequests=true and a wheels.middleware.Cors "
						& "instance are active. The legacy global CORS path is deferring to the middleware to avoid "
						& "duplicate Access-Control-Allow-* headers. Disable allowCorsRequests once the Cors middleware "
						& "is configured. (##3114)"
				);
			}
		}
	}

	/**
	 * Restore the application scope modified by the test runner
	 */
	public void function $restoreTestRunnerApplicationScope() {
		if (StructKeyExists(request, "wheels") && StructKeyExists(request.wheels, "testRunnerApplicationScope")) {
			application.wheels = request.wheels.testRunnerApplicationScope;
		}
	}

	/**
	 * Registers a callback function to be invoked when an unhandled error occurs.
	 * Callbacks receive a single argument: the exception struct.
	 * Multiple callbacks are invoked in registration order. A failing callback
	 * is logged and skipped — it will not prevent other callbacks from running.
	 * Should be called during app initialization, not per-request.
	 *
	 * [section: Configuration]
	 * [category: Error Handling]
	 *
	 * @callback A function that accepts an exception struct argument. Must complete quickly — long-running callbacks delay error responses.
	 */
	public void function registerOnError(required function callback) {
		ArrayAppend(application.wheels.onErrorCallbacks, arguments.callback);
	}

	/**
	 * Fires all registered onError callbacks. Each runs in its own try/catch
	 * so a broken callback cannot suppress other callbacks or break error rendering.
	 */
	public void function $fireOnErrorCallbacks(required any exception) {
		if (
			StructKeyExists(application, "wheels")
			&& StructKeyExists(application.wheels, "onErrorCallbacks")
			&& IsArray(application.wheels.onErrorCallbacks)
		) {
			for (var cb in application.wheels.onErrorCallbacks) {
				try {
					cb(arguments.exception);
				} catch (any e) {
					cflog(text = "onError callback failed: #e.message#", type = "error", file = "wheels-errors");
				}
			}
		}
	}

	/**
	 * Verifies that mixin-assembled objects satisfy critical interface contracts.
	 * Runs only in development mode at the end of application bootstrap.
	 * Checks a subset of essential methods — full verification is done by test specs.
	 * Logs warnings instead of throwing to avoid blocking app startup.
	 * Note: the model check is a no-op at startup because models are lazy-loaded
	 * (application.wheels.models is empty until the first model() call).
	 * It activates when called later or from tests.
	 */
	public void function $verifyInterfaceContracts() {
		local.issues = [];

		// Check Model interface (requires at least one model to be loaded)
		try {
			local.modelMethods = [
				"findAll",
				"findOne",
				"findByKey",
				"count",
				"exists",
				"save",
				"valid",
				"update",
				"delete",
				"hasMany",
				"belongsTo",
				"hasOne",
				"validatesPresenceOf"
			];
			if (StructKeyExists(application.wheels, "models") && !StructIsEmpty(application.wheels.models)) {
				local.sampleModelName = StructKeyArray(application.wheels.models)[1];
				local.sampleModel = model(local.sampleModelName);
				for (local.m in local.modelMethods) {
					if (!StructKeyExists(local.sampleModel, local.m)) {
						ArrayAppend(local.issues, "Model(#local.sampleModelName#) missing: #local.m#()");
					}
				}
			}
		} catch (any e) {
			ArrayAppend(local.issues, "Model contract check failed: #e.message#");
		}

		// Check Controller interface
		try {
			local.controllerMethods = [
				"renderView",
				"renderPartial",
				"renderText",
				"redirectTo",
				"linkTo",
				"urlFor",
				"startFormTag",
				"endFormTag",
				"filters",
				"verifies"
			];
			local.params = {controller = "wheels", action = "wheels"};
			local.testController = controller(name = "wheels", params = local.params);
			for (local.m in local.controllerMethods) {
				if (!StructKeyExists(local.testController, local.m)) {
					ArrayAppend(local.issues, "Controller missing: #local.m#()");
				}
			}
		} catch (any e) {
			ArrayAppend(local.issues, "Controller contract check failed: #e.message#");
		}

		// Report issues as warnings
		if (ArrayLen(local.issues)) {
			local.msg = "Interface contract warnings: " & ArrayToList(local.issues, "; ");
			cflog(text = local.msg, type = "warning", file = "wheels-errors");
			if (StructKeyExists(application, "wheels") && application.wheels.showDebugInformation) {
				request.wheels.interfaceWarnings = local.issues;
			}
		}
	}

	/**
	 * Snapshot mtimes of all .cfm files under the app's global include directory.
	 *
	 * Used by the bare `?reload=true` path so a developer adding a helper to
	 * `app/global/*.cfm` does not have to remember the password-gated full reload
	 * (issue ##2792).
	 */
	public struct function $snapshotGlobalIncludes(string directory = ExpandPath("/app/global")) {
		var snapshot = {};
		if (!DirectoryExists(arguments.directory)) {
			return snapshot;
		}
		var files = DirectoryList(arguments.directory, true, "query", "*.cfm");
		for (var row in files) {
			snapshot[row.directory & "/" & row.name] = row.dateLastModified;
		}
		return snapshot;
	}

	/**
	 * Compare a prior `$snapshotGlobalIncludes` result against the current
	 * filesystem state and return true if any tracked .cfm file was added,
	 * removed, or modified.
	 *
	 * Paired with `$snapshotGlobalIncludes` to drive the bare `?reload=true`
	 * soft-reload path in development (issue ##2792).
	 */
	public boolean function $globalIncludesChanged(
		required struct snapshot,
		string directory = ExpandPath("/app/global")
	) {
		var current = $snapshotGlobalIncludes(directory = arguments.directory);
		for (var key in current) {
			if (!StructKeyExists(arguments.snapshot, key)) {
				return true;
			}
			if (DateCompare(arguments.snapshot[key], current[key]) != 0) {
				return true;
			}
		}
		for (var key in arguments.snapshot) {
			if (!StructKeyExists(current, key)) {
				return true;
			}
		}
		return false;
	}

	/**
	 * Build the comma-list of public framework helper names that get mixed onto
	 * every controller (from `wheels.Global` + `wheels.controller.*` +
	 * `wheels.view.*`). Stored on `application.wheels.protectedControllerMethods`
	 * and consumed by `$callAction()` to reject URL dispatch to framework
	 * helpers like `env()`, `model()`, `redirectTo()` (issue ##2844).
	 *
	 * Derived from `getMetaData().functions` on each source component, mirroring
	 * what `$integrateComponents` mixes onto a controller. `$`-prefixed names
	 * are already gated separately and are excluded here.
	 */
	public string function $buildProtectedControllerMethods() {
		var protectedMethods = "";
		var sources = ["wheels.Global"];
		var mixinPaths = ["wheels.controller", "wheels.view"];
		for (var basePath in mixinPaths) {
			var folder = ExpandPath("/" & Replace(basePath, ".", "/", "all"));
			if (!DirectoryExists(folder)) {
				continue;
			}
			var files = DirectoryList(folder, false, "name", "*.cfc");
			for (var fileName in files) {
				ArrayAppend(sources, basePath & "." & Replace(fileName, ".cfc", "", "all"));
			}
		}
		for (var componentPath in sources) {
			var meta = GetMetaData(CreateObject("component", componentPath));
			if (!StructKeyExists(meta, "functions")) {
				continue;
			}
			for (var fn in meta.functions) {
				if (
					StructKeyExists(fn, "access") && fn.access == "public"
					&& Left(fn.name, 1) != "$"
					&& !ListFindNoCase(protectedMethods, fn.name)
				) {
					protectedMethods = ListAppend(protectedMethods, fn.name);
				}
			}
		}
		return protectedMethods;
	}

	/**
	 * Convert the comma-list returned by `$buildProtectedControllerMethods()`
	 * into a struct-as-set so `$callAction()` can perform an O(1)
	 * `StructKeyExists` membership test on the per-request dispatch hot path
	 * instead of an O(n) `ListFindNoCase` scan over ~100-250 helper names.
	 * CFML struct keys are case-insensitive by default, preserving the prior
	 * `ListFindNoCase` semantics (an action named `ENV` is still rejected like
	 * `env`). Stored on `application.wheels.protectedControllerMethodsLookup`
	 * alongside the list, which is retained for callers expecting that shape.
	 */
	public struct function $protectedControllerMethodsLookup(required string methods) {
		var lookup = {};
		for (var name in ListToArray(arguments.methods)) {
			lookup[name] = true;
		}
		return lookup;
	}

	/**
	 * Re-evaluate the given global-includes file into `application.wo`'s
	 * variables/this scope. Invoked from the bare `?reload=true` soft-reload
	 * when `$globalIncludesChanged` reports drift (issue ##2792).
	 *
	 * `include` inside a method body adds function declarations to the
	 * method's local scope, not the component's outer scope, so we walk
	 * local for any user-defined functions and copy them onto variables
	 * and this so they remain callable on `application.wo` across requests.
	 */
	public void function $reincludeGlobals(string file = "/app/global/functions.cfm") {
		// Evaluate the file in a throwaway instance and bind the functions it
		// declares onto variables + this. Done via a separate instance (not a
		// bare `include` here) because Adobe CF throws "Routines cannot be
		// declared more than once" when a `?reload=true` re-includes a file
		// whose UDFs are already bound to application.wo — the prior copy in
		// our own scope collides with the re-declaration. A fresh scope per
		// call sidesteps that; rebinding here is a plain struct assignment, so
		// the updated version replaces the old one on every engine.
		var reloaded = new wheels.GlobalIncludeLoader().loadFunctions(arguments.file);
		for (var key in reloaded) {
			variables[key] = reloaded[key];
			this[key] = reloaded[key];
		}
	}

	// User-defined global functions
	include "/app/global/functions.cfm";

	// Promote include-injected UDFs from `variables` to `this` so they're
	// discoverable via struct-iteration on engines (Adobe CF) where only
	// `this`-scope members are reliably enumerable. Declared methods on
	// Global.cfc are already in `this` via their `access` modifier and are
	// not clobbered by the `structKeyExists(this, ...)` guard. See #2790
	// and the auto-bind loop in `vendor/wheels/WheelsTest.cfc`.
	//
	// Delegated to `$promoteIncludedGlobalsToThis()` so the loop iterator
	// lives in a real function-local scope. Inlining a `local.X` iterator in
	// the pseudo-constructor materializes `variables.local` on the Global
	// instance — harmless on Lucee/Adobe (where `local` is reserved to the
	// function scope) but on BoxLang it shadows the method-local `local` of
	// every mixed-in `$`-helper (Migrator/Model `local.appKey`, …), throwing
	// "The key [...] was not found in the struct. Valid keys are ([VARKEY])".
	$promoteIncludedGlobalsToThis();

	/**
	 * Copy include-injected user functions from `variables` onto `this` so
	 * they remain enumerable on engines (Adobe CF) where struct-iteration
	 * only reliably surfaces `this`-scope members. Must stay a function: an
	 * inline `local.X` iterator in the pseudo-constructor materializes
	 * `variables.local` and shadows method-local `local` on BoxLang.
	 *
	 * The promote-key list is memoized in application scope because this runs
	 * on EVERY instantiation of every Global-derived component (per model row,
	 * per controller, per Plugins instance) while its input — the function set
	 * injected by the `/app/global/functions.cfm` include above — is constant
	 * for the application lifetime. The memo is keyed per concrete class name
	 * because whether a subclass's own (e.g. private) methods are already
	 * registered in `variables` at this point in the pseudo-constructor is
	 * engine-dependent, so the promotable set is not guaranteed identical
	 * across subclasses. The gate is the cached key itself, never a separate
	 * done-flag (##2800 lesson), and the cache lives inside
	 * `application[$appKey()]`, which `?reload=true` rebuilds as a fresh
	 * struct — so invalidation is structural. When `application` (or the
	 * Wheels struct in it) is unavailable — CLI/test bootstrap, early
	 * application start — we fall back to the full scan without memoizing.
	 */
	public void function $promoteIncludedGlobalsToThis() {
		var promoteCache = "";
		var promoteCacheKey = "";
		if (IsDefined("application")) {
			var promoteAppKey = $appKey();
			if (StructKeyExists(application, promoteAppKey) && IsStruct(application[promoteAppKey])) {
				var classMetadata = GetMetadata(this);
				if (IsStruct(classMetadata) && StructKeyExists(classMetadata, "name") && Len(classMetadata.name)) {
					promoteCacheKey = classMetadata.name;
					if (!StructKeyExists(application[promoteAppKey], "promotedGlobalKeys")) {
						application[promoteAppKey].promotedGlobalKeys = {};
					}
					promoteCache = application[promoteAppKey].promotedGlobalKeys;
				}
			}
		}
		if (IsStruct(promoteCache) && StructKeyExists(promoteCache, promoteCacheKey)) {
			// Memoized path: apply the recorded keys with the same guards the
			// fresh scan uses. Keys that vanished from `variables` are skipped
			// and keys already on `this` are left alone, so a stale entry can
			// never promote something the scan would not have.
			var cachedKeys = promoteCache[promoteCacheKey];
			var cachedKeyCount = ArrayLen(cachedKeys);
			for (var keyIndex = 1; keyIndex <= cachedKeyCount; keyIndex++) {
				var promoteKey = cachedKeys[keyIndex];
				if (StructKeyExists(variables, promoteKey) && !StructKeyExists(this, promoteKey)) {
					this[promoteKey] = variables[promoteKey];
				}
			}
			return;
		}
		var promotedKeys = $scanAndPromoteIncludedGlobals();
		if (IsStruct(promoteCache)) {
			// Concurrent first instantiations may both scan and both assign;
			// the value is deterministic per class, so last-write-wins is safe.
			promoteCache[promoteCacheKey] = promotedKeys;
		}
	}

	/**
	 * The full `variables` scan behind `$promoteIncludedGlobalsToThis()`:
	 * promote every variables-scope custom function that is not already on
	 * `this`, returning the promoted key names. Also serves as the
	 * non-memoizing fallback when application scope is unavailable.
	 */
	public array function $scanAndPromoteIncludedGlobals() {
		var promotedKeys = [];
		for (var promoteKey in variables) {
			if (!isCustomFunction(variables[promoteKey])) {
				continue;
			}
			if (structKeyExists(this, promoteKey)) {
				continue;
			}
			this[promoteKey] = variables[promoteKey];
			ArrayAppend(promotedKeys, promoteKey);
		}
		return promotedKeys;
	}

}