From 2158ef1434b7e75a90d44123881077e6c1cc4814 Mon Sep 17 00:00:00 2001
From: miyanialkesh7 <miyanialkesh7@gmail.com>
Date: Tue, 25 Aug 2026 13:26:19 +0530
Subject: [PATCH] Fix PHPCS/WPCS violations and add missing docblocks

Auto-fix mechanical indentation/whitespace violations via phpcbf, add
missing file/class/method docblocks, document two escaping
false-positives with phpcs:ignore, prefix a local template variable,
and exclude the classic WP file-naming sniffs since this plugin uses
namespaced classes autoloaded via Composer's PSR-4.
---
 Functions/Enqueues.php        | 84 ++++++++++++++++++++---------------
 Functions/Plugin_Paths.php    | 36 +++++++++++----
 Functions/Register_Blocks.php | 57 +++++++++++++++---------
 advanced-multi-block.php      | 20 ++++-----
 phpcs.xml.dist                |  4 ++
 src/blocks/banner/render.php  |  6 ++-
 src/blocks/toggle/render.php  | 13 +++---
 7 files changed, 138 insertions(+), 82 deletions(-)

diff --git a/Functions/Enqueues.php b/Functions/Enqueues.php
index d3599ee..068938e 100644
--- a/Functions/Enqueues.php
+++ b/Functions/Enqueues.php
@@ -1,46 +1,58 @@
 <?php
+/**
+ * Enqueues the plugin's editor and frontend script assets.
+ *
+ * @package Advanced_Multi_Block
+ */
 
 namespace Advanced_Multi_Block;
 
 use Advanced_Multi_Block\Plugin_Paths;
 
 if ( ! defined( 'ABSPATH' ) ) {
-  exit;
+	exit;
 }
 
+/**
+ * Enqueues the plugin's editor and frontend script assets.
+ */
 class Enqueues {
-  public function __construct() {
-      add_action( 'enqueue_block_editor_assets', array( $this, 'enqueue_block_assets' ) );
-      add_action( 'wp_enqueue_scripts', array( $this, 'enqueue_frontend_assets' ) );
-  }
-
-  /**
-    * Enqueues the block assets for the editor
-    */
-  public function enqueue_block_assets() {
-      $asset_file = include Plugin_Paths::plugin_path() . 'build/editor-script.asset.php';
-
-      wp_enqueue_script(
-          'editor-script-js',
-          Plugin_Paths::plugin_url() . 'build/editor-script.js',
-          $asset_file['dependencies'],
-          $asset_file['version'],
-          false
-      );
-  }
-
-  /**
-    * Enqueues the block assets for the frontend
-    */
-  public function enqueue_frontend_assets() {
-      $asset_file = include Plugin_Paths::plugin_path() . 'build/frontend-script.asset.php';
-
-      wp_enqueue_script(
-          'frontend-script-js',
-          Plugin_Paths::plugin_url() . 'build/frontend-script.js',
-          $asset_file['dependencies'],
-          $asset_file['version'],
-          true
-      );
-  }
-}
\ No newline at end of file
+
+	/**
+	 * Hooks the asset enqueue callbacks into WordPress.
+	 */
+	public function __construct() {
+		add_action( 'enqueue_block_editor_assets', array( $this, 'enqueue_block_assets' ) );
+		add_action( 'wp_enqueue_scripts', array( $this, 'enqueue_frontend_assets' ) );
+	}
+
+	/**
+	 * Enqueues the block assets for the editor
+	 */
+	public function enqueue_block_assets() {
+		$asset_file = include Plugin_Paths::plugin_path() . 'build/editor-script.asset.php';
+
+		wp_enqueue_script(
+			'editor-script-js',
+			Plugin_Paths::plugin_url() . 'build/editor-script.js',
+			$asset_file['dependencies'],
+			$asset_file['version'],
+			false
+		);
+	}
+
+	/**
+	 * Enqueues the block assets for the frontend
+	 */
+	public function enqueue_frontend_assets() {
+		$asset_file = include Plugin_Paths::plugin_path() . 'build/frontend-script.asset.php';
+
+		wp_enqueue_script(
+			'frontend-script-js',
+			Plugin_Paths::plugin_url() . 'build/frontend-script.js',
+			$asset_file['dependencies'],
+			$asset_file['version'],
+			true
+		);
+	}
+}
diff --git a/Functions/Plugin_Paths.php b/Functions/Plugin_Paths.php
index 7876ffd..6ec0254 100644
--- a/Functions/Plugin_Paths.php
+++ b/Functions/Plugin_Paths.php
@@ -1,16 +1,36 @@
 <?php
+/**
+ * Provides shared filesystem and URL paths for the plugin.
+ *
+ * @package Advanced_Multi_Block
+ */
 
 namespace Advanced_Multi_Block;
 
 if ( ! defined( 'ABSPATH' ) ) {
-  exit;
+	exit;
 }
 
