<?php
/**
 * AJAX Exception Class.
 *
 * Custom exception for AJAX handlers that supports HTTP status codes and
 * custom error codes for frontend handling.
 *
 * @package   Agenistrator
 * @since     1.0.0
 * @author    Alex Ruban <alex@maximum.guru>
 * @author    Maximum Software Inc <contact@maximum.software>
 * @license   GPL-3.0-only
 * @link      https://agenistrator.com/
 *
 * SPDX-FileCopyrightText: 2025-2026 Alex Ruban <alex@maximum.guru>
 * SPDX-FileCopyrightText: 2025-2026 Maximum Software Inc <contact@maximum.software>
 * SPDX-License-Identifier: GPL-3.0-only
 */

namespace Agenistrator;

// Exit if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Ajax_Exception class.
 *
 * Usage:
 *   throw new Ajax_Exception( 'Permission denied', 403 );
 *   throw new Ajax_Exception( 'Thread busy', 409, 'thread_busy' );
 *   throw new Ajax_Exception( 'Invalid input', 400 );
 *   throw new Ajax_Exception( 'Unexpected error' ); // defaults to 500
 */
class Ajax_Exception extends \Exception {

	/**
	 * Custom error code for frontend handling
	 *
	 * @var string
	 */
	private string $error_code;

	/**
	 * Constructor
	 *
	 * @param string $message     Error message.
	 * @param int    $http_status HTTP status code (default 500).
	 * @param string $error_code  Custom error code for frontend (optional).
	 * @since     1.0.0
	 */
	public function __construct( string $message, int $http_status = 500, string $error_code = '' ) {
		parent::__construct( $message, $http_status );
		$this->error_code = $error_code;
	}

	/**
	 * Get the HTTP status code
	 *
	 * @return int HTTP status code.
	 * @since     1.0.0
	 */
	public function get_http_status(): int {
		return $this->getCode();
	}

	/**
	 * Get the custom error code
	 *
	 * @return string Custom error code for frontend handling.
	 * @since     1.0.0
	 */
	public function get_error_code(): string {
		return $this->error_code;
	}
}