Log Rotation Planner

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 log rotation by size, date, compression, and retention rules.
 *
 * Primary use case: Custom app logging.
 * Typical inputs: log path, retention policy.
 * Typical output: rotation plan.
 *
 * Implementation note: Avoid rotating active file without lock strategy.
 *
 * @return array Structured result data with success, message, and data keys.
 */
function ogPlanLogRotation($log_path, $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

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

	$base_path = '';
	if (!empty($options['base_path'])) {
		$base_path = (string)$options['base_path'];
	}
	if (!empty($base_path)) {
		$safe_path = ogResolveSafePath($base_path, $log_path, array('must_exist' => true));
		if (empty($safe_path['success'])) {
			$result['message'] = $safe_path['message'];
			return $result;
		}
		$log_real = $safe_path['data']['safe_path'];
	} else {
		$log_real = realpath($log_path);
		if ($log_real === false) {
			$result['message'] = 'Log file does not exist.';
			return $result;
		}
	}

	if (!is_file($log_real) || is_link($log_real)) {
		$result['message'] = 'Log path must be a regular file.';
		return $result;
	}

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

	$retention_count = 7;
	if (!empty($options['retention_count'])) {
		$retention_count = (int)$options['retention_count'];
	}
	if ($retention_count < 1) {
		$retention_count = 1;
	}

	$size = filesize($log_real);
	if ($size === false) {
		$size = 0;
	}

	$rotation_needed = false;
	if ($size >= $max_bytes) {
		$rotation_needed = true;
	}

	$archive_name = basename($log_real) . '.' . date('Ymd-His') . '.log';
	if (!empty($options['compress']) && $options['compress'] === true) {
		$archive_name .= '.gz';
	}

	$result['success'] = true;
	$result['message'] = 'Log rotation plan built.';
	$result['data'] = array(
		'log_path' => $log_real,
		'current_bytes' => $size,
		'max_bytes' => $max_bytes,
		'rotation_needed' => $rotation_needed,
		'archive_name' => $archive_name,
		'retention_count' => $retention_count,
		'actions' => array('lock', 'rename-or-copy', 'create-empty-log', 'apply-retention')
	);

	return $result;
}