Plugin Refactoring 01/2025 (#665)

* Refactor main plugin file.

* Refactor functions and rest

* Refactor Blocks Component

* Refactor tests

* Update bootstrap.php

plugin/inc/Blocks/Blocks.php

@@ -12,7 +12,6 @@
 namespace WpMunich\lhpbp\plugin\Blocks;
 
 use WpMunich\lhpbp\plugin\Plugin_Component;
-
 use function WpMunich\lhpbp\plugin\plugin;
 use function add_action;
 use function add_filter;
@@ -72,19 +71,18 @@ public function add_block_categories( $categories, $post ) {
 	 * and translations for the block UI.
 	 */
 	public function enqueue_block_editor_assets() {
-		$screen = get_current_screen();
+		$screen = function_exists( 'get_current_screen' ) ? get_current_screen() : null;
 
-		// Load asset configuration.
-		$assets = wp_json_file_decode( plugin()->get_plugin_path() . '/admin/dist/assets.json', array( 'associative' => true ) );
+		$assets_path = plugin()->get_plugin_path() . '/admin/dist/assets.json';
+		$assets      = file_exists( $assets_path ) ? wp_json_file_decode( $assets_path, array( 'associative' => true ) ) : array();
 
-		// Enqueue block helper script outside the widgets screen.
-		if ( ! in_array( $screen->id, array( 'widgets' ), true ) ) {
+		if ( $screen && ! in_array( $screen->id, array( 'widgets' ), true ) ) {
 			$block_helper_assets = $assets['js/blocks-helper.min.js'] ?? array();
 			wp_enqueue_script(
 				'lhpbpp-blocks-helper',
 				plugin()->get_plugin_url() . 'admin/dist/js/blocks-helper.min.js',
-				array_merge( array(), $block_helper_assets['dependencies'] ),
-				$block_helper_assets['version'],
+				$block_helper_assets['dependencies'] ?? array(),
+				$block_helper_assets['version'] ?? false,
 				true
 			);
 		}
@@ -93,8 +91,8 @@ public function enqueue_block_editor_assets() {
 		wp_enqueue_script(
 			'lhpbpp-blocks',
 			plugin()->get_plugin_url() . 'admin/dist/js/blocks.min.js',
-			array_merge( array(), $block_assets['dependencies'] ),
-			$block_assets['version'],
+			$block_assets['dependencies'] ?? array(),
+			$block_assets['version'] ?? false,
 			true
 		);
 
@@ -106,28 +104,13 @@ public function enqueue_block_editor_assets() {
 			'all'
 		);
 
-		// Load translations for block editor assets.
-		$dir  = plugin()->get_plugin_path();
-		$path = $dir . '/languages/';
-
-		wp_set_script_translations(
-			'lhpbpp-blocks',
-			'lhpbpp',
-			$path
-		);
-
-		wp_set_script_translations(
-			'lhpbpp-blocks-helper',
-			'lhpbpp',
-			$path
-		);
+		$path = plugin()->get_plugin_path() . '/languages/';
+		wp_set_script_translations( 'lhpbpp-blocks', 'lhpbpp', $path );
+		wp_set_script_translations( 'lhpbpp-blocks-helper', 'lhpbpp', $path );
 	}
 
 	/**
 	 * Register custom blocks for the plugin.
-	 *
-	 * Registers block types from the specified directory, setting a render callback function
-	 * for custom rendering of each block.
 	 */
 	public function register_blocks() {
 		$blocks_path = plugin()->get_plugin_path() . 'blocks/';
@@ -149,9 +132,6 @@ public function register_blocks() {
 	/**
 	 * Provide the render callback for custom blocks.
 	 *
-	 * Captures block-specific HTML output using a buffer and includes the block's template file
-	 * based on its name. This allows dynamic block content rendering on the frontend.
-	 *
 	 * @param array    $attributes The block attributes.
 	 * @param string   $content    The block content.
 	 * @param WP_Block $block      The block instance.
@@ -168,8 +148,6 @@ public function provide_render_callback( $attributes, $content, $block ) {
 				break;
 		}
 
-		$block_html = ob_get_clean();
-
-		return $block_html;
+		return ob_get_clean();
 	}
 }

plugin/inc/REST/REST.php

@@ -11,8 +11,9 @@
 namespace WpMunich\lhpbp\plugin\REST;
 
 use WpMunich\lhpbp\plugin\Plugin_Component;
-
+use WP_REST_Server;
 use function add_action;
+use function register_rest_route;
 
 /**
  * REST
@@ -43,38 +44,41 @@ protected function add_filters() {}
 	/**
 	 * Register custom REST API routes.
 	 *
+	 * This method is intended to be overridden by developers when adding REST routes.
+	 * Example usage is provided in the comments below.
+	 *
 	 * @return void
 	 */
 	public function register_rest_routes() {
-		/* phpcs:disable */
-		// Route to retrieve all examples.
 		/*
+		Example route: Retrieve all examples
 		register_rest_route(
 			$this->rest_namespace,
-			'examples',
+			'/examples/',
 			array(
 				'methods'             => WP_REST_Server::READABLE,
 				'callback'            => array( $this, 'rest_get_examples' ),
 				'permission_callback' => '__return_true',
 			)
 		);
 		*/
-		/* phpcs:enable */
 
-		/* phpcs:disable */
-		// Route to retrieve a single example by slug.
 		/*
+		Example route: Retrieve a single example by slug
 		register_rest_route(
 			$this->rest_namespace,
-			'example(?:/(?<slug>[a-z0-9-]+))?',
+			'/example/(?P<slug>[a-z0-9-]+)/',
 			array(
 				'methods'             => WP_REST_Server::READABLE,
 				'callback'            => array( $this, 'rest_get_example' ),
 				'permission_callback' => '__return_true',
 				'args'                => array(
 					'slug' => array(
-						'type' => 'string',
-					),
+						'required' => true,
+						'validate_callback' => function( $param ) {
+							return is_string( $param ) && preg_match( '/^[a-z0-9-]+$/', $param );
+						}
+					)
 				),
 			)
 		);

plugin/inc/functions.php

@@ -12,6 +12,9 @@
 
 namespace WpMunich\lhpbp\plugin;
 
+use DI\ContainerBuilder;
+use DI\Container;
+
 /**
  * Access the main plugin instance.
  *
@@ -24,12 +27,10 @@
 function plugin() {
 	static $plugin = null;
 
-	// Ensure all requirements are met before initializing the plugin.
 	if ( ! plugin_requirements_are_met() ) {
-		return null;
+		return null; // Prevent fatal error while allowing WordPress backend access.
 	}
 
-	// Initialize the plugin only once.
 	if ( null === $plugin ) {
 		/**
 		 * The main plugin component.
@@ -49,14 +50,13 @@ function plugin() {
  * services and dependencies within the plugin.
  *
  * @link https://github.com/PHP-DI/PHP-DI
- * @return \DI\Container The plugin's DI container.
+ * @return Container The plugin's DI container.
  */
 function plugin_container() {
 	static $container = null;
 
-	// Initialize the container if it has not been created yet.
 	if ( null === $container ) {
-		$builder   = new \DI\ContainerBuilder();
+		$builder   = new ContainerBuilder();
 		$container = $builder->build();
 	}
 
@@ -69,11 +69,24 @@ function plugin_container() {
  * Verifies that all necessary dependencies and functions are available. This prevents errors
  * that could arise if required components are missing.
  *
- * @return bool True if requirements are met, false otherwise.
+ * @return bool True if all requirements are met, false otherwise.
  */
 function plugin_requirements_are_met() {
-	if ( ! function_exists( '\WpMunich\lhpbp\plugin\plugin' ) ) {
-		return false;
+	$requirements = array(
+		'function_exists' => array(
+			'\WpMunich\lhpbp\plugin\plugin',
+		),
+		'class_exists' => array(
+			'DI\\ContainerBuilder',
+		),
+	);
+
+	foreach ( $requirements as $check => $items ) {
+		foreach ( $items as $item ) {
+			if ( ! call_user_func( $check, $item ) ) {
+				return false;
+			}
+		}
 	}
 
 	return true;

plugin/lhpbpp.php

@@ -1,13 +1,5 @@
 <?php
 /**
- * The main file of the plugin.
- *
- * This file defines the main plugin metadata, initializes the plugin, loads necessary files,
- * and sets up an automatic update checker. It serves as the primary entry point for the plugin's
- * functionality within WordPress.
- *
- * @package lhpbp\plugin
- *
  * Plugin Name: WordPress Project Boilerplate
  * Plugin URI: https://www.luehrsen-heinrich.de
  * Description: A base boilerplate for Luehrsen // Heinrich WordPress projects.
@@ -16,45 +8,60 @@
  * Version: 0.0.18
  * Text Domain: lhpbpp
  * Domain Path: /languages
+ *
+ * @package lhpbp\plugin
  */
 
 use YahnisElsts\PluginUpdateChecker\v5\PucFactory;
-
 use function WpMunich\lhpbp\plugin\plugin;
 use function WpMunich\lhpbp\plugin\plugin_requirements_are_met;
 
-// If this file is called directly, abort.
+// Exit if accessed directly.
 if ( ! defined( 'WPINC' ) ) {
 	exit( 1 );
 }
 
-// Set a constant for the plugin's main file.
-if ( ! defined( 'LHPBPP_FILE' ) ) {
-	/**
-	 * The path to the main file of the plugin.
-	 *
-	 * This constant provides a reference to the main plugin file, used for determining the
-	 * plugin directory and for other relative paths within the plugin.
-	 *
-	 * @var string
-	 */
-	define( 'LHPBPP_FILE', __FILE__ );
-}
+/**
+ * Define the plugin's main file path constant.
+ *
+ * This constant provides a reference to the main plugin file, used for determining the
+ * plugin directory and for other relative paths within the plugin.
+ */
+define( 'LHPBPP_FILE', __FILE__ );
 
-// Load the Composer autoloader to include third-party dependencies.
-require plugin_dir_path( LHPBPP_FILE ) . 'vendor/autoload.php';
+/**
+ * Load the Composer autoloader.
+ *
+ * This ensures that all required dependencies and third-party libraries are properly loaded.
+ */
+require_once plugin_dir_path( LHPBPP_FILE ) . 'vendor/autoload.php';
 
-// Load the main `wp_lhpbpp()` entry point function, which initializes the plugin's components.
-require plugin_dir_path( LHPBPP_FILE ) . 'inc/functions.php';
+/**
+ * Load the core plugin functions.
+ *
+ * These functions initialize the main components and logic of the plugin.
+ */
+require_once plugin_dir_path( LHPBPP_FILE ) . 'inc/functions.php';
 
-// Initialize the plugin by calling the main entry point function.
+/**
+ * Initialize the plugin.
+ *
+ * Calls the main function to bootstrap the plugin's components.
+ */
+if ( ! function_exists( 'WpMunich\lhpbp\plugin\plugin' ) ) {
+	wp_die( esc_html__( 'Critical error: The main plugin function is missing.', 'lhpbpp' ) );
+}
 call_user_func( 'WpMunich\lhpbp\plugin\plugin' );
 
-// Initialize the plugin update checker if all plugin requirements are met.
-if ( class_exists( 'YahnisElsts\PluginUpdateChecker\v5\PucFactory' ) && plugin_requirements_are_met() ) {
+/**
+ * Initialize the plugin update checker.
+ *
+ * Ensures the plugin can check for and receive updates if all requirements are met.
+ */
+if ( class_exists( 'YahnisElsts\PluginUpdateChecker\v5\PucFactory' ) && function_exists( 'WpMunich\lhpbp\plugin\plugin_requirements_are_met' ) && plugin_requirements_are_met() ) {
 	PucFactory::buildUpdateChecker(
 		'https://www.luehrsen-heinrich.de/updates/?action=get_metadata&slug=' . plugin()->get_plugin_slug(),
-		__FILE__, // Full path to the main plugin file (used for update tracking).
+		LHPBPP_FILE, // Full path to the main plugin file (used for update tracking).
 		plugin()->get_plugin_slug()
 	);
 }

plugin/tests/Lhpbpp_Test.php

@@ -6,7 +6,7 @@
  */
 
 /**
- * Class Lhpbpp_Basic_Test
+ * Class Lhpbpp_Test
  */
 class Lhpbpp_Test extends WP_UnitTestCase {
 

plugin/tests/bootstrap.php

@@ -2,7 +2,7 @@
 /**
  * PHPUnit bootstrap file.
  *
- * @package citations
+ * @package lhpbp\plugin
  */
 
 // Load PHPUnit Polyfills.
@@ -32,7 +32,7 @@
  * Manually load the plugin being tested.
  */
 function _manually_load_plugin() {
-	require WP_CONTENT_DIR . '/plugins/plugin/lhpbpp.php';
+	require WP_PLUGIN_DIR . '/plugin/lhpbpp.php';
 }
 
 tests_add_filter( 'muplugins_loaded', '_manually_load_plugin' );