Temporary File Quarantine

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

/**
 * Moves an uploaded file into a temporary quarantine path for validation before public exposure.
 *
 * Primary use case: Safer product images, documents, imports.
 * Typical inputs: uploaded file path, quarantine path, random name options.
 * Typical output: quarantine record.
 *
 * Implementation note: Keep outside public web root when possible.
 *
 * @param array $file Uploaded file entry.
 * @param string $quarantine_dir Approved quarantine directory.
 * @param array $options Quarantine options.
 * @return array Structured result data with success, message, and data keys.
 */
function ogQuarantineUploadFile($file, $quarantine_dir, $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

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

	$quarantine_dir = rtrim((string)$quarantine_dir, '/\\');
	if (empty($quarantine_dir) || !is_dir($quarantine_dir) || !is_writable($quarantine_dir)) {
		$result['message'] = 'Quarantine directory is not available.';
		return $result;
	}

	$tmp_name = '';
	if (!empty($file['tmp_name'])) {
		$tmp_name = (string)$file['tmp_name'];
	}
	if (empty($tmp_name) || !is_file($tmp_name)) {
		$result['message'] = 'Temporary upload file is missing.';
		return $result;
	}

	$extension = 'bin';
	if (!empty($file['name'])) {
		$detected_extension = strtolower(pathinfo((string)$file['name'], PATHINFO_EXTENSION));
		if (preg_match('/^[a-z0-9]{1,12}$/', $detected_extension)) {
			$extension = $detected_extension;
		}
	}

	$quarantine_name = bin2hex(random_bytes(20)) . '.' . $extension;
	$target_path = $quarantine_dir . DIRECTORY_SEPARATOR . $quarantine_name;

	$allow_local_file = false;
	if (!empty($options['allow_local_file'])) {
		$allow_local_file = true;
	}

	$moved = false;
	if (is_uploaded_file($tmp_name)) {
		$moved = move_uploaded_file($tmp_name, $target_path);
	} else {
		if ($allow_local_file) {
			$moved = rename($tmp_name, $target_path);
		}
	}

	if (!$moved) {
		$result['message'] = 'Uploaded file could not be moved into quarantine.';
		return $result;
	}

	$result['success'] = true;
	$result['message'] = 'Uploaded file quarantined.';
	$result['data'] = array(
		'quarantine_name' => $quarantine_name,
		'quarantine_path' => $target_path,
		'size' => filesize($target_path)
	);

	return $result;
}