Search Term Analyzer

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

/**
 * Groups internal search terms by frequency, zero-result rate, and conversion signal.
 *
 * @param array $search_logs Search log rows with term/results/conversions fields.
 * @param array $options Optional keys: term_key, results_key, conversion_key.
 * @return array Search term analytics report.
 */
function ogAnalyzeSearchTerms($search_logs = array(), $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	if (!is_array($search_logs)) {
		$result['message'] = 'Search logs must be an array.';
		return $result;
	}

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

	$term_key = 'term';
	$results_key = 'results_count';
	$conversion_key = 'conversions';
	if (!empty($options['term_key'])) {
		$term_key = (string)$options['term_key'];
	}
	if (!empty($options['results_key'])) {
		$results_key = (string)$options['results_key'];
	}
	if (!empty($options['conversion_key'])) {
		$conversion_key = (string)$options['conversion_key'];
	}

	$terms = array();
	foreach ($search_logs as $row) {
		if (!is_array($row) || empty($row[$term_key])) {
			continue;
		}
		$term = strtolower(trim((string)$row[$term_key]));
		$term = preg_replace('/\s+/', ' ', $term);
		if (strlen($term) < 2) {
			continue;
		}
		if (empty($terms[$term])) {
			$terms[$term] = array('term' => $term, 'searches' => 0, 'zero_result_searches' => 0, 'conversions' => 0);
		}
		$terms[$term]['searches']++;
		$results_count = 0;
		if (isset($row[$results_key]) && is_numeric($row[$results_key])) {
			$results_count = (int)$row[$results_key];
		}
		if ($results_count <= 0) {
			$terms[$term]['zero_result_searches']++;
		}
		if (isset($row[$conversion_key]) && is_numeric($row[$conversion_key])) {
			$terms[$term]['conversions'] += (int)$row[$conversion_key];
		}
	}

	foreach ($terms as $term => $row) {
		$zero_rate = 0;
		$conversion_rate = 0;
		if ($row['searches'] > 0) {
			$zero_rate = ($row['zero_result_searches'] / $row['searches']) * 100;
			$conversion_rate = ($row['conversions'] / $row['searches']) * 100;
		}
		$terms[$term]['zero_result_rate'] = $zero_rate;
		$terms[$term]['conversion_rate'] = $conversion_rate;
	}

	$result['success'] = true;
	$result['message'] = 'Search terms analyzed.';
	$result['data'] = array('terms' => array_values($terms));

	return $result;
}