File Name Sanitizer

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

/**
 * Creates a safe randomized storage filename from an original uploaded filename.
 *
 * @param string $original_filename Original client filename.
 * @param array $allowed_extensions Allowed lowercase file extensions.
 * @param string $prefix Optional filename prefix.
 * @return array Safe filename result.
 */
function ogSanitizeStorageFileName($original_filename, $allowed_extensions = array(), $prefix = 'file') {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	$original_filename = trim((string)$original_filename);
	$prefix = strtolower(trim((string)$prefix));
	$prefix = preg_replace('/[^a-z0-9_\-]+/', '-', $prefix);
	$prefix = trim($prefix, '-');

	if (empty($prefix)) {
		$prefix = 'file';
	}

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

	if (empty($original_filename)) {
		$result['message'] = 'Missing original filename.';
		return $result;
	}

	$basename = basename(str_replace('\\', '/', $original_filename));
	$extension = strtolower(pathinfo($basename, PATHINFO_EXTENSION));

	if (empty($extension)) {
		$result['message'] = 'Filename extension is required.';
		return $result;
	}

	if (!preg_match('/^[a-z0-9]{1,12}$/', $extension)) {
		$result['message'] = 'Filename extension is invalid.';
		return $result;
	}

	if (!empty($allowed_extensions) && !in_array($extension, $allowed_extensions, true)) {
		$result['message'] = 'Filename extension is not allowed.';
		return $result;
	}

	$random = bin2hex(random_bytes(16));
	$safe_filename = $prefix . '-' . date('YmdHis') . '-' . $random . '.' . $extension;

	$result['success'] = true;
	$result['message'] = 'Storage filename created.';
	$result['data'] = array(
		'filename' => $safe_filename,
		'extension' => $extension,
		'original_basename' => $basename
	);

	return $result;
}