Administration Menus and Settings API

<?php
/**
 * The catalogue settings: one registered option, its sections and its fields.
 *
 * @package Lumen\Catalog
 */

namespace Lumen\Catalog;

defined( 'ABSPATH' ) || exit;

/**
 * Registers lp_catalog_settings with the Settings API.
 */
final class Settings {

	public const OPTION = 'lp_catalog_settings';
	public const GROUP  = 'lumen_catalog';
	public const PAGE   = 'lumen-catalog-settings';
	public const CAP    = 'manage_lumen_catalog';

	public const PLACEHOLDER_FEED = 'https://distributor.example';

	/**
	 * Default values, also used to fill keys missing from an older stored array.
	 *
	 * @return array<string, mixed>
	 */
	public static function defaults(): array {
		return array(
			'isbn_prefix'     => '978',
			'books_per_page'  => 12,
			'show_stock'      => true,
			'distributor_url' => self::PLACEHOLDER_FEED,
		);
	}

	/**
	 * The stored settings merged over the defaults.
	 *
	 * @return array<string, mixed>
	 */
	public static function get(): array {
		return wp_parse_args( (array) get_option( self::OPTION, array() ), self::defaults() );
	}

	/** Runs on init, so the setting exists for options.php, the REST API and WP-CLI alike. */
	public static function register(): void {
		register_setting(
			self::GROUP,
			self::OPTION,
			array(
				'type'              => 'object',
				'label'             => __( 'Lumen catalogue settings', 'lumen-catalog' ),
				'sanitize_callback' => array( self::class, 'sanitize' ),
				'default'           => self::defaults(),
				'show_in_rest'      => array(
					'name'   => 'lumen_catalog',
					'schema' => array(
						'additionalProperties' => false,
						'properties'           => array(
							'isbn_prefix'     => array(
								'type' => 'string',
								'enum' => array( '978', '979' ),
							),
							'books_per_page'  => array(
								'type'    => 'integer',
								'minimum' => 1,
								'maximum' => 100,
							),
							'show_stock'      => array( 'type' => 'boolean' ),
							'distributor_url' => array( 'type' => 'string' ),
						),
					),
				),
			)
		);
	}

	/**
	 * Filters wp_default_autoload_value, so writes without $autoload store auto-off.
	 *
	 * @param bool|null $autoload Default decision.
	 * @param string    $option   Option name.
	 * @return bool|null
	 */
	public static function autoload( $autoload, $option ) {
		return self::OPTION === $option ? false : $autoload;
	}

	/**
	 * Sanitizes every write; absent keys keep their stored value.
	 *
	 * @param mixed $value Raw value.
	 * @return array<string, mixed>
	 */
	public static function sanitize( $value ): array {
		$value = is_array( $value ) ? $value : array();
		$clean = self::get();

		if ( isset( $value['isbn_prefix'] ) ) {
			$prefix = sanitize_text_field( (string) $value['isbn_prefix'] );
			if ( in_array( $prefix, array( '978', '979' ), true ) ) {
				$clean['isbn_prefix'] = $prefix;
			} else {
				add_settings_error( self::OPTION, 'isbn_prefix', __( 'The ISBN prefix must be 978 or 979.', 'lumen-catalog' ) );
			}
		}

		if ( isset( $value['books_per_page'] ) ) {
			$clean['books_per_page'] = min( 100, max( 1, absint( $value['books_per_page'] ) ) );
		}

		if ( isset( $value['show_stock'] ) ) {
			$clean['show_stock'] = rest_sanitize_boolean( $value['show_stock'] );
		}

		if ( isset( $value['distributor_url'] ) ) {
			$url = esc_url_raw( trim( (string) $value['distributor_url'] ), array( 'https' ) );
			if ( '' === $url ) {
				add_settings_error( self::OPTION, 'distributor_url', __( 'The distributor feed must be an https:// URL.', 'lumen-catalog' ) );
			} else {
				$clean['distributor_url'] = $url;
			}
		}

		return $clean;
	}

	/** Runs on admin_init: the sections and fields of the settings screen. */
	public static function add_fields(): void {
		add_settings_section(
			'lumen_catalog_display',
			__( 'Catalogue display', 'lumen-catalog' ),
			static function () {
				echo '<p>' . esc_html__( 'How books appear on the public site.', 'lumen-catalog' ) . '</p>';
			},
			self::PAGE
		);
		add_settings_section( 'lumen_catalog_stock', __( 'Stock synchronisation', 'lumen-catalog' ), '__return_null', self::PAGE );

		$fields = array(
			'isbn_prefix'     => array( __( 'ISBN prefix', 'lumen-catalog' ), 'lumen_catalog_display', 'select' ),
			'books_per_page'  => array( __( 'Books per archive page', 'lumen-catalog' ), 'lumen_catalog_display', 'number' ),
			'show_stock'      => array( __( 'Show stock level', 'lumen-catalog' ), 'lumen_catalog_stock', 'checkbox' ),
			'distributor_url' => array( __( 'Distributor feed URL', 'lumen-catalog' ), 'lumen_catalog_stock', 'url' ),
		);
		foreach ( $fields as $key => list( $label, $section, $control ) ) {
			add_settings_field(
				'lumen_catalog_' . $key,
				$label,
				array( self::class, 'render_field' ),
				self::PAGE,
				$section,
				array(
					'label_for' => 'lumen_catalog_' . $key, // Wraps the title in <label for>.
					'key'       => $key,
					'control'   => $control,
				)
			);
		}
	}

