Data Sync Checkpoint

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

/**
 * Builds a resumable sync checkpoint record.
 *
 * The result is safe to store in a database row or JSON state file after the
 * caller has completed a sync step.
 *
 * @param array $state Current sync state.
 * @param array $options Checkpoint options.
 * @return array Checkpoint record.
 */
function ogBuildSyncCheckpoint($state = array(), $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

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

	if (!is_array($options)) {
		$options = array();
	}

	$sync_name = '';
	if (!empty($state['sync_name'])) {
		$sync_name = preg_replace('/[^a-zA-Z0-9_.-]/', '', (string)$state['sync_name']);
	}
	if (empty($sync_name)) {
		$result['message'] = 'Sync name is required.';
		return $result;
	}

	$cursor = '';
	if (!empty($state['cursor'])) {
		$cursor = (string)$state['cursor'];
	}

	$page = 0;
	if (!empty($state['page'])) {
		$page = (int)$state['page'];
	}

	$rows_processed = 0;
	if (!empty($state['rows_processed'])) {
		$rows_processed = (int)$state['rows_processed'];
	}

	$status = 'running';
	if (!empty($state['status'])) {
		$status = preg_replace('/[^a-z_]/', '', strtolower((string)$state['status']));
	}
	if (empty($status)) {
		$status = 'running';
	}

	$checkpoint = array(
		'sync_name' => $sync_name,
		'cursor' => $cursor,
		'page' => $page,
		'rows_processed' => $rows_processed,
		'status' => $status,
		'updated_at' => time()
	);

	$checkpoint_json = json_encode($checkpoint);
	if ($checkpoint_json === false) {
		$result['message'] = 'Checkpoint could not be encoded.';
		return $result;
	}

	$result['success'] = true;
	$result['message'] = 'Sync checkpoint built.';
	$result['data'] = array(
		'checkpoint' => $checkpoint,
		'checkpoint_json' => $checkpoint_json,
		'checkpoint_hash' => hash('sha256', $checkpoint_json)
	);

	return $result;
}