Maintenance Mode Gate

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

/**
 * Allows only approved admins or IPs through during maintenance while showing safe public responses.
 *
 * Primary use case: Deployment and repair windows.
 * Typical inputs: request path, user state, IP allowlist.
 * Typical output: allow/maintenance response.
 *
 * Implementation note: Never disclose internal maintenance details to public users.
 *
 * @param string $request_path Current request path.
 * @param array $user_state User/admin state data.
 * @param array $allowed_ips Approved maintenance bypass IP list.
 * @param array $options Optional public message and allowed paths.
 * @return array Structured maintenance access result.
 */
function ogCheckMaintenanceAccess($request_path, $user_state = array(), $allowed_ips = array(), $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array('allowed' => false)
	);

	$request_path = trim((string)$request_path);
	if (!is_array($user_state)) {
		$user_state = array();
	}
	if (!is_array($allowed_ips)) {
		$allowed_ips = array();
	}
	if (!is_array($options)) {
		$options = array();
	}

	$client_ip = '';
	if (!empty($user_state['ip'])) {
		$client_ip = trim((string)$user_state['ip']);
	}

	$is_admin = false;
	if (!empty($user_state['is_admin'])) {
		$is_admin = true;
	}

	$allowed = false;
	$reason = 'Maintenance mode is active.';

	if ($is_admin) {
		$allowed = true;
		$reason = 'Administrator bypass allowed.';
	}

	if (!$allowed && !empty($client_ip)) {
		foreach ($allowed_ips as $allowed_ip) {
			$allowed_ip = trim((string)$allowed_ip);
			if (!empty($allowed_ip) && hash_equals($allowed_ip, $client_ip)) {
				$allowed = true;
				$reason = 'IP bypass allowed.';
			}
		}
	}

	if (!$allowed && !empty($options['allowed_paths']) && is_array($options['allowed_paths'])) {
		foreach ($options['allowed_paths'] as $allowed_path) {
			$allowed_path = (string)$allowed_path;
			if (!empty($allowed_path) && strpos($request_path, $allowed_path) === 0) {
				$allowed = true;
				$reason = 'Path bypass allowed.';
			}
		}
	}

	$public_message = 'Site maintenance is in progress.';
	if (!empty($options['public_message'])) {
		$public_message = (string)$options['public_message'];
	}

	$result['success'] = true;
	$result['message'] = $reason;
	$result['data'] = array(
		'allowed' => $allowed,
		'request_path' => $request_path,
		'public_message' => $public_message
	);

	return $result;
}