Import Dry Run Reporter

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

/**
 * Runs an import preview and reports inserts, updates, skips, and errors without writing data.
 *
 * The function compares candidate rows against existing keys and validation errors. It performs no
 * database writes and is safe for pre-import review screens.
 *
 * @param array $rows Import candidate rows.
 * @param array $rules Existing keys, required fields, and match field rules.
 * @return array Dry-run import report.
 */
function ogBuildImportDryRunReport($rows = array(), $rules = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	if (!is_array($rows)) {
		$result['message'] = 'Import rows must be an array.';
		return $result;
	}
	if (!is_array($rules)) {
		$rules = array();
	}

	$match_field = 'id';
	if (!empty($rules['match_field'])) {
		$match_field = preg_replace('/[^a-zA-Z0-9_]/', '', (string)$rules['match_field']);
	}
	$existing_keys = array();
	if (!empty($rules['existing_keys']) && is_array($rules['existing_keys'])) {
		foreach ($rules['existing_keys'] as $key) {
			$existing_keys[(string)$key] = true;
		}
	}
	$required_fields = array();
	if (!empty($rules['required_fields']) && is_array($rules['required_fields'])) {
		$required_fields = $rules['required_fields'];
	}

	$report_rows = array();
	$counts = array('insert' => 0, 'update' => 0, 'skip' => 0, 'error' => 0);
	foreach ($rows as $index => $row) {
		$status = 'insert';
		$errors = array();
		if (!is_array($row)) {
			$status = 'error';
			$errors[] = 'Row is not an array.';
		} else {
			foreach ($required_fields as $field) {
				$field = (string)$field;
				if (!isset($row[$field]) || trim((string)$row[$field]) == '') {
					$errors[] = 'Missing required field: ' . $field;
				}
			}
			$match_value = '';
			if (!empty($row[$match_field])) {
				$match_value = (string)$row[$match_field];
			}
			if (!empty($errors)) {
				$status = 'error';
			} elseif (!empty($match_value) && !empty($existing_keys[$match_value])) {
				$status = 'update';
			}
		}
		$counts[$status]++;
		$report_rows[] = array(
			'row_number' => $index + 1,
			'status' => $status,
			'errors' => $errors
		);
	}

	$result['success'] = true;
	$result['message'] = 'Import dry-run report built.';
	$result['data'] = array(
		'counts' => $counts,
		'rows' => $report_rows
	);

	return $result;
}