V5-alpha #2

modified:   CHANGELOG.md
modified:   README.md
new file:   src/changelog.txt
modified:   src/src/admin/class-admin-notifications.php
modified:   src/src/core/class-lifecycle.php
modified:   src/src/registerables/metaboxes/class-base-metabox.php
modified:   src/src/registerables/metaboxes/class-image-upload-metabox.php
modified:   src/src/utilities/class-wp-filesystem-utility.php

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 2023-10-11
+- v5-alpha update
+
 ## 2023-08-01
 ### Changed 
 - Use Constant instead of function for the plugin base name

README.md

@@ -1,5 +1,5 @@
 # Better WordPress Plugin Boilerplate ![GitHub contributors](https://img.shields.io/github/contributors/TukuToi/better-wp-plugin-boilerplate) ![GitHub last commit](https://img.shields.io/github/last-commit/TukuToi/better-wp-plugin-boilerplate)
-[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=TukuToi_better-wp-plugin-boilerplate&metric=bugs)](https://sonarcloud.io/dashboard?id=TukuToi_better-wp-plugin-boilerplate) [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=TukuToi_better-wp-plugin-boilerplate&metric=vulnerabilities)](https://sonarcloud.io/dashboard?id=TukuToi_better-wp-plugin-boilerplate) [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=TukuToi_better-wp-plugin-boilerplate&metric=sqale_rating)](https://sonarcloud.io/dashboard?id=TukuToi_better-wp-plugin-boilerplate) [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=TukuToi_better-wp-plugin-boilerplate&metric=reliability_rating)](https://sonarcloud.io/dashboard?id=TukuToi_better-wp-plugin-boilerplate) [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=TukuToi_better-wp-plugin-boilerplate&metric=security_rating)](https://sonarcloud.io/dashboard?id=TukuToi_better-wp-plugin-boilerplate) [PHPUnit](https://github.com/tukutoi/better-wp-plugin-boilerplate/actions/workflows/phpunit.yml/badge.svg) [![WPCS](https://github.com/tukutoi/better-wp-plugin-boilerplate/actions/workflows/wpcs.yml/badge.svg)]
+[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=TukuToi_better-wp-plugin-boilerplate&metric=bugs)](https://sonarcloud.io/dashboard?id=TukuToi_better-wp-plugin-boilerplate) [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=TukuToi_better-wp-plugin-boilerplate&metric=vulnerabilities)](https://sonarcloud.io/dashboard?id=TukuToi_better-wp-plugin-boilerplate) [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=TukuToi_better-wp-plugin-boilerplate&metric=sqale_rating)](https://sonarcloud.io/dashboard?id=TukuToi_better-wp-plugin-boilerplate) [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=TukuToi_better-wp-plugin-boilerplate&metric=reliability_rating)](https://sonarcloud.io/dashboard?id=TukuToi_better-wp-plugin-boilerplate) [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=TukuToi_better-wp-plugin-boilerplate&metric=security_rating)](https://sonarcloud.io/dashboard?id=TukuToi_better-wp-plugin-boilerplate) [![Run PHPUnit](https://github.com/TukuToi/better-wp-plugin-boilerplate/actions/workflows/phpunit.yml/badge.svg)](https://github.com/TukuToi/better-wp-plugin-boilerplate/actions/workflows/phpunit.yml) [![WordPress Coding Standards](https://github.com/TukuToi/better-wp-plugin-boilerplate/actions/workflows/wpcs.yml/badge.svg)](https://github.com/TukuToi/better-wp-plugin-boilerplate/actions/workflows/wpcs.yml)
 
 The Better WordPress Plugin Boilerplate is an advanced starting point for developers looking to create robust and standards-compliant plugins for WordPress and ClassicPress. In a landscape where coding standards and best practices are pivotal, this Boilerplate provides a structured, organized, and modern foundation, ensuring your plugin starts on the right foot.
 

src/src/admin/class-admin-notifications.php

@@ -61,6 +61,7 @@ class Admin_Notifications {
 	 * Public method to print requirements notice.
 	 *
 	 * phpcs: output safe, as coming directly from plugin file.
+	 * reviewers: phpcs:ignore is used deterministically because GitHub WPCS Workflow fails otherwise.
 	 *
 	 * @since  1.0.0 Introduced on 2023-08-02 15:14
 	 * @author Beda Schmid <[email protected]>
@@ -71,6 +72,7 @@ public static function print_requirement_notice(): void {
 		$notice = ( WP_Filesystem_Utility::get_filesystem() )
 			->get_contents( Config::get( 'plugin_dir' ) . 'resources/admin-requirements-notice.php' );
 		printf(
+			// phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
 			$notice,
 			esc_html( Config::get( 'human_name' ) ),
 			esc_html__( ' activation failed! Please read', 'plugin-slug' ),

src/src/core/class-lifecycle.php

@@ -73,13 +73,18 @@ class Lifecycle {
 	 * Checks if the plugin was (safely) activated.
 	 * Place to add any custom action during plugin activation.
 	 *
+	 * phpcs: not a security issue.
+	 * reviewers: phpcs:ignore is used deterministically because GitHub WPCS Workflow fails otherwise.
+	 * The developer should however have remmoved this section, if unused, on release.
+	 *
 	 * @since  1.0.0 Introduced on 2023-08-01 15:30
 	 * @author Your Name <[email protected]>
 	 * @access public
 	 * @return void
 	 */
 	public static function activate(): void {
 
+		// phpcs:ignore Generic.CodeAnalysis.EmptyStatement.DetectedIf
 		if ( self::is_request_valid( 'activate_plugins', 'activate-plugin_' ) ) {
 			/**
 			 * It is now safe to perform your custom activation actions here.
@@ -97,13 +102,18 @@ public static function activate(): void {
 	 * Checks if the plugin was (safely) deactivated.
 	 * Place to add any custom action during plugin deactivation.
 	 *
+	 * phpcs: not a security issue.
+	 * reviewers: phpcs:ignore is used deterministically because GitHub WPCS Workflow fails otherwise.
+	 * The developer should however have remmoved this section, if unused, on release.
+	 *
 	 * @since  1.0.0 Introduced on 2023-08-01 15:30
 	 * @author Your Name <[email protected]>
 	 * @access public
 	 * @return void
 	 */
 	public static function deactivate(): void {
 
+		// phpcs:ignore Generic.CodeAnalysis.EmptyStatement.DetectedIf
 		if ( self::is_request_valid( 'deactivate_plugins', 'deactivate-plugin_' ) ) {
 			/**
 			 * It is now safe to perform your custom deactivation actions here.
@@ -121,13 +131,18 @@ public static function deactivate(): void {
 	 * Checks if the plugin was (safely) uninstalled.
 	 * Place to add any custom action during plugin uninstallation.
 	 *
+	 * phpcs: not a security issue.
+	 * reviewers: phpcs:ignore is used deterministically because GitHub WPCS Workflow fails otherwise.
+	 * The developer should however have remmoved this section, if unused, on release.
+	 *
 	 * @since  1.0.0 Introduced on 2023-08-01 15:30
 	 * @author Your Name <[email protected]>
 	 * @access public
 	 * @return void
 	 */
 	public static function uninstall(): void {
 
+		// phpcs:ignore Generic.CodeAnalysis.EmptyStatement.DetectedIf
 		if ( self::is_uninstall_request_valid( 'delete_plugins' ) ) {
 			/**
 			 * It is now safe to perform your custom uninstall actions here.

src/src/registerables/metaboxes/class-base-metabox.php

@@ -1,53 +1,154 @@
 <?php
+/**
+ * The Base Metabox class file
+ *
+ * This file registers the Base Metabox class.
+ * This file includes:
+ * - Strict Typing declaration,
+ * - Namespace declaration,
+ * - Use declarations,
+ * - Check for direct access,
+ * - Base Metabox Class Declaration
+ *
+ * @link    https://site.tld
+ * @since   1.0.0 Introduced on 2023-08-01 15:30
+ * @package Company\Plugins\PluginName\Registerables\Metaboxes
+ * @author  Your Name <[email protected]>
+ */
 
-declare(strict_types=1);
+/**
+ * Declare strict typing
+ *
+ * @see https://www.php.net/manual/en/language.types.declarations.php#language.types.declarations.strict
+ */
+declare( strict_types = 1 );
 
+/**
+ * Declare the namespace
+ *
+ * @see https://www.php.net/manual/en/language.namespaces.php
+ */
 namespace Company\Plugins\PluginName\Registerables\Metaboxes;
 
 use Company\Plugins\PluginName\Registerables\Base_WP_Registerable;
 
-if (!defined('ABSPATH')) {
-    exit;
+/**
+ * Exit the code if this file is accessed directly
+ */
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
 }
 
+/**
+ * The Base Metabox Class
+ *
+ * Base Metabox class provides abstracts and methods to register a new Metabox.
+ *
+ * @since   1.0.0 Introduced on 2023-08-01 15:30
+ * @package Company\Plugins\PluginName\Registerables\Metaboxes
+ * @author  Your Name <[email protected]>
+ */
 abstract class Base_Metabox extends Base_WP_Registerable {
-    protected array $post_types = [];
-    protected array $user_roles = [];
-    protected array $taxonomies = [];
 
-    abstract public function render(): void;
+	/**
+	 * Post types to assign metabox
+	 *
+	 * @since  1.0.0 Introduced on 2023-08-02 14:14
+	 * @author Your Name <[email protected]>
+	 * @access private
+	 * @var array $post_types Array of the post types to assign the metabox to.
+	 */
+	protected array $post_types = array();
 
-    public function register(): void {
-        if (!empty($this->post_types)) {
-			add_action('add_meta_boxes', [$this, 'register_metaboxes_for_post_types']);
+	/**
+	 * User Roles to assign metabox
+	 *
+	 * @since  1.0.0 Introduced on 2023-08-02 14:14
+	 * @author Your Name <[email protected]>
+	 * @access private
+	 * @var array $user_roles Array of the user roles to assign the metabox to.
+	 */
+	protected array $user_roles = array();
+
+	/**
+	 * Taxonomies to assign metabox
+	 *
+	 * @since  1.0.0 Introduced on 2023-08-02 14:14
+	 * @author Your Name <[email protected]>
+	 * @access private
+	 * @var array $taxonomies Array of the taxonomies to assign the metabox to.
+	 */
+	protected array $taxonomies = array();
+
+	/**
+	 * Abstract method to render metabox
+	 *
+	 * Provides an abstract to render the metabox
+	 *
+	 * @since 1.0.0 Introduced on 2023-10-08 17:09
+	 * @see https://developer.wordpress.org/reference/functions/add_meta_box/#parameters
+	 * @author Beda Schmid <[email protected]>
+	 * @return array
+	 */
+	abstract public function render(): void;
+
+	/**
+	 * Register Metabox
+	 *
+	 * Registers the metabox with WordPress
+	 *
+	 * @since 1.0.0 Introduced on 2023-10-08 17:09
+	 * @see https://developer.wordpress.org/reference/functions/add_meta_box/
+	 * @author Beda Schmid <[email protected]>
+	 * @return void
+	 */
+	public function register(): void {
+
+		/**
+		 * Register for Post types if any
+		 */
+		if ( ! empty( $this->post_types ) ) {
+			add_action( 'add_meta_boxes', array( $this, 'register_metaboxes_for_post_types' ) );
 		}
 
-        // Register metabox for users
-        if (!empty($this->user_roles)) {
-            add_action('show_user_profile', [$this, 'render']);
-            add_action('edit_user_profile', [$this, 'render']);
-        }
+		/**
+		 * Register for User Roles if any
+		 */
+		if ( ! empty( $this->user_roles ) ) {
+			add_action( 'show_user_profile', array( $this, 'render' ) );
+			add_action( 'edit_user_profile', array( $this, 'render' ) );
+		}
 
-        // Register metabox for taxonomies
-        foreach ($this->taxonomies as $taxonomy) {
-            add_action("{$taxonomy}_add_form_fields", [$this, 'render']);
-            add_action("{$taxonomy}_edit_form_fields", [$this, 'render']);
-        }
-    }
+		/**
+		 * Register for Taxonomies if any
+		 */
+		foreach ( $this->taxonomies as $taxonomy ) {
+			add_action( "{$taxonomy}_add_form_fields", array( $this, 'render' ) );
+			add_action( "{$taxonomy}_edit_form_fields", array( $this, 'render' ) );
+		}
+	}
 
+	/**
+	 * Callback for Post Types
+	 *
+	 * True metaboxes are only available on Post Types.
+	 *
+	 * @since 1.0.0 Introduced on 2023-10-08 17:09
+	 * @see https://developer.wordpress.org/reference/functions/add_meta_box/#parameters
+	 * @author Beda Schmid <[email protected]>
+	 * @return void
+	 */
 	public function register_metaboxes_for_post_types(): void {
-		foreach ($this->post_types as $post_type) {
+		foreach ( $this->post_types as $post_type ) {
 			add_meta_box(
 				$this->get_key() . '_' . $post_type,
-				ucwords(str_replace('_', ' ', $this->get_key())),
-				[$this, 'render'],
-				$post_type, 
-				'side', 
-				'high', 
+				ucwords( str_replace( '_', ' ', $this->get_key() ) ),
+				array( $this, 'render' ),
+				$post_type,
+				'side',
+				'high',
 				null
 			);
 		}
 	}
-
-    // Additional methods to set the post types, user roles, and taxonomies can be added if needed
 }

src/src/registerables/metaboxes/class-image-upload-metabox.php

@@ -1,30 +1,97 @@
 <?php
+/**
+ * The Specialised Image Upload Metabox class file
+ *
+ * This file registers the Image Upload Metabox class.
+ * This file includes:
+ * - Strict Typing declaration,
+ * - Namespace declaration,
+ * - Use declarations,
+ * - Check for direct access,
+ * - Image Upload Metabox Class Declaration
+ *
+ * @link    https://site.tld
+ * @since   1.0.0 Introduced on 2023-08-01 15:30
+ * @package Company\Plugins\PluginName\Registerables\Metaboxes
+ * @author  Your Name <[email protected]>
+ */
 
-declare(strict_types=1);
+/**
+ * Declare strict typing
+ *
+ * @see https://www.php.net/manual/en/language.types.declarations.php#language.types.declarations.strict
+ */
+declare( strict_types = 1 );
 
+/**
+ * Declare the namespace
+ *
+ * @see https://www.php.net/manual/en/language.namespaces.php
+ */
 namespace Company\Plugins\PluginName\Registerables\MetaBoxes;
 
 use Company\Plugins\PluginName\Registerables\Metaboxes\Base_Metabox;
 
-if (!defined('ABSPATH')) {
-    exit;
+/**
+ * Exit the code if this file is accessed directly
+ */
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
 }
 
+/**
+ * The Image Upload Metabox Class
+ *
+ * Image Upload Metabox class registers a Media Upload metabox for:
+ * - posts, pages, items,
+ * - administrators, editors,
+ * - categories, tags, collections.
+ *
+ * @since   1.0.0 Introduced on 2023-08-01 15:30
+ * @package Company\Plugins\PluginName\Registerables\Metaboxes
+ * @author  Your Name <[email protected]>
+ */
 class Image_Upload_Metabox extends Base_Metabox {
 
 
-    public function __construct() {
-        // Define the post types, user roles, and taxonomies where the metabox should be added
-        $this->post_types = ['post', 'page', 'item'];
-        $this->user_roles = ['administrator', 'editor'];
-        $this->taxonomies = ['category', 'post_tag', 'collection'];
-    }
+	/**
+	 * Initiate class properties
+	 *
+	 * Defines object types to which the metebox will be assigned
+	 *
+	 * @since 1.0.0 Introduced on 2023-10-08 17:09
+	 * @author Beda Schmid <[email protected]>
+	 * @return void
+	 */
+	public function __construct() {
+		$this->post_types = array( 'post', 'page', 'item' );
+		$this->user_roles = array( 'administrator', 'editor' );
+		$this->taxonomies = array( 'category', 'post_tag', 'collection' );
+	}
 
+	/**
+	 * Set registerable key
+	 *
+	 * Sets the metabox unique key.
+	 *
+	 * @since 1.0.0 Introduced on 2023-10-08 17:09
+	 * @author Beda Schmid <[email protected]>
+	 * @return void
+	 */
 	protected function set_key(): void {
-        $this->key = 'my-box';
-    }
-
-    public function render(): void {
-        echo '<input type="file" name="custom_image_upload" />';
-    }
+		$this->key = 'my-box';
+	}
+
+	/**
+	 * Render the metabox
+	 *
+	 * A metabox needs to be rendered. This can be as simple or as complex as required.
+	 *
+	 * @since 1.0.0 Introduced on 2023-10-08 17:09
+	 * @author Beda Schmid <[email protected]>
+	 * @return void
+	 */
+	public function render(): void {
+		echo '<input type="file" name="custom_image_upload" />';
+	}
 }