<?php
/**
 * Installation Lockdown.
 *
 * Stops new code arriving: no plugins or themes installed or uploaded. Updates keep working.
 *
 * Update capabilities are deliberately never denied. Without update_plugins / update_themes WordPress
 * hides every pending update — security releases included — and refuses to apply them, which the
 * wordpress.org plugin review team ruled out on 2026-09-14.
 *
 * Deliberately implemented by filtering capabilities rather than by defining DISALLOW_FILE_MODS.
 * The constant is all-or-nothing, cannot be scoped, and — living in wp-config.php — cannot be
 * switched off from the admin, which strands the person who enabled it. This can always be
 * turned back off from the settings screen, which is guarded by manage_options and is never
 * touched by the lockdown.
 *
 * Honest limits, stated in the readme too: this is enforced in PHP. Anyone with filesystem,
 * database or WP-CLI access can bypass it. It guards against accident and casual change. It is
 * not a security boundary.
 *
 * @package Adminkeep
 */

namespace Adminkeep\Feature;

use Adminkeep\Feature;

defined( 'ABSPATH' ) || exit;

/**
 * Capability-level lock on installing and uploading.
 */
class InstallLock implements Feature {

	/**
	 * Capabilities that add something new to the site. The only ones denied while locked.
	 *
	 * @var string[]
	 */
	const ADDITIVE_CAPS = array(
		'install_plugins',
		'upload_plugins',
		'install_themes',
		'upload_themes',
	);

	/**
	 * Feature id.
	 *
	 * @return string
	 */
	public function id() {
		return 'install_lock';
	}

	/**
	 * Label.
	 *
	 * @return string
	 */
	public function label() {
		return __( 'Installation Lockdown', 'adminkeep' );
	}

	/**
	 * Description.
	 *
	 * @return string
	 */
	public function description() {
		return __( 'Stop anyone installing or uploading plugins and themes. Updates keep working, activating what is already installed still works, and you can switch this off again at any time.', 'adminkeep' );
	}

	/**
	 * Settings schema.
	 *
	 * @return array
	 */
	public function settings_schema() {
		return array();
	}

	/**
	 * Field label. Render-time only, so translation is safe here.
	 *
	 * @param string $key Field key.
	 * @return string
	 */
	public function field_label( $key ) {
		return '';
	}

	/**
	 * A word for what this feature is doing right now.
	 *
	 * @return string
	 */
	public function state_label() {
		return __( 'No installs', 'adminkeep' );
	}

	/**
	 * What switching this on actually does. Shown on the settings screen.
	 *
	 * @return string[]
	 */
	public function how_it_works() {
		return array(
			__( 'Denies the install and upload capabilities for plugins and themes, for every user.', 'adminkeep' ),
			__( 'Updates are untouched: update notifications, manual updates and auto-updates all keep working, so security releases still reach the site.', 'adminkeep' ),
			__( 'Activating and deactivating what is already installed still works — this stops new code arriving, not what is running.', 'adminkeep' ),
			__( 'Always reversible from this screen. It deliberately does not use DISALLOW_FILE_MODS, which lives in wp-config.php and cannot be undone from the admin.', 'adminkeep' ),
			__( 'Enforced in PHP: filesystem, database or WP-CLI access can bypass it. A policy guard against accidents, not a security boundary.', 'adminkeep' ),
		);
	}

	/**
	 * Register hooks.
	 *
	 * @param array $settings Resolved settings.
	 * @return void
	 */
	public function boot( array $settings ) {
		add_filter( 'user_has_cap', array( $this, 'filter_capabilities' ), 100 );
	}

	/**
	 * The capabilities this lock denies.
	 *
	 * @return string[]
	 */
	public function denied_caps() {
		return self::ADDITIVE_CAPS;
	}

	/**
	 * Deny the locked capabilities.
	 *
	 * @param array $allcaps All capabilities of the current user.
	 * @return array
	 */
	public function filter_capabilities( $allcaps ) {
		if ( ! is_array( $allcaps ) ) {
			return $allcaps;
		}

		foreach ( $this->denied_caps() as $cap ) {
			$allcaps[ $cap ] = false;
		}

		return $allcaps;
	}
}