At this point in the series, we are ready to complete our plugin by documenting our files, classes, functions, variables, etc.
Although this is the last step where we actually have to complete the plugin, this is not the last article in the series as we will continue to look at some advanced topics in object-oriented programming.
But before that, let’s put into practice everything we learned in the previous article and upgrade our plugin to version 1.0.
Of course, as with all previous posts, I recommend that you keep up to date with everything we've covered so far so that you not only fully understand what we did in the previous post, but How do we actually get to the last point discussed in this article.
Record plugin
To do this, we will look at the plugin file by file, introducing documentation for each piece of code we have, and then we will discuss any points of interest behind the code.
Finally, we will make sure to reference the final version of the plugin at the end of the article. With that being said, let’s get started.
Single Post Meta Manager
The following is the fully documented version of this file. Read each review carefully, paying attention not only to the format it follows but also to the content it offers.
<?php /** * The file responsible for starting the Single Post Meta Manager plugin * * The Single Post Meta Manager is a plugin that displays the post meta data * associated with a given post. This particular file is responsible for * including the necessary dependencies and starting the plugin. * * @package SPPM * * @wordpress-plugin * Plugin Name: Single Post Meta Manager * Plugin URI: https://github.com/tommcfarlin/post-meta-manager * Description: Single Post Meta Manager displays the post meta data associated with a given post. * Version: 1.0.0 * Author: Tom McFarlin * Author URI: http://tommcfarlin.com * Text Domain: single-post-meta-manager-locale * License: GPL-2.0+ * License URI: http://www.gnu.org/licenses/gpl-2.0.txt * Domain Path: /languages */ // If this file is called directly, then about execution. if ( ! defined( 'WPINC' ) ) { die; } /** * Include the core class responsible for loading all necessary components of the plugin. */ require_once plugin_dir_path( __FILE__ ) . 'includes/class-single-post-meta-manager.php'; /** * Instantiates the Single Post Meta Manager class and then * calls its run method officially starting up the plugin. */ function run_single_post_meta_manager() { $spmm = new Single_Post_Meta_Manager(); $spmm->run(); } // Call the above function to begin execution of the plugin. run_single_post_meta_manager();
Note that in this example we have included them under the custom
@wordpress-plugin tag. This is not required, but helps separate file header comments from required plugin comments.
1.0, and we have also assigned the
@package value="inline" to the plugin >SPMM
is missing Single Post Meta Manager. We will use this throughout the plugin.
Directory
Since these files are required before anything can be managed in the directory, it makes sense to look at each of these files individually and then round out our discussion with the remaining files in the managed directory.
Single Post Meta Manager
<?php /** * The Single Post Meta Manager is the core plugin responsible for including and * instantiating all of the code that composes the plugin * * @package SPMM */ /** * The Single Post Meta Manager is the core plugin responsible for including and * instantiating all of the code that composes the plugin. * * The Single Post Meta Manager includes an instance to the Single Post Manager * Loader which is responsible for coordinating the hooks that exist within the * plugin. * * It also maintains a reference to the plugin slug which can be used in * internationalization, and a reference to the current version of the plugin * so that we can easily update the version in a single place to provide * cache busting functionality when including scripts and styles. * * @since 1.0.0 */ class Single_Post_Meta_Manager { /** * A reference to the loader class that coordinates the hooks and callbacks * throughout the plugin. * * @access protected * @var Single_Post_Meta_Manager_Loader $loader Manages hooks between the WordPress hooks and the callback functions. */ protected $loader; /** * Represents the slug of hte plugin that can be used throughout the plugin * for internationalization and other purposes. * * @access protected * @var string $plugin_slug The single, hyphenated string used to identify this plugin. */ protected $plugin_slug; /** * Maintains the current version of the plugin so that we can use it throughout * the plugin. * * @access protected * @var string $version The current version of the plugin. */ protected $version; /** * Instantiates the plugin by setting up the core properties and loading * all necessary dependencies and defining the hooks. * * The constructor will define both the plugin slug and the verison * attributes, but will also use internal functions to import all the * plugin dependencies, and will leverage the Single_Post_Meta_Loader for * registering the hooks and the callback functions used throughout the * plugin. */ public function __construct() { $this->plugin_slug = 'single-post-meta-manager-slug'; $this->version = '1.0.0'; $this->load_dependencies(); $this->define_admin_hooks(); } /** * Imports the Single Post Meta administration classes, and the Single Post Meta Loader. * * The Single Post Meta Manager administration class defines all unique functionality for * introducing custom functionality into the WordPress dashboard. * * The Single Post Meta Manager Loader is the class that will coordinate the hooks and callbacks * from WordPress and the plugin. This function instantiates and sets the reference to the * $loader class property. * * @access private */ private function load_dependencies() { require_once plugin_dir_path( dirname( __FILE__ ) ) . 'admin/class-single-post-meta-manager-admin.php'; require_once plugin_dir_path( __FILE__ ) . 'class-single-post-meta-manager-loader.php'; $this->loader = new Single_Post_Meta_Manager_Loader(); } /** * Defines the hooks and callback functions that are used for setting up the plugin stylesheets * and the plugin's meta box. * * This function relies on the Single Post Meta Manager Admin class and the Single Post Meta Manager * Loader class property. * * @access private */ private function define_admin_hooks() { $admin = new Single_Post_Meta_Manager_Admin( $this->get_version() ); $this->loader->add_action( 'admin_enqueue_scripts', $admin, 'enqueue_styles' ); $this->loader->add_action( 'add_meta_boxes', $admin, 'add_meta_box' ); } /** * Sets this class into motion. * * Executes the plugin by calling the run method of the loader class which will * register all of the hooks and callback functions used throughout the plugin * with WordPress. */ public function run() { $this->loader->run(); } /** * Returns the current version of the plugin to the caller. * * @return string $this->version The current version of the plugin. */ public function get_version() { return $this->version; } }
a lot of new comments were introduced in this particular file; however, the role of each class attribute, constructor, and internal function should be very self-explanatory.
In addition to how information is coordinated through plugins, the key thing to note is how we adhere to the standards defined in the previous article.Please note, however, that if certain tags and/or features in the documentation
are not used when they are not relevant, we take the liberty of using them. We will continue to do so in the remainder of this article.
Single Post Meta Manager Loader<?php /** * The Single Post Meta Manager Loader is a class that is responsible for * coordinating all actions and filters used throughout the plugin * * @package SPMM */ /** * The Single Post Meta Manager Loader is a class that is responsible for * coordinating all actions and filters used throughout the plugin. * * This class maintains two internal collections - one for actions, one for * hooks - each of which are coordinated through external classes that * register the various hooks through this class. * * @since 1.0.0 */ class Single_Post_Meta_Manager_Loader { /** * A reference to the collection of actions used throughout the plugin. * * @access protected * @var array $actions The array of actions that are defined throughout the plugin. */ protected $actions; /** * A reference to the collection of filters used throughout the plugin. * * @access protected * @var array $actions The array of filters that are defined throughout the plugin. */ protected $filters; /** * Instantiates the plugin by setting up the data structures that will * be used to maintain the actions and the filters. */ public function __construct() { $this->actions = array(); $this->filters = array(); } /** * Registers the actions with WordPress and the respective objects and * their methods. * * @param string $hook The name of the WordPress hook to which we're registering a callback. * @param object $component The object that contains the method to be called when the hook is fired. * @param string $callback The function that resides on the specified component. */ public function add_action( $hook, $component, $callback ) { $this->actions = $this->add( $this->actions, $hook, $component, $callback ); } /** * Registers the filters with WordPress and the respective objects and * their methods. * * @param string $hook The name of the WordPress hook to which we're registering a callback. * @param object $component The object that contains the method to be called when the hook is fired. * @param string $callback The function that resides on the specified component. */ public function add_filter( $hook, $component, $callback ) { $this->filters = $this->add( $this->filters, $hook, $component, $callback ); } /** * Registers the filters with WordPress and the respective objects and * their methods. * * @access private * * @param array $hooks The collection of existing hooks to add to the collection of hooks. * @param string $hook The name of the WordPress hook to which we're registering a callback. * @param object $component The object that contains the method to be called when the hook is fired. * @param string $callback The function that resides on the specified component. * * @return array The collection of hooks that are registered with WordPress via this class. */ private function add( $hooks, $hook, $component, $callback ) { $hooks[] = array( 'hook' => $hook, 'component' => $component, 'callback' => $callback ); return $hooks; } /** * Registers all of the defined filters and actions with WordPress. */ public function run() { foreach ( $this->filters as $hook ) { add_filter( $hook['hook'], array( $hook['component'], $hook['callback'] ) ); } foreach ( $this->actions as $hook ) { add_action( $hook['hook'], array( $hook['component'], $hook['callback'] ) ); } } }
Finally, when
run is called, all hooks are registered with WordPress, so when the plugin starts, it will call every registered action and filter.
Directory
While the file consists of several PHP files, it also contains a CSS file. For the purposes of this article, we won't be documenting CSS files; we will be writing CSS files. However, the WordPress Codex
doesdefine documentation for this.
Now, let's continue logging the classes and files present in theadmin directory.
<?php /** * The Single Post Meta Manager Admin defines all functionality for the dashboard * of the plugin * * @package SPMM */ /** * The Single Post Meta Manager Admin defines all functionality for the dashboard * of the plugin. * * This class defines the meta box used to display the post meta data and registers * the style sheet responsible for styling the content of the meta box. * * @since 1.0.0 */ class Single_Post_Meta_Manager_Admin { /** * A reference to the version of the plugin that is passed to this class from the caller. * * @access private * @var string $version The current version of the plugin. */ private $version; /** * Initializes this class and stores the current version of this plugin. * * @param string $version The current version of this plugin. */ public function __construct( $version ) { $this->version = $version; } /** * Enqueues the style sheet responsible for styling the contents of this * meta box. */ public function enqueue_styles() { wp_enqueue_style( 'single-post-meta-manager-admin', plugin_dir_url( __FILE__ ) . 'css/single-post-meta-manager-admin.css', array(), $this->version, FALSE ); } /** * Registers the meta box that will be used to display all of the post meta data * associated with the current post. */ public function add_meta_box() { add_meta_box( 'single-post-meta-manager-admin', 'Single Post Meta Manager', array( $this, 'render_meta_box' ), 'post', 'normal', 'core' ); } /** * Requires the file that is used to display the user interface of the post meta box. */ public function render_meta_box() { require_once plugin_dir_path( __FILE__ ) . 'partials/single-post-meta-manager.php'; } }
请注意,上面的类只有很少的功能细节。主要是,该类维护对插件版本的引用、用于设置元框样式的样式表以及实际渲染元框所需的函数。
回想一下,所有这些都是在核心插件文件和加载器中设置的。这有助于解耦插件中存在的逻辑,以便每个类都可以专注于其主要目的。
当然,插件的最后一部分依赖于包含显示元框所需标记的实际部分文件。
<?php /** * Displays the user interface for the Single Post Meta Manager meta box. * * This is a partial template that is included by the Single Post Meta Manager * Admin class that is used to display all of the information that is related * to the post meta data for the given post. * * @package SPMM */ ?> <div id="single-post-meta-manager"> <?php $post_meta = get_post_meta( get_the_ID() ); ?> <table id="single-post-meta-manager-data"> <?php foreach ( $post_meta as $post_meta_key => $post_meta_value ) { ?> <tr> <td class="key"><?php echo $post_meta_key; ?></td> <td class="value"><?php print_r( $post_meta_value[0] ); ?></td> </tr> <?php } ?> </table> </div><!-- #single-post-meta-manager -->
这应该是相对不言自明的;但是,为了完整起见,请注意此文件获取当前帖子 ID(通过使用 get_the_ID()
函数),读取帖子元数据,然后迭代它构建一个表显示键和值。
至此,我们已经完成了插件的实现。从实施面向对象的编程实践,到记录代码。
您可以在 GitHub 上获取该插件的最终版本;但是,我们将在更多帖子中继续进行面向对象的讨论,以便我们可以探索一些更高级的主题,例如继承、抽象和其他主题。
同时,如果您对该插件有疑问或意见,请随时在评论中留下!
The above is the detailed content of WordPress Plugin Continue Documentation: Object-Oriented Programming II. For more information, please follow other related articles on the PHP Chinese website!