Boolean Form Parser

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.
 */

/**
 * Converts checkbox, radio, and hidden boolean values into explicit true/false integers.
 *
 * Primary use case: Admin forms and settings panels.
 * Typical inputs: raw value, default.
 * Typical output: 0 or 1.
 *
 * Implementation note: Accept only approved truthy/falsy values.
 *
 * @param mixed $value Raw submitted value from a checkbox, radio, hidden input, or settings field.
 * @param int $default Default value returned when the field is missing or intentionally blank.
 * @return array Structured result with parsed integer boolean, validity, and reason data.
 */
function ogParseFormBoolean($value, $default = 0) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	$default = (int)$default;
	if ($default !== 1) {
		$default = 0;
	}

	if (is_bool($value)) {
		$parsed_value = 0;
		if ($value) {
			$parsed_value = 1;
		}

		$result['success'] = true;
		$result['message'] = 'Boolean value parsed.';
		$result['data'] = array(
			'value' => $parsed_value,
			'is_default' => false,
			'valid' => true
		);
		return $result;
	}

	if ($value === null) {
		$result['success'] = true;
		$result['message'] = 'Boolean value missing; default applied.';
		$result['data'] = array(
			'value' => $default,
			'is_default' => true,
			'valid' => true
		);
		return $result;
	}

	$value = strtolower(trim((string)$value));

	$truthy_values = array('1', 'true', 'yes', 'y', 'on', 'checked', 'enabled');
	$falsy_values = array('0', 'false', 'no', 'n', 'off', 'unchecked', 'disabled', '');

	if (in_array($value, $truthy_values, true)) {
		$parsed_value = 1;
	} elseif (in_array($value, $falsy_values, true)) {
		$parsed_value = 0;
	} else {
		$result['message'] = 'Boolean value is not approved.';
		$result['data'] = array(
			'value' => $default,
			'is_default' => true,
			'valid' => false,
			'raw_value' => $value
		);
		return $result;
	}

	$result['success'] = true;
	$result['message'] = 'Boolean value parsed.';
	$result['data'] = array(
		'value' => $parsed_value,
		'is_default' => false,
		'valid' => true
	);

	return $result;
}