Input Intent Classifier

Code

<?php

/*
 * Copyright (c) 2026 Jeffery L. Paris <jparis@phpog.com>.
 * Free for personal and internal use. Paid project use requires visible credit
 * to Jeffery L. Paris. Corporate use requires a paid license fee unless a
 * separate written license states otherwise.
 */

/**
 * Classifies request input by expected context such as email, slug, integer, URL, HTML text, or plain text.
 *
 * Primary use case: Route request values to the right cleaner.
 * Typical inputs: field name, raw value, schema rules.
 * Typical output: classified field object.
 *
 * Implementation note: Use context-specific validators and output encoders separately.
 *
 * @param string $field_name Input field name.
 * @param mixed $value Raw input value.
 * @param array $schema Optional field rules keyed by field name.
 * @return array Structured result data with success, message, and data keys.
 */
function ogClassifyInputIntent($field_name, $value, $schema = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	$field_name = trim((string)$field_name);
	if (!is_array($schema)) {
		$schema = array();
	}

	if (empty($field_name)) {
		$result['message'] = 'Missing field name.';
		return $result;
	}

	$intent = 'plain_text';
	if (!empty($schema[$field_name]['intent'])) {
		$intent = trim((string)$schema[$field_name]['intent']);
	} else {
		$lower_name = strtolower($field_name);
		if (preg_match('/(^|_)(id|count|qty|quantity|page|limit|offset)$/', $lower_name)) {
			$intent = 'integer';
		} elseif (strpos($lower_name, 'email') !== false) {
			$intent = 'email';
		} elseif (strpos($lower_name, 'slug') !== false) {
			$intent = 'slug';
		} elseif (strpos($lower_name, 'url') !== false || strpos($lower_name, 'link') !== false) {
			$intent = 'url';
		} elseif (strpos($lower_name, 'html') !== false || strpos($lower_name, 'body') !== false || strpos($lower_name, 'content') !== false) {
			$intent = 'html_text';
		} elseif (strpos($lower_name, 'date') !== false || strpos($lower_name, 'time') !== false) {
			$intent = 'date_time';
		} elseif (strpos($lower_name, 'price') !== false || strpos($lower_name, 'amount') !== false || strpos($lower_name, 'total') !== false) {
			$intent = 'currency';
		}
	}

	$allowed_intents = array('plain_text', 'integer', 'email', 'slug', 'url', 'html_text', 'date_time', 'currency', 'boolean', 'file');
	if (!in_array($intent, $allowed_intents, true)) {
		$intent = 'plain_text';
	}

	$result['success'] = true;
	$result['message'] = 'Input intent classified.';
	$result['data'] = array(
		'field_name' => $field_name,
		'intent' => $intent,
		'value_type' => gettype($value),
		'needs_output_encoding' => true,
		'needs_sql_handling' => true
	);

	return $result;
}