WIP: SlimPlugin, some interfaces, filter storage and more

CHANGELOG.md

+## [1.4.0] - 2019-09-26
+### Added
+- SlimPlugin - abstract class with only most important plugin elements
+- AbstractPlugin - docs and cleaning
+- Activateable - interface to tag plugin to hook into activation hook
+- Deactivateable - interface to tag plugin to hook into deactivation hook
+- Conditional - interface to tag classes that should be instantiated/hooked only in given state
+### Changed
+- WordpressFilterStorage - store plugin using WordPress filter system
+### Fixed
+- Fixed assets and plugin url issues
+
 ## [1.3.4] - 2019-09-26
 ### Fixed
 - Gitlab.ci

src/Plugin/AbstractPlugin.php

@@ -3,31 +3,50 @@
 namespace WPDesk\PluginBuilder\Plugin;
 
 /**
- * Base plugin class for WP Desk plugins.
+ * Base plugin with most basic functionalities used by every WPDesk plugin.
  *
- * *************************************************************
- * * Important! This class should be not modified!             *
- * * This class is loaded at startup from first loaded plugin! *
- * *************************************************************
  *
- * @author Grzegorz, Dyszczo
+ * Known issues:
  *
+ * The class name is too generic but can't be changed as it would introduce a major incompatibility for most of the plugins.
+ * The $plugin_url, $docs_url and most other fields should be removed as they only litter the place but for compatibility reasons we can't do it right now.
+ * Hook methods should be moved to external classes but for compatibility reasons we can't do it right now.
  */
