Lead Source Attribution

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

/**
 * Assigns lead records to source channels using UTM, referrer, and landing page data.
 *
 * @param array $leads Lead records.
 * @param array $options Options: channel_rules map.
 * @return array Lead attribution report.
 */
function ogAttributeLeadSources($leads = array(), $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

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

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

	$channel_rules = array(
		'google' => 'search',
		'bing' => 'search',
		'facebook' => 'social',
		'instagram' => 'social',
		'linkedin' => 'social',
		'youtube' => 'video',
		'newsletter' => 'email'
	);
	if (!empty($options['channel_rules']) && is_array($options['channel_rules'])) {
		$channel_rules = array_merge($channel_rules, $options['channel_rules']);
	}

	$attributed = array();
	$channel_counts = array();
	foreach ($leads as $index => $lead) {
		if (!is_array($lead)) {
			continue;
		}

		$source_text = '';
		if (!empty($lead['utm_source'])) {
			$source_text .= ' ' . strtolower((string)$lead['utm_source']);
		}
		if (!empty($lead['referrer'])) {
			$source_text .= ' ' . strtolower((string)$lead['referrer']);
		}
		if (!empty($lead['landing_page'])) {
			$source_text .= ' ' . strtolower((string)$lead['landing_page']);
		}

		$channel = 'direct-or-unknown';
		foreach ($channel_rules as $needle => $mapped_channel) {
			if (!empty($needle) && strpos($source_text, strtolower((string)$needle)) !== false) {
				$channel = (string)$mapped_channel;
				break;
			}
		}

		if (empty($channel_counts[$channel])) {
			$channel_counts[$channel] = 0;
		}
		$channel_counts[$channel]++;

		$lead['attributed_channel'] = $channel;
		$lead['attribution_index'] = $index;
		$attributed[] = $lead;
	}

	arsort($channel_counts);

	$result['success'] = true;
	$result['message'] = 'Lead sources attributed.';
	$result['data'] = array(
		'leads' => $attributed,
		'channel_counts' => $channel_counts
	);

	return $result;
}