<?php
/**
 * @package PlugixaCrm
 */

declare( strict_types = 1 );

namespace PlugixaCrm\Core;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * A typed phone number turned into the one form a messaging gateway will accept, and into the one
 * form two numbers can be compared in.
 *
 * IN CORE FOR THE SAME REASON AS `WallClock` AND `Money`: it must exist exactly once. Numbers are
 * stored here exactly as somebody typed them — `ContactService::sanitize()` runs
 * `sanitize_text_field()` and nothing else — so `+44 20 7946 0958`, `(020) 7946 0958` and
 * `020-7946-0958` are three rows describing one telephone. Every consumer that has to *act* on a
 * number rather than display it needs the same two answers, and the moment a second one computes
 * them itself the two disagree about a customer's phone number.
 *
 * THIS IS NOT A PHONE NUMBER LIBRARY AND MUST NOT GROW INTO ONE. EspoCRM bundles
 * `giggsey/libphonenumber-for-php`, which carries a per-country metadata set of several megabytes
 * to answer questions this plugin never asks — is this number *allocatable*, which carrier owns it,
 * is it a mobile. A CRM sending a text needs to know how to address it, not whether it is real; the
 * gateway answers that, authoritatively, in its response. Adding the dependency would put megabytes
 * into a WordPress.org download to replace forty lines.
 *
 * @see \PlugixaCrm\Core\WallClock The same argument, for the date formats.
 */
final class PhoneNumber {

	/**
	 * E.164 permits fifteen digits after the `+`, country code included. ITU-T Recommendation E.164
	 * §6.2.1. A longer string is not a number that was typed slightly wrong; it is not a number.
	 */
	public const MAX_DIGITS = 15;

	/**
	 * The shortest thing that can still be dialled internationally — a one-digit country code plus a
	 * six-digit subscriber number. Below this a "number" is an extension, a typo, or a partial entry
	 * somebody is still in the middle of.
	 */
	public const MIN_DIGITS = 7;

	/**
	 * How many trailing digits decide that two numbers are the same telephone.
	 *
	 * NINE, AND THE REASON IS THE ONLY THING HERE WORTH ARGUING WITH. A number stored nationally
	 * (`07700 900123`) and the same number as a gateway reports it (`+447700900123`) share no prefix
	 * at all — one starts with a trunk `0` the other replaces with a country code. What they do
	 * share is the subscriber number, and nine digits is long enough that a collision needs two real
	 * telephones agreeing in their last nine digits, and short enough to survive every national
	 * formatting convention this has to read.
	 *
	 * Comparing the WHOLE digit string instead would fail on the single most common case in the
	 * table — a number typed by a person in their own country — which is the case that matters,
	 * because it is how an inbound reply finds the contact who sent it.
	 */
	public const COMPARE_DIGITS = 9;

	/**
	 * Every digit in the string, and nothing else.
	 *
	 * The stored form for comparison. Not itself dialable — `to_e164()` does that — and deliberately
	 * lossy about the `+`, because the `+` is exactly the character people omit.
	 *
	 * @param string $raw A number as somebody typed it.
	 */
	public static function digits( string $raw ): string {
		$digits = preg_replace( '/[^0-9]+/', '', $raw );

		if ( ! is_string( $digits ) ) {
			return '';
		}

		// Kept from the RIGHT: a number carrying an international access prefix ("011", "00") or a
		// stray leading zero is still the same telephone, and the tail is the part that says so.
		return strlen( $digits ) > self::MAX_DIGITS
			? substr( $digits, -self::MAX_DIGITS )
			: $digits;
	}

	/**
	 * The trailing run that decides identity. The value an inbound number is looked up by.
	 *
	 * @param string $raw A number as somebody typed it.
	 */
	public static function tail( string $raw ): string {
		$digits = self::digits( $raw );

		return strlen( $digits ) > self::COMPARE_DIGITS
			? substr( $digits, -self::COMPARE_DIGITS )
			: $digits;
	}

	/**
	 * Are these two the same telephone?
	 *
	 * @param string $a One number, in any form.
	 * @param string $b Another number, in any form.
	 */
	public static function same( string $a, string $b ): bool {
		$left  = self::tail( $a );
		$right = self::tail( $b );

		// Two empties are not a match. Without this a record with a blank phone number matches every
		// inbound message, which is the failure mode where a stranger's reply lands on a real person.
		if ( '' === $left || '' === $right ) {
			return false;
		}

		return $left === $right;
	}

	/**
	 * The E.164 form a gateway will accept, or null when the number cannot be addressed.
	 *
	 * RETURNING NULL IS THE POINT OF THIS METHOD. `07700 900123` is a complete, correct, dialable
	 * number *if you already know which country it belongs to*, and meaningless otherwise — there is
	 * no such thing as guessing it. A caller that receives null has been told to ask somebody, and
	 * that is a better outcome than a text sent to the same digits in a different country.
	 *
	 * THIS NEVER REWRITES WHAT IS STORED. `phone_numbers` carries
	 * `UNIQUE KEY link (parent_type,parent_id,number)`, so normalising the column in place would
	 * collide the day one contact holds the same telephone in two notations — and the insert that
	 * collides fails silently. The stored string stays as it was typed; this is the form used to
	 * address a message, and it lives only as long as the request that sends it.
	 *
	 * @param string $raw           A number as somebody typed it.
	 * @param string $dialling_code The country's dialling code, for a number written nationally.
	 *                              Digits, with or without a `+`. Empty when unknown.
	 */
	public static function to_e164( string $raw, string $dialling_code = '' ): ?string {
		$raw = trim( $raw );

		if ( '' === $raw ) {
			return null;
		}

		// Anything after an extension marker belongs to a switchboard, not to the public number, and
		// a gateway cannot dial it. Dropping it is right; carrying it makes the whole number invalid.
		$trimmed = preg_replace( '/\s*(?:ext\.?|x|#)\s*[0-9]+\s*$/i', '', $raw );
		$raw     = is_string( $trimmed ) ? $trimmed : $raw;

		$digits = preg_replace( '/[^0-9]+/', '', $raw );
		$digits = is_string( $digits ) ? $digits : '';

		if ( '' === $digits ) {
			return null;
		}

		if ( str_starts_with( $raw, '+' ) ) {
			// Already international. Nothing to infer.
			return self::finish( $digits );
		}

		// "00" and "011" are how the rest of the world and North America respectively write "+".
		// Both are international dialling, so the country is stated and no default is wanted.
		foreach ( array( '011', '00' ) as $access ) {
			if ( str_starts_with( $digits, $access ) ) {
				return self::finish( substr( $digits, strlen( $access ) ) );
			}
		}

		$code = preg_replace( '/[^0-9]+/', '', $dialling_code );

		if ( ! is_string( $code ) || '' === $code ) {
			// National notation and nobody has said which nation. Refuse rather than guess.
			return null;
		}

		// One leading zero is the trunk prefix, which an international number replaces rather than
		// keeps. Exactly one: "00" was handled above, and a number beginning "000" is not a number.
		if ( str_starts_with( $digits, '0' ) ) {
			$digits = substr( $digits, 1 );
		}

		return self::finish( $code . $digits );
	}

	/**
	 * Length-check a finished digit string and put the `+` back on.
	 *
	 * @param string $digits Country code and subscriber number, digits only.
	 */
	private static function finish( string $digits ): ?string {
		$length = strlen( $digits );

		if ( $length < self::MIN_DIGITS || $length > self::MAX_DIGITS ) {
			return null;
		}

		return '+' . $digits;
	}
}