Advertisement
  1. Code
  2. WordPress

Objektorientierte Programmierung in WordPress: Dokumentieren Sie das Plugin II

Scroll to top
Read Time: 15 min
This post is part of a series called Object-Oriented Programming in WordPress.
Object-Oriented Programming in WordPress: Document the Plugin I
Object-Oriented Programming in WordPress: Inheritance I

German (Deutsch) translation by Alex Grigorovich (you can also view the original English article)

An diesem Punkt der Serie können wir unser Plugin abrunden, indem wir unsere Dateien, Klassen, Funktionen, Variablen und mehr dokumentieren.

Obwohl es der letzte Schritt ist, den wir zum Vervollständigen des Plugins benötigen, ist das nicht der letzte Beitrag in der Reihe, da wir uns weiterhin mit einigen fortgeschrittenen Themen der objektorientierten Programmierung befassen werden.

Aber bevor wir das tun, bringen wir unser Plugin auf Version 1.0, indem wir alles, was wir im vorherigen Artikel gelernt haben, in die Praxis umsetzen.

Natürlich empfehle ich, wie bei allen vorherigen Artikeln, alles nachzuholen, was wir bisher behandelt haben, damit Sie nicht nur mit der Arbeit, die wir im letzten Artikel geleistet haben, sondern auch mit unserer tatsächlichen Arbeit auf dem neuesten Stand sind kamen zu den letzten Punkten, die wir in diesem Artikel diskutieren.

  1. Eine Einleitung
  2. Klassen
  3. Typen
  4. Kontrollstrukturen: Bedingte Anweisungen
  5. Kontrollstrukturen: Schleifen
  6. Funktionen und Attribute
  7. Umfang
  8. Plugin I erstellen
  9. Plugin II erstellen
  10. Dokumentieren Sie das Plugin I

Nachdem alle diese Themen behandelt und überprüft wurden, beginnen wir mit der Dokumentation jeder unserer Dateien.

Dokumentation des Plugins

Es gibt verschiedene Möglichkeiten, dieses Plugin zu dokumentieren:

  • Wir könnten zuerst alle Dateikopfzeilen dokumentieren, dann könnten wir zurückkommen und die Klassen dokumentieren, dann könnten wir zurückkommen und die Variablen dokumentieren, dann könnten wir die Funktionen dokumentieren.
  • Wir könnten jede Datei einzeln dokumentieren und eine kurze Diskussion über alles führen, was pro Datei enthalten ist.

Offensichtlich bietet die Option mehr Dokumentation pro Abschnitt, muss jedoch zu einem viel weniger langwierigen Artikel und einem viel einfacheren Verständnis des Kontrollflusses für das gesamte Plugin führen.

Zu diesem Zweck werden wir das Plugin Datei für Datei durcharbeiten und die Dokumentation für jeden vorhandenen Code einführen. Anschließend werden wir alle Punkte von Interesse besprechen, die dem Code folgen.

Schließlich werden wir sicherstellen, dass wir uns auf die endgültige Version des Plugins am Ende des Artikels beziehen. Nachdem das gesagt ist, fangen wir an.

Der Single Post Meta Manager

Denken Sie daran, dass die Hauptdatei zum Starten des Plugins die Datei single-post-meta-manager.php ist, die sich im Stammverzeichnis des Verzeichnisses des Plugins befindet.

So sieht die vollständig dokumentierte Version der Datei aus. Lesen Sie jeden Kommentar genau durch und achten Sie dabei nicht nur auf das folgende Format, sondern auch auf den darin enthaltenen Inhalt.

1
<?php
2
/**

3
 * The file responsible for starting the Single Post Meta Manager plugin

4
 *

5
 * The Single Post Meta Manager is a plugin that displays the post meta data

6
 * associated with a given post. This particular file is responsible for

7
 * including the necessary dependencies and starting the plugin.

8
 *

9
 * @package SPPM

10
 *

11
 * @wordpress-plugin

12
 * Plugin Name:       Single Post Meta Manager

13
 * Plugin URI:        https://github.com/tommcfarlin/post-meta-manager

14
 * Description:       Single Post Meta Manager displays the post meta data associated with a given post.

15
 * Version:           1.0.0

16
 * Author:            Tom McFarlin

17
 * Author URI:        http://tommcfarlin.com

18
 * Text Domain:       single-post-meta-manager-locale

19
 * License:           GPL-2.0+

20
 * License URI:       http://www.gnu.org/licenses/gpl-2.0.txt

21
 * Domain Path:       /languages

22
 */
