Churn Risk Scorer

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

/**
 * Scores users or customers by inactivity, decline, failed payments, and support signals.
 *
 * @param array $customer Customer activity/risk record.
 * @param array $options Optional key: weights.
 * @return array Risk score, risk level, and reason list.
 */
function ogScoreChurnRisk($customer = array(), $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

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

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

	$weights = array(
		'inactivity_days' => 0.4,
		'failed_payments' => 15,
		'support_tickets' => 4,
		'revenue_decline_percent' => 0.5
	);
	if (!empty($options['weights']) && is_array($options['weights'])) {
		foreach ($options['weights'] as $key => $value) {
			if (isset($weights[$key]) && is_numeric($value)) {
				$weights[$key] = (float)$value;
			}
		}
	}

	$score = 0;
	$reasons = array();
	foreach ($weights as $field => $weight) {
		$value = 0;
		if (isset($customer[$field]) && is_numeric($customer[$field])) {
			$value = (float)$customer[$field];
		}
		if ($value > 0) {
			$score += ($value * $weight);
			$reasons[] = $field . ':' . $value;
		}
	}

	if ($score > 100) {
		$score = 100;
	}

	$level = 'low';
	if ($score >= 70) {
		$level = 'high';
	} elseif ($score >= 40) {
		$level = 'medium';
	}

	$result['success'] = true;
	$result['message'] = 'Churn risk scored.';
	$result['data'] = array(
		'score' => $score,
		'level' => $level,
		'reasons' => $reasons,
		'weights' => $weights
	);

	return $result;
}