<?php
/**
 * The plugin's capabilities and the roles they are granted to.
 *
 * Two jobs are deliberately kept apart, mirroring the Drupal module's
 * `administer mapsemble` / `edit mapsemble map data` split:
 *
 * - configuring maps and holding the API credentials, and
 * - maintaining the locations shown on a hosted map.
 *
 * The second is content work. The person doing it should not need the screen
 * that holds the client secret, so `edit_mapsemble_map_data` is granted to
 * editors and is never implied by the administrative capabilities.
 *
 * @package Mapsemble
 */

namespace Mapsemble;

/**
 * Capability definitions plus the activation-time role grants.
 */
final class Capabilities {

	/**
	 * Option holding the roles' capability grants across a deactivate cycle.
	 *
	 * Written by revoke(), consumed (and deleted) by the next grant(). Saved
	 * without autoload: it exists only between a deactivation and the next
	 * activation, and is read exactly once.
	 */
	public const SNAPSHOT_OPTION = 'mapsemble_custom_role_caps';

	/**
	 * Gates the credentials screen.
	 */
	public const MANAGE = 'manage_mapsemble';

	/**
	 * Gates the in-WordPress data editor for hosted maps.
	 *
	 * Opening that editor signs the user in to the connected Mapsemble account
	 * with this site's API credentials, which they never see. The session it
	 * opens is scoped to the one map and confined to the embedded editor for
	 * its whole life, so it reaches no other map and no part of the account.
	 */
	public const EDIT_MAP_DATA = 'edit_mapsemble_map_data';

	/**
	 * The primitive capability WordPress derives `edit_post` from for maps.
	 *
	 * Named separately because the admin menu and several screens test it
	 * directly rather than through a post id.
	 */
	public const EDIT_MAPS = 'edit_mapsemble_maps';

	/**
	 * Every primitive capability the `mapsemble_map` post type derives from.
	 *
	 * Generated by WordPress from `capability_type` + `map_meta_cap`; listed
	 * here because roles are granted primitives, not meta capabilities.
	 *
	 * @var string[]
	 */
	private const POST_TYPE_CAPS = array(
		'edit_mapsemble_maps',
		'edit_others_mapsemble_maps',
		'edit_private_mapsemble_maps',
		'edit_published_mapsemble_maps',
		'publish_mapsemble_maps',
		'read_private_mapsemble_maps',
		'delete_mapsemble_maps',
		'delete_others_mapsemble_maps',
		'delete_private_mapsemble_maps',
		'delete_published_mapsemble_maps',
	);

	/**
	 * Every capability this plugin defines.
	 *
	 * @return string[]
	 */
	public static function all(): array {
		return array_merge(
			array( self::MANAGE, self::EDIT_MAP_DATA ),
			self::POST_TYPE_CAPS
		);
	}

	/**
	 * Grants the capabilities to the default roles. Runs on activation.
	 *
	 * Administrators get everything, data editing included: an administrator
	 * who could configure a map but not open its editor would be a puzzle, not
	 * a safeguard. Editors get data editing only — the whole point of the
	 * split.
	 *
	 * After the stock grants, any snapshot the last revoke() left behind is
	 * restored and deleted. Deactivation is often temporary — a debugging
	 * step, an update gone sideways — and a grant a site made itself must
	 * survive it. Re-adding a capability a role already holds is a no-op, so
	 * restoring over the stock grants is safe.
	 */
	public static function grant(): void {
		$admin = get_role( 'administrator' );
		if ( null !== $admin ) {
			foreach ( self::all() as $cap ) {
				$admin->add_cap( $cap );
			}
		}

		$editor = get_role( 'editor' );
		if ( null !== $editor ) {
			$editor->add_cap( self::EDIT_MAP_DATA );
		}

		$snapshot = get_option( self::SNAPSHOT_OPTION );
		if ( is_array( $snapshot ) ) {
			foreach ( $snapshot as $role_name => $caps ) {
				$role = get_role( (string) $role_name );
				if ( null === $role || ! is_array( $caps ) ) {
					continue;
				}
				foreach ( array_intersect( $caps, self::all() ) as $cap ) {
					$role->add_cap( $cap );
				}
			}
		}
		delete_option( self::SNAPSHOT_OPTION );
	}

	/**
	 * Removes the capabilities from every role. Runs on deactivation.
	 *
	 * Swept across all roles rather than the two we granted to, because a site
	 * may have handed `edit_mapsemble_map_data` to a role of its own and a
	 * capability left behind after deactivation is a capability nothing
	 * documents.
	 *
	 * Before the sweep, every role's plugin capabilities are snapshotted to an
	 * option for the next grant() to restore — all roles, the stock ones
	 * included, because a site may have added to those too and the sweep alone
	 * would silently erase its choices. The roles themselves still end the
	 * sweep holding nothing, so a deactivated plugin leaves no capability
	 * behind; only uninstall (which deletes the option) forgets the grants.
	 */
	public static function revoke(): void {
		$snapshot = array();
		foreach ( wp_roles()->role_objects as $role_name => $role ) {
			$held = array_values(
				array_filter(
					self::all(),
					static fn ( string $cap ): bool => $role->has_cap( $cap )
				)
			);
			if ( array() !== $held ) {
				$snapshot[ $role_name ] = $held;
			}
		}
		if ( array() !== $snapshot ) {
			update_option( self::SNAPSHOT_OPTION, $snapshot, false );
		}

		foreach ( wp_roles()->role_objects as $role ) {
			foreach ( self::all() as $cap ) {
				$role->remove_cap( $cap );
			}
		}
	}

	/**
	 * The capability the top-level Mapsemble menu is registered with.
	 *
	 * The menu holds screens with three different capabilities, and WordPress
	 * accepts only one for the parent. Returning the first the current user
	 * actually holds shows the menu to anyone with any business inside it,
	 * while the fallback hides it from everyone else — a plain
	 * `edit_mapsemble_maps` would hide the whole menu from the data editors
	 * the `Maps` screen exists for.
	 */
	public static function menu_cap(): string {
		foreach ( array( self::EDIT_MAP_DATA, self::EDIT_MAPS, self::MANAGE ) as $cap ) {
			if ( current_user_can( $cap ) ) {
				return $cap;
			}
		}
		return self::EDIT_MAP_DATA;
	}
}