Array Dot Path Reader

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

/**
 * Reads nested array data using dot-path notation with safe fallback handling.
 *
 * Primary use case: Config readers, API payload processing.
 * Typical inputs: array, dot path, default value.
 * Typical output: value or default.
 *
 * Implementation note: Avoid magic references; handle missing keys explicitly.
 *
 * @param array $data Source array.
 * @param string $path Dot-delimited path such as user.email or settings.mail.host.
 * @param mixed $default Default value returned when the path is not present.
 * @return array Structured result with found flag and value.
 */
function ogReadDotPathValue($data, $path, $default = null) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	if (!is_array($data)) {
		$result['message'] = 'Data must be an array.';
		$result['data'] = array('value' => $default, 'found' => false);
		return $result;
	}

	$path = trim((string)$path);
	if (empty($path)) {
		$result['message'] = 'Path is required.';
		$result['data'] = array('value' => $default, 'found' => false);
		return $result;
	}

	$parts = explode('.', $path);
	$current = $data;
	$found = true;

	foreach ($parts as $part) {
		$part = trim((string)$part);
		if ($part === '') {
			$found = false;
			$current = $default;
			break;
		}

		if (is_array($current) && array_key_exists($part, $current)) {
			$current = $current[$part];
		} else {
			$found = false;
			$current = $default;
			break;
		}
	}

	$result['success'] = true;
	if ($found) {
		$result['message'] = 'Path value found.';
	} else {
		$result['message'] = 'Path value not found.';
	}
	$result['data'] = array('value' => $current, 'found' => $found);

	return $result;
}