Audit Trail Formatter

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

/**
 * Formats admin/user activity logs into consistent human-readable and machine-readable records.
 *
 * Primary use case: Admin logs and compliance history.
 * Typical inputs: actor id, action, target, metadata.
 * Typical output: audit entry array/string.
 *
 * Implementation note: Store raw machine data and rendered display safely.
 *
 * @param int $actor_id User/admin ID responsible for the action.
 * @param string $action Action name.
 * @param string $target_type Target resource type.
 * @param int $target_id Target resource ID.
 * @param array $metadata Additional audit metadata.
 * @return array Structured result data with success, message, and data keys.
 */
function ogFormatAuditTrailEntry($actor_id, $action, $target_type, $target_id = 0, $metadata = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	$actor_id = (int)$actor_id;
	$action = trim((string)$action);
	$target_type = trim((string)$target_type);
	$target_id = (int)$target_id;
	if (!is_array($metadata)) {
		$metadata = array();
	}

	if ($actor_id <= 0) {
		$result['message'] = 'Audit actor ID is required.';
		return $result;
	}
	if (empty($action) || !preg_match('/^[A-Za-z0-9_.:-]+$/', $action)) {
		$result['message'] = 'Audit action is invalid.';
		return $result;
	}
	if (empty($target_type) || !preg_match('/^[A-Za-z0-9_.:-]+$/', $target_type)) {
		$result['message'] = 'Audit target type is invalid.';
		return $result;
	}

	$redacted_metadata = array();
	foreach ($metadata as $key => $value) {
		$key = (string)$key;
		if (preg_match('/password|token|secret|api[_-]?key|cookie/i', $key)) {
			$redacted_metadata[$key] = '[redacted]';
		} else {
			$redacted_metadata[$key] = $value;
		}
	}

	$display = 'Actor #' . $actor_id . ' performed ' . $action . ' on ' . $target_type;
	if ($target_id > 0) {
		$display .= ' #' . $target_id;
	}

	$result['success'] = true;
	$result['message'] = 'Audit trail entry formatted.';
	$result['data'] = array(
		'actor_id' => $actor_id,
		'action' => $action,
		'target_type' => $target_type,
		'target_id' => $target_id,
		'metadata' => $redacted_metadata,
		'display' => $display,
		'created_at' => date('Y-m-d H:i:s')
	);

	return $result;
}