Bulk Insert Planner

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

/**
 * Plans safe batched inserts from validated records.
 *
 * The function creates batch metadata and prepared INSERT plans. It does not execute
 * SQL and does not alter data.
 *
 * @param string $table Database table name.
 * @param array $records Validated records to insert.
 * @param array $allowed_fields Field allowlist.
 * @param int $batch_size Number of records per batch.
 * @return array Bulk insert plan.
 */
function ogPlanBulkInsert($table, $records = array(), $allowed_fields = array(), $batch_size = 100) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	$table = trim((string)$table);
	if (empty($table) || !preg_match('/^[a-zA-Z0-9_]+$/', $table)) {
		$result['message'] = 'Invalid table name.';
		return $result;
	}

	if (!is_array($records) || empty($records)) {
		$result['message'] = 'Records are required.';
		return $result;
	}

	$batch_size = (int)$batch_size;
	if ($batch_size < 1) {
		$batch_size = 1;
	}
	if ($batch_size > 1000) {
		$batch_size = 1000;
	}

	$clean_records = array();
	foreach ($records as $record) {
		if (!is_array($record)) {
			continue;
		}
		$clean = array();
		foreach ($record as $field => $value) {
			$field = trim((string)$field);
			if (!preg_match('/^[a-zA-Z0-9_]+$/', $field)) {
				continue;
			}
			if (!empty($allowed_fields) && !in_array($field, $allowed_fields, true)) {
				continue;
			}
			$clean[$field] = $value;
		}
		if (!empty($clean)) {
			$clean_records[] = $clean;
		}
	}

	if (empty($clean_records)) {
		$result['message'] = 'No valid records remained after field filtering.';
		return $result;
	}

	$batches = array();
	$offset = 0;
	$total = count($clean_records);
	while ($offset < $total) {
		$batch_records = array_slice($clean_records, $offset, $batch_size);
		$batches[] = array(
			'batch_number' => count($batches) + 1,
			'offset' => $offset,
			'count' => count($batch_records),
			'records' => $batch_records
		);
		$offset += $batch_size;
	}

	$result['success'] = true;
	$result['message'] = 'Bulk insert plan built.';
	$result['data'] = array(
		'table' => $table,
		'total_records' => $total,
		'batch_size' => $batch_size,
		'batch_count' => count($batches),
		'batches' => $batches
	);

	return $result;
}