23
24
// If this file is called directly, then about execution.

25
if ( ! defined( 'WPINC' ) ) {
26
    die;
27
}
28
29
/**

30
 * Include the core class responsible for loading all necessary components of the plugin.

31
 */
32
require_once plugin_dir_path( __FILE__ ) . 'includes/class-single-post-meta-manager.php';
33
34
/**

35
 * Instantiates the Single Post Meta Manager class and then

36
 * calls its run method officially starting up the plugin.

37
 */
38
function run_single_post_meta_manager() {
39
40
	$spmm = new Single_Post_Meta_Manager();
41
	$spmm->run();
42
43
}
44
45
// Call the above function to begin execution of the plugin.

46
run_single_post_meta_manager();

Beachten Sie im obigen Code, dass wir einen Dateikopf gemäß den Konventionen definiert haben, die wir im vorherigen Artikel beschrieben haben. Wir haben auch die erforderlichen Plugin-Header-Tags beibehalten, damit WordPress sie richtig lesen kann.

Beachten Sie, dass wir sie in diesem Fall unter einem benutzerdefinierten @wordpress-plugin-Tag eingefügt haben. Das ist nicht erforderlich, hilft jedoch dabei, die Dateikopfkommentare von den erforderlichen Plugin-Kommentaren zu trennen.

Beachten Sie schließlich, dass wir die Version dieses Plugins auf 1.0 erhöht haben und diesem Plugin auch den @package-Wert von SPMM gegeben haben, der kurz vor Single Post Meta Manager steht. Wir werden ihn im gesamten Plugin verwenden.

Das includes Verzeichnis

Als nächstes wenden wir uns allen Dateien zu, die sich im Includes-Verzeichnis befinden.

Da diese Dateien vor allem im Administratorverzeichnis erforderlich sind, ist es sinnvoll, jede dieser Dateien einzeln zu betrachten und dann unsere Diskussion mit den verbleibenden Dateien im Administratorverzeichnis abzurunden.

Der Single Post Meta Manager

1
<?php
2
3
/**

4
 * The Single Post Meta Manager is the core plugin responsible for including and

5
 * instantiating all of the code that composes the plugin

6
 *

7
 * @package SPMM

8
 */
9
10
/**

11
 * The Single Post Meta Manager is the core plugin responsible for including and

12
 * instantiating all of the code that composes the plugin.

13
 *

14
 * The Single Post Meta Manager includes an instance to the Single Post Manager

15
 * Loader which is responsible for coordinating the hooks that exist within the

16
 * plugin.

17
 *

18
 * It also maintains a reference to the plugin slug which can be used in

19
 * internationalization, and a reference to the current version of the plugin

20
 * so that we can easily update the version in a single place to provide

21
 * cache busting functionality when including scripts and styles.

22
 *

23
 * @since    1.0.0

24
 */