+/**
+ * Resolves the plugin's base URL and filesystem path.
+ */
 class Plugin_Paths {
-  public static function plugin_url() {
-      return plugin_dir_url( dirname( __FILE__ ) );
-  }
-  public static function plugin_path() {
-      return plugin_dir_path( dirname( __FILE__ ) );
-  }
-}
\ No newline at end of file
+
+	/**
+	 * Gets the plugin's base URL.
+	 *
+	 * @return string The plugin's base URL, with a trailing slash.
+	 */
+	public static function plugin_url() {
+		return plugin_dir_url( __DIR__ );
+	}
+
+	/**
+	 * Gets the plugin's base filesystem path.
+	 *
+	 * @return string The plugin's base filesystem path, with a trailing slash.
+	 */
+	public static function plugin_path() {
+		return plugin_dir_path( __DIR__ );
+	}
+}
diff --git a/Functions/Register_Blocks.php b/Functions/Register_Blocks.php
index b3d3ba6..ee3877a 100644
--- a/Functions/Register_Blocks.php
+++ b/Functions/Register_Blocks.php
@@ -1,31 +1,46 @@
 <?php
+/**
+ * Registers the plugin's block types.
+ *
+ * @package Advanced_Multi_Block
+ */
 
 namespace Advanced_Multi_Block;
 
 use Advanced_Multi_Block\Plugin_Paths;
 
 if ( ! defined( 'ABSPATH' ) ) {
-  exit;
+	exit;
 }
 
+/**
+ * Registers the plugin's block types with WordPress.
+ */
 class Register_Blocks {
-  public function __construct() {
-      add_action( 'init', array( $this, 'register_blocks' ) );
-  }
-
-  public function register_blocks() {
-      if ( function_exists( 'wp_register_block_types_from_metadata_collection' ) ) {
-          wp_register_block_types_from_metadata_collection( Plugin_Paths::plugin_path() . 'build/blocks', Plugin_Paths::plugin_path() . '/build/blocks-manifest.php' );
-          return;
-      }
-
-      if ( function_exists( 'wp_register_block_metadata_collection' ) ) {
-          wp_register_block_metadata_collection( Plugin_Paths::plugin_path() . 'build/blocks', Plugin_Paths::plugin_path() . '/build/blocks-manifest.php' );
-      }
-
-      $manifest_data = include Plugin_Paths::plugin_path() . 'build/blocks-manifest.php';
-      foreach ( array_keys( $manifest_data ) as $block_type ) {
-          register_block_type( Plugin_Paths::plugin_path() . "build/blocks/{$block_type}" );
-      }
-  }
-}
\ No newline at end of file
+
+	/**
+	 * Hooks block registration into WordPress init.
+	 */
+	public function __construct() {
+		add_action( 'init', array( $this, 'register_blocks' ) );
+	}
+
+	/**
+	 * Registers all block types found in the build directory's manifest.
+	 */
+	public function register_blocks() {
+		if ( function_exists( 'wp_register_block_types_from_metadata_collection' ) ) {
+			wp_register_block_types_from_metadata_collection( Plugin_Paths::plugin_path() . 'build/blocks', Plugin_Paths::plugin_path() . '/build/blocks-manifest.php' );
+			return;
+		}
+
+		if ( function_exists( 'wp_register_block_metadata_collection' ) ) {
+			wp_register_block_metadata_collection( Plugin_Paths::plugin_path() . 'build/blocks', Plugin_Paths::plugin_path() . '/build/blocks-manifest.php' );
+		}
+
+		$manifest_data = include Plugin_Paths::plugin_path() . 'build/blocks-manifest.php';
+		foreach ( array_keys( $manifest_data ) as $block_type ) {
+			register_block_type( Plugin_Paths::plugin_path() . "build/blocks/{$block_type}" );
+		}
+	}
+}
diff --git a/advanced-multi-block.php b/advanced-multi-block.php
index 51050f6..35df9ab 100644
--- a/advanced-multi-block.php
+++ b/advanced-multi-block.php
@@ -13,25 +13,25 @@
  * @package CreateBlock
  */
 
