PHP Documentation (#589)

* Block Pattern Component

* I18N Component

* Nav Menus Component

* Scripts & Styles

* Theme Supports Component

* Theme Components

* Theme functions

* Main Plugin File

* Plugin Components

* ACF Component

* Blocks Component

* i18n Component

* Rest Component

* Plugin functions

plugin/inc/ACF/ACF.php

@@ -1,11 +1,16 @@
 <?php
 /**
- * LHPBPP\ACF\Component class
+ * The ACF component.
+ *
+ * This file defines the `ACF` class, which handles logic related to Advanced Custom Fields (ACF)
+ * in the plugin. This includes setting up options pages, managing JSON save/load points, and
+ * configuring ACF-specific settings based on the environment.
  *
  * @package lhpbp\plugin
  */
 
 namespace WpMunich\lhpbp\plugin\ACF;
+
 use WpMunich\lhpbp\plugin\Plugin_Component;
 
 use function WpMunich\lhpbp\plugin\plugin;
@@ -15,11 +20,15 @@
 use function wp_get_environment_type;
 
 /**
- * A class to handle acf related logic.
+ * ACF
+ *
+ * A class to handle ACF-related functionality in the plugin. This class manages the creation
+ * of ACF options pages, JSON save/load paths, and environment-specific settings for ACF.
  */
 class ACF extends Plugin_Component {
+
 	/**
-	 * Validated and final page settings.
+	 * Validated and finalized settings for the ACF options page.
 	 *
 	 * @see https://www.advancedcustomfields.com/resources/acf_add_options_page/
 	 *
@@ -46,23 +55,31 @@ protected function add_filters() {
 	}
 
 	/**
-	 * Add the json save point for acf.
+	 * Set the JSON save path for ACF.
 	 *
-	 * @param  string $path Save path.
+	 * This method configures the directory where ACF JSON data is saved, allowing for
+	 * custom save points in development environments. This feature is helpful for version
+	 * control of ACF fields.
 	 *
-	 * @return string       Save path.
+	 * @param  string $path The default save path.
+	 *
+	 * @return string The modified save path for ACF JSON data.
 	 */
 	public function acf_json_save_point( $path ) {
 		$path = plugin()->get_plugin_path() . 'acf-json';
 		return $path;
 	}
 
 	/**
-	 * Add the json load point for acf.
+	 * Add a custom JSON load path for ACF.
+	 *
+	 * This method adds the specified directory to the list of locations from which
+	 * ACF JSON data can be loaded. This setup enables shared ACF configurations across
+	 * different environments.
 	 *
 	 * @param  array $paths An array of paths.
 	 *
-	 * @return array        An array of paths.
+	 * @return array The modified array of JSON load paths.
 	 */
 	public function acf_json_load_point( $paths ) {
 		$paths[] = plugin()->get_plugin_path() . 'acf-json';
@@ -71,7 +88,11 @@ public function acf_json_load_point( $paths ) {
 	}
 
 	/**
-	 * Add a theme options page.
+	 * Add an ACF options page for theme settings.
+	 *
+	 * This method creates a custom options page for managing theme-specific settings
+	 * via ACF. It sets up page attributes like title, menu slug, icon, and user
+	 * capability requirements.
 	 */
 	public function add_options_page() {
 		if ( ! function_exists( 'acf_add_options_page' ) ) {

plugin/inc/Abstracts/Component.php

@@ -1,10 +1,10 @@
 <?php
 /**
- * This file contains the abstract component class.
- * It is used to define the basic structure of a component, which we use to
- * extend the plugin and the accompanying theme. A component is a class that
- * contains all the logic for a specific feature of the plugin or theme. It combines
- * actions and filters, the logic and helper functions.
+ * The abstract base class for a component.
+ *
+ * This file defines the `Component` class, which provides the core structure for all plugin
+ * and theme components. Components encapsulate the logic, actions, filters, and helper functions
+ * needed for specific features within the plugin or theme.
  *
  * @package lhpbp\plugin
  */
@@ -14,12 +14,22 @@
 use function WpMunich\lhpbp\plugin\plugin_container;
 
 /**
- * Abstract class for a component.
+ * Component
+ *
+ * An abstract class that defines the structure and behavior for components within the plugin
+ * or theme. Components extending this class should implement `add_actions()` and `add_filters()`
+ * methods to define their WordPress-specific hooks.
+ *
+ * @abstract
  */
 abstract class Component {
+
 	/**
 	 * Constructor.
-	 * Used to initialize the component and add the needed actions and filters.
+	 *
+	 * Initializes the component by calling the `add_actions()` and `add_filters()` methods,
+	 * which child classes must implement. This constructor ensures each component sets up
+	 * its actions and filters when instantiated.
 	 *
 	 * @return void
 	 */
@@ -29,30 +39,35 @@ public function __construct() {
 	}
 
 	/**
-	 * Add the needed WordPress actions for the component.
+	 * Register WordPress actions for the component.
 	 *
 	 * @see https://codex.wordpress.org/Plugin_API/Action_Reference
+	 * @return void
 	 */
 	abstract protected function add_actions();
 
 	/**
-	 * Add the needed WordPress filters for the component.
+	 * Register WordPress filters for the component.
 	 *
 	 * @see https://codex.wordpress.org/Plugin_API/Filter_Reference
+	 * @return void
 	 */
 	abstract protected function add_filters();
 
 	/**
-	 * Get the parent class.
+	 * Get the parent class of the component instance.
 	 *
-	 * @return Object The parent class.
+	 * @return string|false The name of the parent class, or false if no parent.
 	 */
 	public function get_parent() {
 		return get_parent_class( $this );
 	}
 
 	/**
-	 * Get the DI container.
+	 * Access the Dependency Injection (DI) container.
+	 *
+	 * The DI container provides access to shared services and instances used throughout
+	 * the plugin or theme, promoting reusability and modularity.
 	 *
 	 * @return \DI\Container The DI container.
 	 */

plugin/inc/Blocks/Blocks.php

@@ -1,37 +1,39 @@
 <?php
 /**
- * LHPBPP\Blocks\Component class
+ * The Blocks component.
+ *
+ * This file defines the `Blocks` class, which handles the registration, categorization,
+ * and management of custom blocks within the plugin. This includes enqueuing necessary
+ * assets for block editing and providing callback functions for rendering.
  *
  * @package lhpbp\plugin
  */
 
 namespace WpMunich\lhpbp\plugin\Blocks;
+
 use WpMunich\lhpbp\plugin\Plugin_Component;
 
 use function WpMunich\lhpbp\plugin\plugin;
-use function acf_register_block_type;
 use function add_action;
 use function add_filter;
-use function apply_filters;
 use function get_current_screen;
 use function register_block_type;
 use function wp_enqueue_script;
 use function wp_json_file_decode;
 use function wp_set_script_translations;
 
 /**
- * A class to handle the plugins blocks.
+ * Blocks
+ *
+ * A class to handle the plugin's custom blocks. It registers blocks, assigns them to custom
+ * categories, enqueues block editor assets, and defines rendering callbacks for block display.
  */
 class Blocks extends Plugin_Component {
 
 	/**
 	 * {@inheritDoc}
 	 */
 	protected function add_actions() {
-		if ( function_exists( 'acf_register_block_type' ) ) {
-			add_action( 'acf/init', array( $this, 'register_acf_block_types' ) );
-		}
-
 		add_action( 'enqueue_block_editor_assets', array( $this, 'enqueue_block_editor_assets' ) );
 		add_action( 'init', array( $this, 'register_blocks' ) );
 	}
@@ -44,34 +46,12 @@ protected function add_filters() {
 	}
 
 	/**
-	 * Register ACF driven blocks.
+	 * Register the plugin's custom block category.
 	 *
-	 * @return void
-	 */
-	public function register_acf_block_types() {
-		acf_register_block_type(
-			array(
-				'name'            => 'acf-demo-block',
-				'title'           => __( 'Demo Block', 'lhpbpp' ),
-				'description'     => __( 'A demo block to show that everything is working.', 'lhpbpp' ),
-				'category'        => 'lhpbpp-blocks',
-				'icon'            => 'screenoptions',
-				'keywords'        => array( __( 'ACF', 'lhpbpp' ), __( 'Demo', 'lhpbpp' ), __( 'Block', 'lhpbpp' ) ),
-				'render_template' => apply_filters( 'lh_acf_block_template_path', plugin()->get_plugin_path() . 'blocks/acf/template.php', 'acf-demo-block' ),
-				'mode'            => 'auto',
-				'supports'        => array(
-					'align' => array( 'wide', 'full' ),
-					'mode'  => 'auto',
-				),
-			)
-		);
-	}
-
-	/**
-	 * Register the plugins custom block category.
+	 * @param array   $categories The existing block categories.
+	 * @param WP_Post $post       The current post being edited.
 	 *
-	 * @param array   $categories The block categories.
-	 * @param WP_Post $post     The current post that is edited.
+	 * @return array The updated array of block categories, including the custom category.
 	 */
 	public function add_block_categories( $categories, $post ) {
 		return array_merge(
@@ -86,13 +66,18 @@ public function add_block_categories( $categories, $post ) {
 	}
 
 	/**
-	 * Enqueue the block scripts and styles.
+	 * Enqueue the block editor scripts and styles.
+	 *
+	 * Enqueues JavaScript and CSS assets required for the block editor, including helper scripts
+	 * and translations for the block UI.
 	 */
 	public function enqueue_block_editor_assets() {
 		$screen = get_current_screen();
 
+		// Load asset configuration.
 		$assets = wp_json_file_decode( plugin()->get_plugin_path() . '/admin/dist/assets.json', array( 'associative' => true ) );
 
+		// Enqueue block helper script outside the widgets screen.
 		if ( ! in_array( $screen->id, array( 'widgets' ), true ) ) {
 			$block_helper_assets = $assets['js/blocks-helper.min.js'] ?? array();
 			wp_enqueue_script(
@@ -121,9 +106,7 @@ public function enqueue_block_editor_assets() {
 			'all'
 		);
 
-		/**
-		 * Load the translations for the block editor assets.
-		 */
+		// Load translations for block editor assets.
 		$dir  = plugin()->get_plugin_path();
 		$path = $dir . '/languages/';
 
@@ -141,7 +124,10 @@ public function enqueue_block_editor_assets() {
 	}
 
 	/**
-	 * Register the blocks.
+	 * 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/';
@@ -161,13 +147,16 @@ public function register_blocks() {
 	}
 
 	/**
-	 * Provide the render callback for the block.
+	 * 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 type.
+	 * @param string   $content    The block content.
+	 * @param WP_Block $block      The block instance.
 	 *
-	 * @return string The rendered block.
+	 * @return string The rendered block HTML.
 	 */
 	public function provide_render_callback( $attributes, $content, $block ) {
 		$blocks_path = plugin()->get_plugin_path() . 'blocks/';