<?php
/**
 * Capability map.
 *
 * @package FormPilot
 * @since   1.0.0
 */

declare( strict_types = 1 );

namespace FormPilot\Security;

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

/**
 * Maps the plugin permissions onto WordPress capabilities.
 *
 * Every screen and every REST route asks for a plugin permission rather than a
 * hardcoded core capability, so a site can hand individual areas to other roles
 * by filtering the map instead of editing the plugin.
 *
 * @since 1.0.0
 */
final class Capabilities {

	/**
	 * Permission to create and edit forms.
	 */
	public const MANAGE_FORMS = 'formpilot_manage_forms';

	/**
	 * Permission to read and delete submissions.
	 */
	public const MANAGE_ENTRIES = 'formpilot_manage_entries';

	/**
	 * Permission to change the plugin settings.
	 */
	public const MANAGE_SETTINGS = 'formpilot_manage_settings';

	/**
	 * Permission to run the import, export and maintenance tools.
	 */
	public const USE_TOOLS = 'formpilot_use_tools';

	/**
	 * Returns the WordPress capability required for a plugin permission.
	 *
	 * @param string $permission One of the class constants.
	 */
	public static function get( string $permission ): string {
		$map = self::map();

		$capability = $map[ $permission ] ?? 'manage_options';

		/**
		 * Filters the WordPress capability required for a plugin permission.
		 *
		 * @since 1.0.0
		 *
		 * @param string $capability WordPress capability.
		 * @param string $permission Requested plugin permission.
		 */
		return (string) apply_filters( 'formpilot_capability', $capability, $permission );
	}

	/**
	 * Checks whether the current user holds a plugin permission.
	 *
	 * @param string $permission One of the class constants.
	 *
	 * @return bool True when the current user is allowed.
	 */
	public static function current_user_can( string $permission ): bool {
		return current_user_can( self::get( $permission ) );
	}

	/**
	 * Stops the request when the current user lacks a permission.
	 *
	 * @param string $permission One of the class constants.
	 * @param string $message    Optional. Message shown to the user. Default ''.
	 */
	public static function require( string $permission, string $message = '' ): void {
		if ( self::current_user_can( $permission ) ) {
			return;
		}

		if ( '' === $message ) {
			$message = __( 'You do not have permission to perform this action.', 'devplugins-custom-form-builder' );
		}

		wp_die(
			esc_html( $message ),
			esc_html__( 'Permission denied', 'devplugins-custom-form-builder' ),
			array( 'response' => 403 )
		);
	}

	/**
	 * Returns every registered permission.
	 *
	 * @return array<int, string> The permission names.
	 */
	public static function all(): array {
		return array_keys( self::map() );
	}

	/**
	 * Returns the default permission map.
	 *
	 * @return array<string, string> WordPress capabilities keyed by plugin permission.
	 */
	private static function map(): array {
		return array(
			self::MANAGE_FORMS    => 'manage_options',
			self::MANAGE_ENTRIES  => 'manage_options',
			self::MANAGE_SETTINGS => 'manage_options',
			self::USE_TOOLS       => 'manage_options',
		);
	}
}