25
class Single_Post_Meta_Manager {
26
27
    /**

28
	 * A reference to the loader class that coordinates the hooks and callbacks

29
	 * throughout the plugin.

30
	 *

31
	 * @access protected

32
	 * @var    Single_Post_Meta_Manager_Loader   $loader    Manages hooks between the WordPress hooks and the callback functions.

33
	 */
34
	protected $loader;
35
36
	/**

37
	 * Represents the slug of hte plugin that can be used throughout the plugin

38
	 * for internationalization and other purposes.

39
	 *

40
	 * @access protected

41
	 * @var    string   $plugin_slug    The single, hyphenated string used to identify this plugin.

42
	 */
43
	protected $plugin_slug;
44
45
	/**

46
	 * Maintains the current version of the plugin so that we can use it throughout

47
	 * the plugin.

48
	 *

49
	 * @access protected

50
	 * @var    string   $version    The current version of the plugin.

51
	 */
52
	protected $version;
53
54
	/**

55
	 * Instantiates the plugin by setting up the core properties and loading

56
	 * all necessary dependencies and defining the hooks.

57
	 *

58
	 * The constructor will define both the plugin slug and the verison

59
	 * attributes, but will also use internal functions to import all the

60
	 * plugin dependencies, and will leverage the Single_Post_Meta_Loader for

61
	 * registering the hooks and the callback functions used throughout the

62
	 * plugin.

63
	 */
64
	public function __construct() {
65
66
		$this->plugin_slug = 'single-post-meta-manager-slug';
67
		$this->version = '1.0.0';
68
69
		$this->load_dependencies();
70
		$this->define_admin_hooks();
71
72
	}
73
74
75
76
	/**

77
	 * Imports the Single Post Meta administration classes, and the Single Post Meta Loader.

78
	 *

79
	 * The Single Post Meta Manager administration class defines all unique functionality for

80
	 * introducing custom functionality into the WordPress dashboard.

81
	 *

82
	 * The Single Post Meta Manager Loader is the class that will coordinate the hooks and callbacks

83
	 * from WordPress and the plugin. This function instantiates and sets the reference to the

84
	 * $loader class property.

85
	 *

86
	 * @access    private

87
	 */
88
	private function load_dependencies() {
89
90
		require_once plugin_dir_path( dirname( __FILE__ ) ) . 'admin/class-single-post-meta-manager-admin.php';
91
92
		require_once plugin_dir_path( __FILE__ ) . 'class-single-post-meta-manager-loader.php';
93
		$this->loader = new Single_Post_Meta_Manager_Loader();
94
95
	}
96
97
	/**

98
	 * Defines the hooks and callback functions that are used for setting up the plugin stylesheets

99
	 * and the plugin's meta box.

100
	 *

101
	 * This function relies on the Single Post Meta Manager Admin class and the Single Post Meta Manager

102
	 * Loader class property.

103
	 *

104
	 * @access    private

105
	 */
106
	private function define_admin_hooks() {
107
108
		$admin = new Single_Post_Meta_Manager_Admin( $this->get_version() );
109
		$this->loader->add_action( 'admin_enqueue_scripts', $admin, 'enqueue_styles' );
110
		$this->loader->add_action( 'add_meta_boxes', $admin, 'add_meta_box' );
111
112
	}
113
114
	/**

115
	 * Sets this class into motion.

116
	 *

117
	 * Executes the plugin by calling the run method of the loader class which will

118
	 * register all of the hooks and callback functions used throughout the plugin

119
	 * with WordPress.

120
	 */
121
	public function run() {
122
		$this->loader->run();
123
	}
124
125
	/**

126
	 * Returns the current version of the plugin to the caller.

127
	 *

128
	 * @return    string    $this->version    The current version of the plugin.

129
	 */
130
	public function get_version() {
131
		return $this->version;
132
	}
133
134
}

Es ist klar, dass viele neue Kommentare in diese bestimmte Datei aufgenommen wurden. Es muss jedoch sehr selbsterklärend sein, was jede Klasseneigenschaft, der Konstruktor und die internen Funktionen tun.

Abgesehen davon, wie die Informationen im gesamten Plugin koordiniert werden, ist es wichtig zu beachten, wie wir die im vorherigen Artikel definierten Standards eingehalten haben.

Beachten Sie jedoch, dass wir uns die Freiheit genommen haben, bestimmte Tags und/oder Funktionen der Dokumentation nicht zu verwenden, wenn sie nicht relevant sind. Dies werden wir im weiteren Verlauf des Artikels fortsetzen.

Der Single Post Meta Manager Loader

1
<?php
2
3
/**

4
 * The Single Post Meta Manager Loader is a class that is responsible for

5
 * coordinating all actions and filters used throughout the plugin

6
 *

7
 * @package    SPMM

8
 */
9
10
/**

11
 * The Single Post Meta Manager Loader is a class that is responsible for

12
 * coordinating all actions and filters used throughout the plugin.

13
 *

14
 * This class maintains two internal collections - one for actions, one for

15
 * hooks - each of which are coordinated through external classes that

16
 * register the various hooks through this class.

17
 *

18
 * @since    1.0.0

19
 */