	/**
	 * Prints one control. Names are lp_catalog_settings[key], so the form posts one array.
	 *
	 * @param array<string, string> $args Arguments passed to add_settings_field().
	 */
	public static function render_field( array $args ): void {
		$value = self::get()[ $args['key'] ];
		$id    = $args['label_for'];
		$name  = self::OPTION . '[' . $args['key'] . ']';

		switch ( $args['control'] ) {
			case 'select':
				printf( '<select id="%s" name="%s">', esc_attr( $id ), esc_attr( $name ) );
				foreach ( array( '978', '979' ) as $prefix ) {
					printf( '<option value="%1$s"%2$s>%1$s</option>', esc_attr( $prefix ), selected( $value, $prefix, false ) );
				}
				echo '</select>';
				break;
			case 'number':
				printf( '<input type="number" id="%s" name="%s" value="%d" min="1" max="100" class="small-text">', esc_attr( $id ), esc_attr( $name ), (int) $value );
				break;
			case 'checkbox':
				// The hidden 0 is posted when the box is unticked; an unticked checkbox sends nothing.
				printf( '<input type="hidden" name="%s" value="0">', esc_attr( $name ) );
				printf( '<input type="checkbox" id="%s" name="%s" value="1"%s>', esc_attr( $id ), esc_attr( $name ), checked( $value, true, false ) );
				break;
			default:
				printf( '<input type="url" id="%s" name="%s" value="%s" class="regular-text" placeholder="https://">', esc_attr( $id ), esc_attr( $name ), esc_attr( $value ) );
		}
	}
}

<?php
/**
 * The Catalogue admin menu, its screens, help tabs and notices.
 *
 * @package Lumen\Catalog
 */

namespace Lumen\Catalog;

defined( 'ABSPATH' ) || exit;

/**
 * Admin-only wiring; loaded when is_admin() is true.
 */
final class Admin {

	public const MENU = 'lumen-catalog';

	/** Hooks the admin screens. */
	public static function register(): void {
		add_action( 'admin_menu', array( self::class, 'add_menus' ) );
		add_action( 'admin_init', array( Settings::class, 'add_fields' ) );
		add_action( 'admin_notices', array( self::class, 'notices' ) );
		add_action( 'admin_enqueue_scripts', array( self::class, 'notice_script' ) );
		add_action( 'wp_ajax_lumen_catalog_dismiss', array( self::class, 'dismiss_notice' ) );
		// options.php checks manage_options unless this filter names another capability.
		add_filter(
			'option_page_capability_' . Settings::GROUP,
			static function () {
				return Settings::CAP;
			}
		);
	}

	/** Runs on admin_menu: a top-level Catalogue menu with Overview and Settings. */
	public static function add_menus(): void {
		add_menu_page(
			__( 'Lumen catalogue', 'lumen-catalog' ),
			__( 'Catalogue', 'lumen-catalog' ),
			'edit_lp_books',
			self::MENU,
			array( self::class, 'render_overview' ),
			'dashicons-book-alt',
			26
		);
		// Same slug as the parent: renames the automatic first item to "Overview".
		add_submenu_page( self::MENU, __( 'Lumen catalogue', 'lumen-catalog' ), __( 'Overview', 'lumen-catalog' ), 'edit_lp_books', self::MENU );

		$hook = add_submenu_page(
			self::MENU,
			__( 'Catalogue settings', 'lumen-catalog' ),
			__( 'Settings', 'lumen-catalog' ),
			Settings::CAP,
			Settings::PAGE,
			array( self::class, 'render_settings' )
		);
		if ( $hook ) {
			add_action( 'load-' . $hook, array( self::class, 'add_help_tabs' ) );
		}
	}

	/** The Overview screen. */
	public static function render_overview(): void {
		$counts = wp_count_posts( 'lp_book' );
		printf(
			/* translators: %d: number of published books. */
			'<div class="wrap"><h1>%s</h1><p>' . esc_html__( '%d published books.', 'lumen-catalog' ) . '</p></div>',
			esc_html( get_admin_page_title() ),
			(int) ( $counts->publish ?? 0 )
		);
	}

	/** The Settings screen: options.php does the saving. */
	public static function render_settings(): void {
		if ( ! current_user_can( Settings::CAP ) ) {
			return;
		}
		echo '<div class="wrap"><h1>' . esc_html( get_admin_page_title() ) . '</h1>';
		settings_errors(); // Core prints these only under Settings (options-general.php).
		echo '<form action="options.php" method="post">';
		settings_fields( Settings::GROUP );
		do_settings_sections( Settings::PAGE );
		submit_button();
		echo '</form></div>';
	}