Double Opt In Manager

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

/**
 * Creates email verification requests with tokens, expiry, and resend metadata.
 *
 * Primary use case: Newsletter or account verification.
 * Typical inputs: email, scope, ttl.
 * Typical output: verification request data.
 *
 * Implementation note: Store hashed tokens and rate-limit resends.
 *
 * @param array $input Structured input values for this helper contract.
 * @param array $options Optional policy and formatting controls.
 * @return array Structured result data with success, message, and data keys.
 */
function ogBuildDoubleOptInRequest($input = array(), $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

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

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

	$email = '';
	if (!empty($input['email'])) {
		$email = strtolower(trim((string)$input['email']));
	}
	$scope = 'default';
	if (!empty($input['scope'])) {
		$scope = preg_replace('/[^a-zA-Z0-9_-]/', '', (string)$input['scope']);
	}
	$base_url = '';
	if (!empty($input['base_url'])) {
		$base_url = trim((string)$input['base_url']);
	}
	$ttl_seconds = 86400;
	if (!empty($input['ttl_seconds'])) {
		$ttl_seconds = (int)$input['ttl_seconds'];
	}

	if (filter_var($email, FILTER_VALIDATE_EMAIL) === false) {
		$result['message'] = 'Valid email address is required.';
		return $result;
	}
	if ($ttl_seconds < 300) {
		$ttl_seconds = 300;
	}
	if (empty($base_url) || preg_match('/[\r\n]/', $base_url)) {
		$result['message'] = 'Safe base URL is required.';
		return $result;
	}

	$token = bin2hex(random_bytes(32));
	$token_hash = password_hash($token, PASSWORD_DEFAULT);
	$query = 'email=' . rawurlencode($email) . '&scope=' . rawurlencode($scope) . '&token=' . rawurlencode($token);
	$separator = '?';
	if (strpos($base_url, '?') !== false) {
		$separator = '&';
	}

	$result['success'] = true;
	$result['message'] = 'Double opt-in request built.';
	$result['data'] = array(
		'email' => $email,
		'scope' => $scope,
		'token' => $token,
		'token_hash' => $token_hash,
		'expires_at' => time() + $ttl_seconds,
		'verification_url' => $base_url . $separator . $query
	);

	return $result;
}