-abstract class AbstractPlugin implements \WPDesk_Translable {
+abstract class AbstractPlugin extends SlimPlugin {
 
-	/** @var \WPDesk_Plugin_Info */
+	/**
+	 * Most info about plugin internals.
+	 *
+	 * @var \WPDesk_Plugin_Info
+	 */
 	protected $plugin_info;
 
-	/** @var string */
+	/**
+	 * Unique string for this plugin in [a-z_]+ format.
+	 *
+	 * @var string
+	 */
 	protected $plugin_namespace;
 
-	/** @var string */
+	/**
+	 * Absolute URL to the plugin dir.
+	 *
+	 * @var string
+	 */
 	protected $plugin_url;
 
-	/** @var string */
+	/**
+	 * Absolute URL to the plugin docs.
+	 *
+	 * @var string
+	 */
 	protected $docs_url;
 
-	/** @var string */
+	/**
+	 * Absolute URL to the plugin settings url.
+	 *
+	 * @var string
+	 */
 	protected $settings_url;
 
 	/**
@@ -45,34 +64,35 @@ abstract class AbstractPlugin implements \WPDesk_Translable {
 	public function __construct( $plugin_info ) {
 		$this->plugin_info      = $plugin_info;
 		$this->plugin_namespace = strtolower( $plugin_info->get_plugin_dir() );
-	}
-
-	public function init() {
+		$this->plugin_url       = $this->plugin_info->get_plugin_url();
 		$this->init_base_variables();
-		$this->hooks();
 	}
 
+	/**
+	 * Initialize internal state of the plugin.
+	 *
+	 * @return void
+	 * @deprecated Just use __construct to initialize plugin internal state.
+	 *
+	 */
 	public function init_base_variables() {
-		$this->plugin_url = plugin_dir_url( $this->plugin_info->get_plugin_dir() );
 	}
 
 	/**
+	 * Initializes plugin external state.
+	 *
+	 * The plugin internal state is initialized in the constructor and the plugin should be internally consistent after creation.
+	 * The external state includes hooks execution, communication with other plugins, integration with WC etc.
+	 *
 	 * @return void
 	 */
-	protected function hooks() {
-		add_action( 'admin_enqueue_scripts', [ $this, 'admin_enqueue_scripts' ] );
-
-		add_action( 'wp_enqueue_scripts', [ $this, 'wp_enqueue_scripts' ] );
-
-		add_action( 'plugins_loaded', [ $this, 'load_plugin_text_domain' ] );
-		add_filter( 'plugin_action_links_' . plugin_basename( $this->get_plugin_file_path() ), [
-			$this,
-			'links_filter'
-		] );
-
+	public function init() {
+		$this->hooks();
 	}
 
 	/**
+	 * Returns absolute path to the plugin dir.
+	 *
 	 * @return string
 	 */
 	public function get_plugin_file_path() {
@@ -80,59 +100,95 @@ abstract class AbstractPlugin implements \WPDesk_Translable {
 	}
 
 	/**
-	 * @return $this
+	 * Returns plugin text domain.
+	 *
+	 * @return string
 	 */
-	public function get_plugin() {
-		return $this;
+	public function get_text_domain() {
+		return $this->plugin_info->get_text_domain();
 	}
 
 	/**
-	 * @return void
+	 * Returns unique string for plugin in [a-z_]+ format. Can be used as plugin id in various places like plugin slug etc.
+	 *
+	 * @return string
 	 */
-	public function load_plugin_text_domain() {
-		load_plugin_textdomain( $this->get_text_domain(), false, $this->get_namespace() . '/lang/' );
+	public function get_namespace() {
+		return $this->plugin_namespace;
 	}
 
 	/**
+	 * Returns plugin absolute URL.
+	 *
 	 * @return string
 	 */
-	public function get_text_domain() {
-		return $this->plugin_info->get_text_domain();
+	public function get_plugin_url() {
+		return esc_url( trailingslashit( $this->plugin_url ) );
 	}
 
 	/**
+	 * Returns plugin absolute URL to dir with front end assets.
+	 *
 	 * @return string
 	 */
-	public function get_namespace() {
-		return $this->plugin_namespace;
-	}
-
 	public function get_plugin_assets_url() {
 		return esc_url( trailingslashit( $this->get_plugin_url() . 'assets' ) );
 	}
 
 	/**
+	 * @return $this
+	 * @deprecated For backward compatibility.
 	 *
-	 * @return string
 	 */
-	public function get_plugin_url() {
-		return esc_url( trailingslashit( $this->plugin_url ) );
+	public function get_plugin() {
+		return $this;
+	}
+
+	/**
+	 * Integrate with WordPress and with other plugins using action/filter system.
+	 *
+	 * @return void
+	 */
+	protected function hooks() {
+		add_action( 'admin_enqueue_scripts', [ $this, 'admin_enqueue_scripts' ] );
+		add_action( 'wp_enqueue_scripts', [ $this, 'wp_enqueue_scripts' ] );
+		add_action( 'plugins_loaded', [ $this, 'load_plugin_text_domain' ] );
+		add_filter( 'plugin_action_links_' . plugin_basename( $this->get_plugin_file_path() ), [
+			$this,
+			'links_filter'
+		] );
+	}
+	/**
+	 * Initialize plugin test domain. This is a hook function. Do not execute directly.
+	 *
+	 * @return void
+	 */
+	public function load_plugin_text_domain() {
+		load_plugin_textdomain( $this->get_text_domain(), false, $this->get_namespace() . '/lang/' );
 	}
 
+	/**
+	 * Append JS scripts in the WordPress admin panel. This is a hook function. Do not execute directly.
+	 *
+	 * @return void
+	 */
 	public function admin_enqueue_scripts() {
 	}
 
+	/**
+	 * Append JS scripts in WordPress. This is a hook function. Do not execute directly.
+	 *
+	 * @return void
+	 */
 	public function wp_enqueue_scripts() {
 	}
 
 	/**
-	 * action_links function.
-	 *
-	 * @access public
+	 * Initialize plugin admin links. This is a hook function. Do not execute directly.
 	 *
-	 * @param mixed $links
+	 * @param string[] $links
 	 *
-	 * @return array
+	 * @return string[]
 	 */
 	public function links_filter( $links ) {
 		$support_link = get_locale() === 'pl_PL' ? 'https://www.wpdesk.pl/support/' : 'https://www.wpdesk.net/support';

src/Plugin/Activateable.php

+<?php
+
+
+namespace WPDesk\PluginBuilder\Plugin;
+
+/**
+ * Tag the plugin with this ingterface to hook it to the WordPress activation hook.
+ *
+ * Note: works from plugin flow ^2.2.
+ *
+ * @package WPDesk\PluginBuilder\Plugin
+ */
+interface Activateable {
+
+	/**
+	 * Plugin activated in WordPress. Do not execute directly.
+	 *
+	 * @return void
+	 */
+	public function activate();
+}

src/Plugin/ActivationAware.php

@@ -3,7 +3,7 @@
 namespace WPDesk\PluginBuilder\Plugin;
 
 /**
- * It means that this class is should know about subscription activation
+ * It means that this class is should know about SUBSCRIPTION activation
  *
  * @package WPDesk\PluginBuilder\Plugin
  */

src/Plugin/Conditional.php

+<?php
+
+
+namespace WPDesk\PluginBuilder\Plugin;
+
+/**
+ * Something that can be instantiated/hooked conditionally.
+ *
+ * @see https://github.com/mwpd/basic-scaffold/blob/master/src/Infrastructure/Conditional.php by Alain Schlesser
+ *
+ * @package WPDesk\PluginBuilder\Plugin
+ */
+interface Conditional {
+	/**
+	 * Check whether the conditional object is currently needed.
+	 *
+	 * @return bool Whether the conditional object is needed.
+	 */
+	public static function is_needed();
+}

src/Plugin/Deactivateable.php

+<?php
+
+
+namespace WPDesk\PluginBuilder\Plugin;
+
+/**
+ * Tag the plugin with this ingterface to hook it to the WordPress deactivation hook.
+ *
+ * Note: works from plugin flow ^2.2.
+ *
+ * @package WPDesk\PluginBuilder\Plugin
+ */
+interface Deactivateable {
+
+	/**
+	 * Plugin deactivate in WordPress. Do not execute directly.
+	 *
+	 * @return void
+	 */
+	public function deactivate();
+}

src/Plugin/HookableParent.php

@@ -45,8 +45,14 @@ trait HookableParent {
 	protected function hooks_on_hookable_objects() {
 		/** @var Hookable $hookable_object $hookable_object */
 		foreach ( $this->hookable_objects as $hookable_object ) {
+			if ($hookable_object instanceof Conditional) {
+				if ($hookable_object::is_needed()) {
 					$hookable_object->hooks();
 				}
+			} else {
+				$hookable_object->hooks();
+			}
+		}
 	}
 
 

src/Plugin/SlimPlugin.php

+<?php
+
+namespace WPDesk\PluginBuilder\Plugin;
+
+/**
+ * Most clean plugin class with only most important details.
+ */
+abstract class SlimPlugin implements \WPDesk_Translatable {
+
+	/**
+	 * Initializes plugin external state.
+	 *
+	 * The plugin internal state is initialized in the constructor and the plugin should be internally consistent after creation.
+	 * The external state includes hooks execution, communication with other plugins, integration with WC etc.
+	 *
+	 * @return void
+	 */
+	abstract public function init();
+}
+

src/Storage/StorageFactory.php

@@ -8,7 +8,7 @@ class StorageFactory {
 	 * @return PluginStorage
 	 */
 	public function create_storage() {
-		return new StaticStorage();
+		return new WordpressFilterStorage();
 	}
 }
 

src/Storage/WordpressFilterStorage.php

+<?php
+
+namespace WPDesk\PluginBuilder\Storage;
+
+use WPDesk\PluginBuilder\Plugin\AbstractPlugin;
+
+/**
+ * Can store plugin instances in WordPress filter system.
+ *
+ * @package WPDesk\PluginBuilder\Storage
+ */
+class WordpressFilterStorage implements PluginStorage {
+	const STORAGE_FILTER_NAME = 'wpdesk_plugin_instances';
+
+	/**
+	 * @param string $class
+	 * @param AbstractPlugin $object
+	 */
+	public function add_to_storage( $class, $object ) {
+		add_filter( self::STORAGE_FILTER_NAME, function ( $plugins ) use ( $class, $object ) {
+			if ( isset( $plugins[ $class ] ) ) {
+				throw new Exception\ClassAlreadyExists( "Class {$class} already exists" );
+			}
+			$plugins[ $class ] = $object;
+
+			return $plugins;
+		} );
+
+	}
+
+	/**
+	 * @param string $class
+	 *
+	 * @return AbstractPlugin
+	 */
+	public function get_from_storage( $class ) {
+		$plugins = apply_filters( self::STORAGE_FILTER_NAME, [] );
+		if ( isset( $plugins[ $class ] ) ) {
+			return $plugins[ $class ];
+		}
+		throw new Exception\ClassNotExists( "Class {$class} not exists in storage" );
+	}
+}
+