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

/**
 * Reads image dimensions and orientation metadata for validation/display planning.
 *
 * Primary use case: Image uploads and responsive layouts.
 * Typical inputs: image path.
 * Typical output: dimension metadata.
 *
 * Implementation note: Validate file before reading metadata.
 *
 * @return array Structured result data with success, message, and data keys.
 */
function ogInspectImageDimensions($file_path, $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

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

	$real_path = realpath($file_path);
	if ($real_path === false || !is_file($real_path)) {
		$result['message'] = 'Image file was not found.';
		return $result;
	}
	if (is_link($real_path)) {
		$result['message'] = 'Symbolic links are not accepted for image inspection.';
		return $result;
	}

	$max_bytes = 10485760;
	if (!empty($options['max_bytes'])) {
		$max_bytes = (int)$options['max_bytes'];
	}
	$file_size = filesize($real_path);
	if ($file_size === false || $file_size > $max_bytes) {
		$result['message'] = 'Image file is too large or unreadable.';
		return $result;
	}

	$image_data = getimagesize($real_path);
	if ($image_data === false) {
		$result['message'] = 'File is not a readable image.';
		return $result;
	}

	$mime = '';
	if (!empty($image_data['mime'])) {
		$mime = $image_data['mime'];
	}

	$allowed_mimes = array('image/jpeg', 'image/png', 'image/gif', 'image/webp');
	if (!empty($options['allowed_mimes']) && is_array($options['allowed_mimes'])) {
		$allowed_mimes = $options['allowed_mimes'];
	}
	if (!in_array($mime, $allowed_mimes, true)) {
		$result['message'] = 'Image MIME type is not allowed.';
		return $result;
	}

	$aspect_ratio = 0;
	if ($image_data[1] > 0) {
		$aspect_ratio = round($image_data[0] / $image_data[1], 4);
	}

	$result['success'] = true;
	$result['message'] = 'Image dimensions inspected.';
	$result['data'] = array(
		'path' => $real_path,
		'width' => (int)$image_data[0],
		'height' => (int)$image_data[1],
		'mime' => $mime,
		'bytes' => (int)$file_size,
		'aspect_ratio' => $aspect_ratio
	);

	return $result;
}