Upload Safety Inspector

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

/**
 * Checks uploaded file size, extension, MIME, image headers, and storage eligibility.
 *
 * Primary use case: Image/file upload endpoints.
 * Typical inputs: $_FILES entry, allowed types, size limit.
 * Typical output: safe file metadata or error list.
 *
 * Implementation note: Rename files; never trust client filename or MIME alone.
 *
 * @param array $file Uploaded file entry.
 * @param array $options Allowed extensions, MIME types, and size limits.
 * @return array Structured result data with success, message, and data keys.
 */
function ogInspectUploadedFile($file, $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

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

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

	$allowed_extensions = array('jpg', 'jpeg', 'png', 'gif', 'webp', 'pdf', 'txt', 'csv');
	if (!empty($options['allowed_extensions']) && is_array($options['allowed_extensions'])) {
		$allowed_extensions = array();
		foreach ($options['allowed_extensions'] as $extension) {
			$allowed_extensions[] = strtolower(trim((string)$extension));
		}
	}

	$max_bytes = 5242880;
	if (!empty($options['max_bytes'])) {
		$max_bytes = (int)$options['max_bytes'];
	}

	$error = 0;
	if (isset($file['error'])) {
		$error = (int)$file['error'];
	}
	if ($error !== UPLOAD_ERR_OK) {
		$result['message'] = 'Upload error code: ' . $error;
		return $result;
	}

	$name = '';
	if (!empty($file['name'])) {
		$name = (string)$file['name'];
	}
	$tmp_name = '';
	if (!empty($file['tmp_name'])) {
		$tmp_name = (string)$file['tmp_name'];
	}
	$size = 0;
	if (!empty($file['size'])) {
		$size = (int)$file['size'];
	}

	if (empty($name) || empty($tmp_name)) {
		$result['message'] = 'Missing upload filename or temporary path.';
		return $result;
	}

	if ($size <= 0 || $size > $max_bytes) {
		$result['message'] = 'Uploaded file size is outside the allowed range.';
		return $result;
	}

	$extension = strtolower(pathinfo($name, PATHINFO_EXTENSION));
	if (empty($extension) || !in_array($extension, $allowed_extensions, true)) {
		$result['message'] = 'Uploaded file extension is not allowed.';
		return $result;
	}

	$mime_type = '';
	if (function_exists('finfo_open') && is_file($tmp_name)) {
		$finfo = finfo_open(FILEINFO_MIME_TYPE);
		if (!empty($finfo)) {
			$mime_type = (string)finfo_file($finfo, $tmp_name);
			finfo_close($finfo);
		}
	}

	$image_info = array();
	if (is_file($tmp_name)) {
		$raw_image_info = @getimagesize($tmp_name);
		if (is_array($raw_image_info)) {
			$image_info = array(
				'width' => (int)$raw_image_info[0],
				'height' => (int)$raw_image_info[1],
				'mime' => (string)$raw_image_info['mime']
			);
		}
	}

	$safe_name = bin2hex(random_bytes(16)) . '.' . $extension;
	$result['success'] = true;
	$result['message'] = 'Uploaded file inspected.';
	$result['data'] = array(
		'original_name' => basename($name),
		'safe_name' => $safe_name,
		'extension' => $extension,
		'size' => $size,
		'mime_type' => $mime_type,
		'image_info' => $image_info
	);

	return $result;
}