-if (! defined('ABSPATH') ) {
-  exit;
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
 }
 
 // Include Composer's autoload file.
 if ( file_exists( plugin_dir_path( __FILE__ ) . 'vendor/autoload.php' ) ) {
-  require_once plugin_dir_path( __FILE__ ) . 'vendor/autoload.php';
+	require_once plugin_dir_path( __FILE__ ) . 'vendor/autoload.php';
 } else {
-  wp_trigger_error( 'Advanced Multi Block Plugin: Composer autoload file not found. Please run `composer install`.', E_USER_ERROR );
-  return;
+	wp_trigger_error( 'Advanced Multi Block Plugin: Composer autoload file not found. Please run `composer install`.', E_USER_ERROR );
+	return;
 }
 
 // Instantiate the classes.
 $advanced_multi_block_classes = array(
-  \Advanced_Multi_Block\Plugin_Paths::class,
-  \Advanced_Multi_Block\Register_Blocks::class,
-  \Advanced_Multi_Block\Enqueues::class,
+	\Advanced_Multi_Block\Plugin_Paths::class,
+	\Advanced_Multi_Block\Register_Blocks::class,
+	\Advanced_Multi_Block\Enqueues::class,
 );
 
 foreach ( $advanced_multi_block_classes as $advanced_multi_block_class ) {
-  new $advanced_multi_block_class();
-}
\ No newline at end of file
+	new $advanced_multi_block_class();
+}
diff --git a/phpcs.xml.dist b/phpcs.xml.dist
index dcdc80e..2ebb93b 100644
--- a/phpcs.xml.dist
+++ b/phpcs.xml.dist
@@ -24,6 +24,10 @@
       <exclude name="Generic.Arrays.DisallowShortArraySyntax"/>
       <exclude name="Generic.Functions.CallTimePassByReference"/>
       <exclude name="WordPress.PHP.YodaConditions.NotYoda"/>
+      <!-- Classes are namespaced and autoloaded via Composer's PSR-4, so filenames -->
+      <!-- match class names rather than the classic class-{name}.php convention. -->
+      <exclude name="WordPress.Files.FileName.NotHyphenatedLowercase"/>
+      <exclude name="WordPress.Files.FileName.InvalidClassFileName"/>
   </rule>
  
   <rule ref="WordPress.Arrays.MultipleStatementAlignment">
diff --git a/src/blocks/banner/render.php b/src/blocks/banner/render.php
index ddac8fc..258e943 100644
--- a/src/blocks/banner/render.php
+++ b/src/blocks/banner/render.php
@@ -1,8 +1,12 @@
 <?php
 /**
+ * PHP file to use when rendering the banner block on the server.
+ *
+ * @package Advanced_Multi_Block
  * @see https://github.com/WordPress/gutenberg/blob/trunk/docs/reference-guides/block-api/block-metadata.md#render
  */
+
 ?>
-<p <?php echo get_block_wrapper_attributes(); ?>>
+<p <?php echo get_block_wrapper_attributes(); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- get_block_wrapper_attributes() escapes its own output. ?>>
 	<?php esc_html_e( 'Banner – hello from a dynamic block!', 'advanced-multi-block' ); ?>
 </p>
diff --git a/src/blocks/toggle/render.php b/src/blocks/toggle/render.php
index 1168f16..15fa984 100644
--- a/src/blocks/toggle/render.php
+++ b/src/blocks/toggle/render.php
@@ -7,11 +7,12 @@
  *     $content (string): The block default content.
  *     $block (WP_Block): The block instance.
  *
+ * @package Advanced_Multi_Block
  * @see https://github.com/WordPress/gutenberg/blob/trunk/docs/reference-guides/block-api/block-metadata.md#render
  */
 
 // Generates a unique id for aria-controls.
-$unique_id = wp_unique_id( 'p-' );
+$advanced_multi_block_unique_id = wp_unique_id( 'p-' );
 
 // Adds the global state.
 wp_interactivity_state(
@@ -20,15 +21,15 @@
 		'isDark'    => false,
 		'darkText'  => esc_html__( 'Switch to Light', 'advanced-multi-block' ),
 		'lightText' => esc_html__( 'Switch to Dark', 'advanced-multi-block' ),
-		'themeText'	=> esc_html__( 'Switch to Dark', 'advanced-multi-block' ),
+		'themeText' => esc_html__( 'Switch to Dark', 'advanced-multi-block' ),
 	)
 );
 ?>
 
 <div
-	<?php echo get_block_wrapper_attributes(); ?>
+	<?php echo get_block_wrapper_attributes(); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- get_block_wrapper_attributes() escapes its own output. ?>
 	data-wp-interactive="create-block"
-	<?php echo wp_interactivity_data_wp_context( array( 'isOpen' => false ) ); ?>
+	<?php echo wp_interactivity_data_wp_context( array( 'isOpen' => false ) ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- wp_interactivity_data_wp_context() escapes its own output. ?>
 	data-wp-watch="callbacks.logIsOpen"
 	data-wp-class--dark-theme="state.isDark"
 >
@@ -40,13 +41,13 @@
 	<button
 		data-wp-on--click="actions.toggleOpen"
 		data-wp-bind--aria-expanded="context.isOpen"
-		aria-controls="<?php echo esc_attr( $unique_id ); ?>"
+		aria-controls="<?php echo esc_attr( $advanced_multi_block_unique_id ); ?>"
 	>
 		<?php esc_html_e( 'Toggle', 'advanced-multi-block' ); ?>
 	</button>
 
 	<p
-		id="<?php echo esc_attr( $unique_id ); ?>"
+		id="<?php echo esc_attr( $advanced_multi_block_unique_id ); ?>"
 		data-wp-bind--hidden="!context.isOpen"
 	>
 		<?php