Responsive Image Plan Builder

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

/**
 * Plans image variants, sizes, and target filenames without performing image processing.
 *
 * Primary use case: Asset optimization workflows.
 * Typical inputs: source image metadata, breakpoints.
 * Typical output: variant plan.
 *
 * Implementation note: Keep original file untouched.
 *
 * @return array Structured result data with success, message, and data keys.
 */
function ogBuildResponsiveImagePlan($source_filename, $metadata = array(), $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	$source_filename = basename((string)$source_filename);
	if (!is_array($metadata)) {
		$metadata = array();
	}
	if (!is_array($options)) {
		$options = array();
	}

	if (empty($source_filename)) {
		$result['message'] = 'Source filename is required.';
		return $result;
	}

	$width = 0;
	$height = 0;
	if (!empty($metadata['width'])) {
		$width = (int)$metadata['width'];
	}
	if (!empty($metadata['height'])) {
		$height = (int)$metadata['height'];
	}
	if ($width <= 0 || $height <= 0) {
		$result['message'] = 'Source width and height are required.';
		return $result;
	}

	$breakpoints = array(320, 640, 960, 1280);
	if (!empty($options['breakpoints']) && is_array($options['breakpoints'])) {
		$breakpoints = array();
		foreach ($options['breakpoints'] as $breakpoint) {
			$breakpoint = (int)$breakpoint;
			if ($breakpoint > 0) {
				$breakpoints[] = $breakpoint;
			}
		}
	}

	$formats = array('webp');
	if (!empty($options['formats']) && is_array($options['formats'])) {
		$formats = $options['formats'];
	}

	$name = pathinfo($source_filename, PATHINFO_FILENAME);
	$variants = array();
	foreach ($breakpoints as $target_width) {
		if ($target_width > $width) {
			continue;
		}
		$target_height = (int)round(($height / $width) * $target_width);
		foreach ($formats as $format) {
			$format = strtolower(trim((string)$format, '. '));
			if (!preg_match('/^[a-z0-9]+$/', $format)) {
				continue;
			}
			$variants[] = array(
				'width' => $target_width,
				'height' => $target_height,
				'format' => $format,
				'filename' => $name . '-' . $target_width . 'w.' . $format
			);
		}
	}

	$result['success'] = true;
	$result['message'] = 'Responsive image plan built.';
	$result['data'] = array(
		'source' => $source_filename,
		'original_width' => $width,
		'original_height' => $height,
		'variants' => $variants
	);

	return $result;
}