File Integrity Checker

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

/**
 * Verifies file checksums against a stored manifest.
 *
 * Primary use case: Deployment and backup verification.
 * Typical inputs: manifest, base path.
 * Typical output: integrity report.
 *
 * Implementation note: Use strong hashes and protect manifest.
 *
 * @return array Structured result data with success, message, and data keys.
 */
function ogCheckFileIntegrity($base_path, $manifest = array(), $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	$base_path = (string)$base_path;
	if (!is_array($manifest)) {
		$result['message'] = 'Manifest must be an array.';
		return $result;
	}
	if (!is_array($options)) {
		$options = array();
	}

	$base_real = realpath($base_path);
	if ($base_real === false || !is_dir($base_real)) {
		$result['message'] = 'Approved base path is missing or is not a directory.';
		return $result;
	}

	$matched = array();
	$changed = array();
	$missing = array();
	$invalid = array();

	foreach ($manifest as $entry) {
		if (!is_array($entry) || empty($entry['path']) || empty($entry['checksum'])) {
			$invalid[] = $entry;
			continue;
		}

		$relative_path = (string)$entry['path'];
		$algorithm = 'sha256';
		if (!empty($entry['hash_algorithm'])) {
			$algorithm = strtolower((string)$entry['hash_algorithm']);
		}
		if (!in_array($algorithm, hash_algos(), true)) {
			$invalid[] = $entry;
			continue;
		}

		$safe_path = ogResolveSafePath($base_real, $relative_path, array('must_exist' => true));
		if (empty($safe_path['success'])) {
			$missing[] = $relative_path;
			continue;
		}

		$file_path = $safe_path['data']['safe_path'];
		if (!is_file($file_path)) {
			$missing[] = $relative_path;
			continue;
		}

		$current_checksum = hash_file($algorithm, $file_path);
		if (hash_equals((string)$entry['checksum'], $current_checksum)) {
			$matched[] = $relative_path;
		} else {
			$changed[] = array(
				'path' => $relative_path,
				'expected' => (string)$entry['checksum'],
				'actual' => $current_checksum
			);
		}
	}

	$result['success'] = true;
	$result['message'] = 'File integrity check completed.';
	$result['data'] = array(
		'matched' => $matched,
		'changed' => $changed,
		'missing' => $missing,
		'invalid' => $invalid,
		'passed' => empty($changed) && empty($missing) && empty($invalid)
	);

	return $result;
}