Reviewing admin functionality. Tidy up of docs etc.

colinmurphy · colinmurphy · commit 2916d1fd5826 · 2025-06-24T11:52:47.000+01:00
diff --git a/plugins/hwp-previews/ACTIONS_AND_FILTERS.md b/plugins/hwp-previews/ACTIONS_AND_FILTERS.md
@@ -8,20 +8,27 @@
 
 ## PHP Filters
 
+## Admin
+
+- `hwp_previews_settings_init` - Allows a user to modify the `Settings` instance
+- `hwp_previews_settings_form_manager_init` - Allows a user to modify the `Settings_Form_Manager` instance and update fields and post types
+- `hwp_previews_settings_fields` - Allows a user to register, modify, or remove settings fields for the settings page
+- `hwp_previews_settings_group_option_key` - Filter to modify the settings group option key. Default is HWP_PREVIEWS_SETTINGS_KEY
+- `hwp_previews_settings_group_settings_group` - Filter to modify the settings group name. Default is HWP_PREVIEWS_SETTINGS_GROUP
+
+
+
 - `hwp_previews_register_parameters` - Allows modification of the URL parameters used for previews for the class `Preview_Parameter_Registry`
 - `hwp_previews_template_path` - To use our own template for iframe previews
 - `hwp_previews_core` - Register or unregister URL parameters, and adjust types/statuses
 - `hwp_previews_filter_available_post_types` - Filter to modify the available post types for Previews.
 - `hwp_previews_filter_available_post_statuses` - Filter for post statuses for previews for Previews
 - `hwp_previews_filter_available_parent_post_statuses` - Filter for parent post statuses for Previews
-- `hwp_previews_settings_group_option_key` - Filter to modify the settings group option key. Default is HWP_PREVIEWS_SETTINGS_KEY
-- `hwp_previews_settings_group_settings_group` - Filter to modify the settings group name. Default is HWP_PREVIEWS_SETTINGS_GROUP
 - `hwp_previews_settings_group_settings_config` - Filter to modify the settings array. See `Settings_Group`
 - `hwp_previews_settings_group_cache_groups` - Filter to modify cache groups for `Settings_Group`
 - `hwp_previews_get_post_types_config` - Filter for generating the instance of `Post_Types_Config_Interface`
 - `hwp_previews_hooks_post_status_config` - Filter for post status config service for the Hook class
 - `hwp_previews_hooks_preview_link_service` - Filter for preview link service for the Hook class
-- `hwp_previews_settings_fields` - Allows a user to register, modify, or remove settings fields for the settings page
 
 ## Usage Examples
 
diff --git a/plugins/hwp-previews/activation.php b/plugins/hwp-previews/activation.php
@@ -3,6 +3,8 @@
  * Activation Hook
  *
  * @package HWP\Previews
+ *
+ * @since 0.0.1
  */
 
 declare(strict_types=1);
diff --git a/plugins/hwp-previews/deactivation.php b/plugins/hwp-previews/deactivation.php
@@ -6,6 +6,8 @@
  * Deactivation Hook
  *
  * @package HWP\Previews
+ *
+ * @since 0.0.1
  */
 
 /**
diff --git a/plugins/hwp-previews/hwp-previews.php b/plugins/hwp-previews/hwp-previews.php
@@ -64,9 +64,6 @@ function hwp_previews_init(): void {
 if ( ! function_exists( 'hwp_previews_constants' ) ) {
 	/**
 	 * Define plugin constants.
-	 *
-	 * phpcs:disable Generic.Metrics.CyclomaticComplexity.TooHigh
-	 * phpcs:disable SlevomatCodingStandard.Complexity.Cognitive.ComplexityTooHigh
 	 */
 	function hwp_previews_constants(): void {
 		if ( ! defined( 'HWP_PREVIEWS_VERSION' ) ) {
@@ -81,25 +78,13 @@ function hwp_previews_constants(): void {
 			define( 'HWP_PREVIEWS_PLUGIN_URL', plugin_dir_url( __FILE__ ) );
 		}
 
-		if ( ! defined( 'HWP_PREVIEWS_PLUGIN_FILE' ) ) {
-			define( 'HWP_PREVIEWS_PLUGIN_FILE', __FILE__ );
-		}
-
-		if ( ! defined( 'HWP_PREVIEWS_AUTOLOAD' ) ) {
-			define( 'HWP_PREVIEWS_AUTOLOAD', true );
-		}
-
 		if ( ! defined( 'HWP_PREVIEWS_SETTINGS_GROUP' ) ) {
 			define( 'HWP_PREVIEWS_SETTINGS_GROUP', 'hwp_previews_settings_group' );
 		}
 
 		if ( ! defined( 'HWP_PREVIEWS_SETTINGS_KEY' ) ) {
 			define( 'HWP_PREVIEWS_SETTINGS_KEY', 'hwp_previews_settings' );
 		}
-
-		if ( ! defined( 'HWP_PREVIEWS_TEXT_DOMAIN' ) ) {
-			define( 'HWP_PREVIEWS_TEXT_DOMAIN', 'hwp-previews' );
-		}
 	}
 }
 