20
class Single_Post_Meta_Manager_Loader {
21
22
    /**

23
	 * A reference to the collection of actions used throughout the plugin.

24
	 *

25
	 * @access protected

26
	 * @var    array    $actions    The array of actions that are defined throughout the plugin.

27
	 */
28
	protected $actions;
29
30
	/**

31
	 * A reference to the collection of filters used throughout the plugin.

32
	 *

33
	 * @access protected

34
	 * @var    array    $actions    The array of filters that are defined throughout the plugin.

35
	 */
36
	protected $filters;
37
38
	/**

39
	 * Instantiates the plugin by setting up the data structures that will

40
	 * be used to maintain the actions and the filters.

41
	 */
42
	public function __construct() {
43
44
		$this->actions = array();
45
		$this->filters = array();
46
47
	}
48
49
	/**

50
	 * Registers the actions with WordPress and the respective objects and

51
	 * their methods.

52
	 *

53
	 * @param  string    $hook        The name of the WordPress hook to which we're registering a callback.

54
	 * @param  object    $component   The object that contains the method to be called when the hook is fired.

55
	 * @param  string    $callback    The function that resides on the specified component.

56
	 */
57
	public function add_action( $hook, $component, $callback ) {
58
		$this->actions = $this->add( $this->actions, $hook, $component, $callback );
59
	}
60
61
	/**

62
	 * Registers the filters with WordPress and the respective objects and

63
	 * their methods.

64
	 *

65
	 * @param  string    $hook        The name of the WordPress hook to which we're registering a callback.

66
	 * @param  object    $component   The object that contains the method to be called when the hook is fired.

67
	 * @param  string    $callback    The function that resides on the specified component.

68
	 */
69
	public function add_filter( $hook, $component, $callback ) {
70
		$this->filters = $this->add( $this->filters, $hook, $component, $callback );
71
	}
72
73
	/**

74
	 * Registers the filters with WordPress and the respective objects and

75
	 * their methods.

76
	 *

77
	 * @access private

78
	 *

79
	 * @param  array     $hooks       The collection of existing hooks to add to the collection of hooks.

80
	 * @param  string    $hook        The name of the WordPress hook to which we're registering a callback.

81
	 * @param  object    $component   The object that contains the method to be called when the hook is fired.

82
	 * @param  string    $callback    The function that resides on the specified component.

83
	 *

84
	 * @return array                  The collection of hooks that are registered with WordPress via this class.

85
	 */
86
	private function add( $hooks, $hook, $component, $callback ) {
87
88
		$hooks[] = array(
89
			'hook'      => $hook,
90
			'component' => $component,
91
			'callback'  => $callback
92
		);
93
94
		return $hooks;
95
96
	}
97
98
	/**

99
	 * Registers all of the defined filters and actions with WordPress.

100
	 */
101
	public function run() {
102
103
		 foreach ( $this->filters as $hook ) {
104
			 add_filter( $hook['hook'], array( $hook['component'], $hook['callback'] ) );
105
		 }
106
107
		 foreach ( $this->actions as $hook ) {
108
			 add_action( $hook['hook'], array( $hook['component'], $hook['callback'] ) );
109
		 }
110
111
	}
112
113
}

Beachten Sie, dass diese Klasse mehr oder weniger eine Kernkomponente des Plugins ist, da sie alle Aktionen und Filter koordiniert, die im gesamten Plugin verwendet werden. Dieses Plugin zentralisiert die gesamte Registrierung und Koordination der Hooks, die im gesamten Plugin verwendet werden.

Wenn run aufgerufen wird, werden alle Hooks bei WordPress registriert. Wenn das Plugin ausgelöst wird, werden alle registrierten Aktionen und Filter aufgerufen.

Das admin Verzeichnis

An diesem Punkt sind wir bereit, unsere Aufmerksamkeit auf die Dateien zu richten, die sich im Administratorverzeichnis des Plugins befinden.

Obwohl die Datei aus einigen PHP-Dateien besteht, besteht sie auch aus einer CSS-Datei. Für den Zweck dieses Artikels werden wir die CSS-Dateien nicht dokumentieren. Der WordPress-Codex definiert jedoch die Dokumentation dafür.

Lassen Sie uns jedoch zunächst die im admin Verzeichnis vorhandenen Klassen und Dateien dokumentieren.

Single Post Meta Manager Admin

Die Admin-Klasse "Single Post Meta Manager" hat eine einzige Verantwortung: Definieren Sie die Funktionalität zum Rendern der Meta-Box und ihre Stile für das Dashboard.

1
<?php
2
3
/**

4
 * The Single Post Meta Manager Admin defines all functionality for the dashboard

5
 * of the plugin

6
 *

7
 * @package SPMM

8
 */
9
10
/**

11
 * The Single Post Meta Manager Admin defines all functionality for the dashboard

12
 * of the plugin.

13
 *

14
 * This class defines the meta box used to display the post meta data and registers

15
 * the style sheet responsible for styling the content of the meta box.

16
 *

17
 * @since    1.0.0

18
 */