@@ -112,7 +97,7 @@ function hwp_previews_plugin_init(): ?Plugin {
 			return null;
 		}
 		require_once HWP_PREVIEWS_PLUGIN_DIR . 'src/Plugin.php';
-		return Plugin::instance();
+		return Plugin::init();
 	}
 }
 
@@ -146,7 +131,7 @@ static function (): void {
 }
 
 /**
- * Load plugin textdomain.
+ * Load plugin text domain.
  */
 function hwp_previews_load_textdomain(): void {
 	load_plugin_textdomain( 'hwp-previews', false, dirname( plugin_basename( __FILE__ ) ) . '/languages' );
diff --git a/plugins/hwp-previews/src/Admin/Settings/Fields/Field/Abstract_Settings_Field.php b/plugins/hwp-previews/src/Admin/Settings/Fields/Field/Abstract_Settings_Field.php
@@ -5,6 +5,7 @@
 namespace HWP\Previews\Admin\Settings\Fields\Field;
 
 use HWP\Previews\Admin\Settings\Fields\Settings_Field_Interface;
+use HWP\Previews\Preview\Post\Post_Settings_Service;
 
 abstract class Abstract_Settings_Field implements Settings_Field_Interface {
 	/**
@@ -121,7 +122,7 @@ public function add_settings_field( string $section, string $page, array $args )
 	public function settings_field_callback( array $args ): void {
 
 		$post_type    = $args['post_type'] ?? 'post';
-		$settings_key = $args['settings_key'] ?? HWP_PREVIEWS_SETTINGS_KEY;
+		$settings_key = $args['settings_key'] ?? Post_Settings_Service::get_option_key();
 
 		printf(
 			'<div tabindex="0" aria-describedby="%2$s-tooltip" class="hwp-previews-tooltip">
diff --git a/plugins/hwp-previews/src/Admin/Settings/Fields/Field/Checkbox_Field.php b/plugins/hwp-previews/src/Admin/Settings/Fields/Field/Checkbox_Field.php
@@ -4,6 +4,15 @@
 
 namespace HWP\Previews\Admin\Settings\Fields\Field;
 
+/**
+ * Checkbox field class
+ *
+ * This class represents a checkbox field in the settings of the HWP Previews plugin.
+ *
+ * @package HWP\Previews
+ *
+ * @since 0.0.1
+ */
 class Checkbox_Field extends Abstract_Settings_Field {
 	/**
 	 * The default value for the field.
diff --git a/plugins/hwp-previews/src/Admin/Settings/Fields/Field/Text_Input_Field.php b/plugins/hwp-previews/src/Admin/Settings/Fields/Field/Text_Input_Field.php
@@ -4,6 +4,15 @@
 
 namespace HWP\Previews\Admin\Settings\Fields\Field;
 
+/**
+ * Text input class
+ *
+ * This class represents a text input field in the settings of the HWP Previews plugin.
+ *
+ * @package HWP\Previews
+ *
+ * @since 0.0.1
+ */
 class Text_Input_Field extends Abstract_Settings_Field {
 	/**
 	 * The default value for the field.
diff --git a/plugins/hwp-previews/src/Admin/Settings/Fields/Field/URL_Input_Field.php b/plugins/hwp-previews/src/Admin/Settings/Fields/Field/URL_Input_Field.php
@@ -4,6 +4,15 @@
 
 namespace HWP\Previews\Admin\Settings\Fields\Field;
 
+/**
+ * URL input class
+ *
+ * This class represents a url input field in the settings of the HWP Previews plugin.
+ *
+ * @package HWP\Previews
+ *
+ * @since 0.0.1
+ */
 class URL_Input_Field extends Text_Input_Field {
 	/**
 	 * @param mixed $value
@@ -64,8 +73,8 @@ private function fix_url( string $value ): string {
 			return '';
 		}
 
-		$has_prootocol = preg_match( '/^https?:\/\//i', $value ) === 1;
-		if ( $has_prootocol ) {
+		$has_protocol = preg_match( '/^https?:\/\//i', $value ) === 1;
+		if ( $has_protocol ) {
 			return $value;
 		}
 		$protocol = is_ssl() ? 'https://' : 'http://';
diff --git a/plugins/hwp-previews/src/Admin/Settings/Fields/Settings_Field_Collection.php b/plugins/hwp-previews/src/Admin/Settings/Fields/Settings_Field_Collection.php
@@ -7,6 +7,16 @@
 use HWP\Previews\Admin\Settings\Fields\Field\Checkbox_Field;
 use HWP\Previews\Admin\Settings\Fields\Field\URL_Input_Field;
 
+/**
+ * Class Settings_Field_Collection
+ *
+ * This class manages a collection of settings fields for the HWP Previews plugin.
+ * It provides methods to add, remove, and retrieve fields, as well as to initialize them.
+ *
+ * @package HWP\Previews
+ *
+ * @since 0.0.1
+ */
 class Settings_Field_Collection {
 	/**
 	 * The ID of the field that enables or disables the previews.
diff --git a/plugins/hwp-previews/src/Admin/Settings/Menu/Menu_Page.php b/plugins/hwp-previews/src/Admin/Settings/Menu/Menu_Page.php
@@ -4,6 +4,15 @@
 
 namespace HWP\Previews\Admin\Settings\Menu;
 
+/**
+ * Menu class for WordPress admin settings page.
+ *
+ * This class is responsible for creating a menu page in the WordPress admin area.
+ *
+ * @package HWP\Previews
+ *
+ * @since 0.0.1
+ */
 class Menu_Page {
 	/**
 	 * The title of the page.
diff --git a/plugins/hwp-previews/src/Admin/Settings/Settings_Form_Manager.php b/plugins/hwp-previews/src/Admin/Settings/Settings_Form_Manager.php
@@ -7,6 +7,15 @@
 use HWP\Previews\Admin\Settings\Fields\Settings_Field_Collection;
 use HWP\Previews\Preview\Post\Post_Settings_Service;
 
+/**
+ * Settings Form Manager class for HWP Previews.
+ *
+ * This class manages the settings form for different post types, allowing for the registration and sanitization of settings fields.
+ *
+ * @package HWP\Previews
+ *
+ * @since 0.0.1
+ */
 class Settings_Form_Manager {
 	/**
 	 * Array of available post-types for which settings are registered.
@@ -20,15 +29,22 @@ class Settings_Form_Manager {
 	 *
 	 * @var \HWP\Previews\Admin\Settings\Fields\Settings_Field_Collection
 	 */
-	protected Settings_Field_Collection $fields;
+	protected Settings_Field_Collection $field_collection;
 
 	/**
 	 * @param array<string>                                                 $post_types Array of post types for which settings are registered.
 	 * @param \HWP\Previews\Admin\Settings\Fields\Settings_Field_Collection $fields Collection of fields to be registered in the settings sections.
 	 */
 	public function __construct( array $post_types, Settings_Field_Collection $fields ) {
-		$this->post_types = $post_types;
-		$this->fields     = $fields;
+		$this->set_post_types( $post_types );
+		$this->set_field_collection( $fields );
+
+		/**
+		 * Fire off init action.
+		 *
+		 * @param \HWP\Previews\Admin\Settings\Settings_Form_Manager $instance the instance of the settings class.
+		 */
+		do_action( 'hwp_previews_settings_form_manager_init', $this );
 	}
 
 	/**
@@ -39,7 +55,7 @@ public function __construct( array $post_types, Settings_Field_Collection $field
 	public function render_form(): void {
 		$this->create_tabs();
 
-		foreach ( $this->post_types as $post_type => $label ) {
+		foreach ( $this->get_post_types() as $post_type => $label ) {
 			$this->render_post_type_section( $post_type, $label );
 		}
 	}
@@ -74,7 +90,7 @@ public function sanitize_settings( array $new_input ): array {
 		// Sanitize the fields in the tab.
 		$sanitized_fields = [];
 		foreach ( $new_input[ $tab_to_sanitize ] as $key => $value ) {
-			$field = $this->fields->get_field( $key );
+			$field = $this->get_field_collection()->get_field( $key );
 			if ( is_null( $field ) ) {
 				continue; // Skip unknown fields.
 			}
@@ -102,6 +118,36 @@ public function get_settings_group(): string {
 		return Post_Settings_Service::get_settings_group();
 	}
 
+	/**
+	 * Get the fields collection for the settings form.
+	 */
+	public function get_field_collection(): Settings_Field_Collection {
+		return $this->field_collection;
+	}
+
+	/**
+	 * @param \HWP\Previews\Admin\Settings\Fields\Settings_Field_Collection $field_collection
+	 */
+	public function set_field_collection( Settings_Field_Collection $field_collection ): void {
+		$this->field_collection = $field_collection;
+	}
+
+	/**
+	 * The available post types for which settings are registered.
+	 *
+	 * @return array<string>
+	 */
+	public function get_post_types(): array {
+		return $this->post_types;
+	}
+
+	/**
+	 * @param array<string, string> $post_types
+	 */
+	public function set_post_types( array $post_types ): void {
+		$this->post_types = $post_types;
+	}
+
 	/**
 	 * Create the settings tabs for the post-types.
 	 *
@@ -132,7 +178,7 @@ protected function create_tabs(): void {
 	 * @param string $label     The label for the post type section.
 	 */
 	protected function render_post_type_section( string $post_type, string $label ): void {
-		$fields          = $this->fields->get_fields();
+		$fields          = $this->get_field_collection()->get_fields();
 		$page_id         = 'hwp_previews_section_' . $post_type;
 		$page_uri        = 'hwp-previews-' . $post_type;
 		$is_hierarchical = is_post_type_hierarchical( $post_type );
@@ -151,7 +197,7 @@ protected function render_post_type_section( string $post_type, string $label ):
 				[
 					'post_type'    => $post_type,
 					'label'        => $label,
-					'settings_key' => HWP_PREVIEWS_SETTINGS_KEY,
+					'settings_key' => Post_Settings_Service::get_option_key(),
 				]
 			);
 		}
diff --git a/plugins/hwp-previews/src/Admin/Settings_Page.php b/plugins/hwp-previews/src/Admin/Settings_Page.php
@@ -10,6 +10,15 @@
 use HWP\Previews\Preview\Parameter\Preview_Parameter_Registry;
 use HWP\Previews\Preview\Post\Post_Preview_Service;
 
+/**
+ * Settings_Page class for HWP Previews.
+ *
+ * This class handles the registration of the settings page, settings fields, and loading of scripts and styles for the plugin.
+ *
+ * @package HWP\Previews
+ *
+ * @since 0.0.1
+ */
 class Settings_Page {
 	/**
 	 * @var string The slug for the plugin menu.
@@ -40,7 +49,7 @@ class Settings_Page {
 	 *
 	 * Initializes the settings page, registers settings fields, and loads scripts and styles.
 	 */
-	public function __construct() {
+	protected function __construct() {
 		$this->parameters           = Preview_Parameter_Registry::get_instance();
 		$this->post_preview_service = new Post_Preview_Service();
 	}
@@ -62,7 +71,7 @@ public static function init(): ?Settings_Page {
 		 *
 		 * @param \HWP\Previews\Admin\Settings_Page $instance the instance of the plugin class.
 		 */
-		do_action( 'hwp_previews_init', self::$instance );
+		do_action( 'hwp_previews_settings_init', self::$instance );
 
 		return self::$instance;
 	}
@@ -81,7 +90,7 @@ public function setup(): void {
 	 */
 	public function register_settings_page(): void {
 
-		// Note: We didn't initalise in the constructor because we need to ensure
+		// Note: We didn't initialise in the constructor because we need to ensure
 		// the post-types are registered before we can use them.
 		$post_types = $this->post_preview_service->get_post_types();
 
diff --git a/plugins/hwp-previews/src/Autoloader.php b/plugins/hwp-previews/src/Autoloader.php
@@ -1,18 +1,15 @@
 <?php
-/**
- * Includes the composer Autoloader used for packages and classes in the src/ directory.
- *
- * @package HWP\Previews
- *
- * @since 0.0.1
- */
 
 declare(strict_types=1);
 
 namespace HWP\Previews;
 
 /**
- * Class - Autoloader
+ * Includes the composer Autoloader used for packages and classes in the src/ directory.
+ *
+ * @package HWP\Previews
+ *
+ * @since 0.0.1
  */
 class Autoloader {
 	/**
diff --git a/plugins/hwp-previews/src/Integration/Faust_Integration.php b/plugins/hwp-previews/src/Integration/Faust_Integration.php
diff --git a/plugins/hwp-previews/src/Plugin.php b/plugins/hwp-previews/src/Plugin.php
diff --git a/plugins/hwp-previews/src/Templates/admin.php b/plugins/hwp-previews/src/Templates/admin.php
diff --git a/plugins/hwp-previews/tests/wpunit/Admin/Settings/SettingsFormManagerTest.php b/plugins/hwp-previews/tests/wpunit/Admin/Settings/SettingsFormManagerTest.php
diff --git a/plugins/hwp-previews/tests/wpunit/Admin/SettingsPageTest.php b/plugins/hwp-previews/tests/wpunit/Admin/SettingsPageTest.php
diff --git a/plugins/hwp-previews/tests/wpunit/Core/PluginTest.php b/plugins/hwp-previews/tests/wpunit/Core/PluginTest.php

Original file line number	Diff line number	Diff line change
`@@ -3,6 +3,8 @@`
`3`	`3`	`* Activation Hook`
`4`	`4`	`*`
`5`	`5`	`* @package HWP\Previews`
	`6`	`+ *`
	`7`	`+ * @since 0.0.1`
`6`	`8`	`*/`
`7`	`9`
`8`	`10`	`declare(strict_types=1);`
Original file line number	Diff line number	Diff line change
`@@ -6,6 +6,8 @@`
`6`	`6`	`* Deactivation Hook`
`7`	`7`	`*`
`8`	`8`	`* @package HWP\Previews`
	`9`	`+ *`
	`10`	`+ * @since 0.0.1`
`9`	`11`	`*/`
`10`	`12`
`11`	`13`	`/**`
Original file line number	Diff line number	Diff line change
`@@ -64,9 +64,6 @@ function hwp_previews_init(): void {`
`64`	`64`	`if ( ! function_exists( 'hwp_previews_constants' ) ) {`
`65`	`65`	`/**`
`66`	`66`	`* Define plugin constants.`
`67`		`- *`
`68`		`- * phpcs:disable Generic.Metrics.CyclomaticComplexity.TooHigh`
`69`		`- * phpcs:disable SlevomatCodingStandard.Complexity.Cognitive.ComplexityTooHigh`
`70`	`67`	`*/`
`71`	`68`	`function hwp_previews_constants(): void {`
`72`	`69`	`if ( ! defined( 'HWP_PREVIEWS_VERSION' ) ) {`
`@@ -81,25 +78,13 @@ function hwp_previews_constants(): void {`
`81`	`78`	`define( 'HWP_PREVIEWS_PLUGIN_URL', plugin_dir_url( __FILE__ ) );`
`82`	`79`	`}`
`83`	`80`
`84`		`- if ( ! defined( 'HWP_PREVIEWS_PLUGIN_FILE' ) ) {`
`85`		`- define( 'HWP_PREVIEWS_PLUGIN_FILE', __FILE__ );`
`86`		`- }`
`87`		`-`
`88`		`- if ( ! defined( 'HWP_PREVIEWS_AUTOLOAD' ) ) {`
`89`		`- define( 'HWP_PREVIEWS_AUTOLOAD', true );`
`90`		`- }`
`91`		`-`
`92`	`81`	`if ( ! defined( 'HWP_PREVIEWS_SETTINGS_GROUP' ) ) {`
`93`	`82`	`define( 'HWP_PREVIEWS_SETTINGS_GROUP', 'hwp_previews_settings_group' );`
`94`	`83`	`}`
`95`	`84`
`96`	`85`	`if ( ! defined( 'HWP_PREVIEWS_SETTINGS_KEY' ) ) {`
`97`	`86`	`define( 'HWP_PREVIEWS_SETTINGS_KEY', 'hwp_previews_settings' );`
`98`	`87`	`}`
`99`		`-`
`100`		`- if ( ! defined( 'HWP_PREVIEWS_TEXT_DOMAIN' ) ) {`
`101`		`- define( 'HWP_PREVIEWS_TEXT_DOMAIN', 'hwp-previews' );`
`102`		`- }`
`103`	`88`	`}`
`104`	`89`	`}`
`105`	`90`
`@@ -112,7 +97,7 @@ function hwp_previews_plugin_init(): ?Plugin {`
`112`	`97`	`return null;`
`113`	`98`	`}`
`114`	`99`	`require_once HWP_PREVIEWS_PLUGIN_DIR . 'src/Plugin.php';`
`115`		`- return Plugin::instance();`
	`100`	`+ return Plugin::init();`
`116`	`101`	`}`
`117`	`102`	`}`
`118`	`103`
`@@ -146,7 +131,7 @@ static function (): void {`
`146`	`131`	`}`
`147`	`132`
`148`	`133`	`/**`
`149`		`- * Load plugin textdomain.`
	`134`	`+ * Load plugin text domain.`
`150`	`135`	`*/`
`151`	`136`	`function hwp_previews_load_textdomain(): void {`
`152`	`137`	`load_plugin_textdomain( 'hwp-previews', false, dirname( plugin_basename( __FILE__ ) ) . '/languages' );`