19
class Single_Post_Meta_Manager_Admin {
20
21
    /**

22
	 * A reference to the version of the plugin that is passed to this class from the caller.

23
	 *

24
	 * @access private

25
	 * @var    string    $version    The current version of the plugin.

26
	 */
27
	private $version;
28
29
	/**

30
	 * Initializes this class and stores the current version of this plugin.

31
	 *

32
	 * @param    string    $version    The current version of this plugin.

33
	 */
34
	public function __construct( $version ) {
35
		$this->version = $version;
36
	}
37
38
	/**

39
	 * Enqueues the style sheet responsible for styling the contents of this

40
	 * meta box.

41
	 */
42
	public function enqueue_styles() {
43
44
		wp_enqueue_style(
45
			'single-post-meta-manager-admin',
46
			plugin_dir_url( __FILE__ ) . 'css/single-post-meta-manager-admin.css',
47
			array(),
48
			$this->version,
49
			FALSE
50
		);
51
52
	}
53
54
	/**

55
	 * Registers the meta box that will be used to display all of the post meta data

56
	 * associated with the current post.

57
	 */
58
	public function add_meta_box() {
59
60
		add_meta_box(
61
			'single-post-meta-manager-admin',
62
			'Single Post Meta Manager',
63
			array( $this, 'render_meta_box' ),
64
			'post',
65
			'normal',
66
			'core'
67
		);
68
69
	}
70
71
	/**

72
	 * Requires the file that is used to display the user interface of the post meta box.

73
	 */
74
	public function render_meta_box() {
75
		require_once plugin_dir_path( __FILE__ ) . 'partials/single-post-meta-manager.php';
76
	}
77
78
}

Beachten Sie, dass die obige Klasse nur sehr wenige funktionale Details enthält. In erster Linie enthält die Klasse einen Verweis auf die Version des Plugins, das zum Stylen der Meta-Box verwendete Stylesheet und die Funktion, die zum tatsächlichen Rendern der Meta-Box erforderlich ist.

Denken Sie daran, dass all dies in der Core-Plugin-Datei und im Loader eingerichtet ist. Dies hilft dabei, die im Plugin vorhandene Logik zu entkoppeln, sodass sich jede Klasse auf ihren Hauptzweck konzentrieren kann.

Natürlich basiert das letzte Stück des Plugins auf der eigentlichen Teildatei, die das Markup enthält, das zum Anzeigen der Meta-Box erforderlich ist.

Single Post Meta Manager Teilweise

1
<?php
2
/**

3
 * Displays the user interface for the Single Post Meta Manager meta box.

4
 *

5
 * This is a partial template that is included by the Single Post Meta Manager

6
 * Admin class that is used to display all of the information that is related

7
 * to the post meta data for the given post.

8
 *

9
 * @package    SPMM

10
 */
11
?>
12
<div id="single-post-meta-manager">
13
14
    <?php $post_meta = get_post_meta( get_the_ID() ); ?>
15
	<table id="single-post-meta-manager-data">
16
	<?php foreach ( $post_meta as $post_meta_key => $post_meta_value ) { ?>
17
		<tr>
18
			<td class="key"><?php echo $post_meta_key; ?></td>
19
			<td class="value"><?php print_r( $post_meta_value[0] ); ?></td>
20
		</tr>
21
	<?php } ?>
22
	</table>
23
24
</div><!-- #single-post-meta-manager -->

Das muss relativ selbsterklärend sein; Beachten Sie jedoch, dass diese Datei die aktuelle Post-ID (mithilfe der Funktion get_the_ID()) verwendet, die Post-Metadaten liest und dann eine Tabelle durchläuft, in der die Schlüssel und Werte angezeigt werden.

Das Plugin fertigstellen

Zu diesem Zeitpunkt haben wir die Implementierung unseres Plugins abgeschlossen. Von der Einführung der objektorientierten Programmierpraktiken bis zur Dokumentation des Codes.

Sie können die endgültige Version des Plugins auf GitHub herunterladen. Wir werden jedoch unsere objektorientierte Diskussion über einige weitere Beiträge fortsetzen, damit wir einige fortgeschrittenere Themen wie Vererbung, Abstraktion und andere Themen untersuchen können.

Wenn Sie in der Zwischenzeit Fragen oder Kommentare zum Plugin haben, zögern Sie nicht, diese in den Kommentaren zu hinterlassen!

Advertisement
Did you find this post useful?
Want a weekly email summary?
Subscribe below and we’ll send you a weekly email summary of all new Code tutorials. Never miss out on learning about the next big thing.
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.