Master WordPress plugin development comprehensively: build custom features from scratch

Why did you choose to develop a WordPress plugin?

WordPress, as the world's most popular content management system, owes its strong scalability primarily to its plugin mechanism. By developing custom plugins, developers can overcome the limitations of existing themes and add any desired functionality to a website without having to modify the core files. This ensures the independence and maintainability of the additional features, while also making it easy to transfer and reuse these plugins across different websites.

A well-designed plugin should be compatible with core WordPress updates and adhere to its coding standards and best practices. This not only enhances the security of the website but also lays a solid foundation for future feature improvements. Whether it’s to meet specific business requirements, address issues that existing plugins cannot handle effectively, or to release the plugin as a commercial product, mastering plugin development skills is an essential step for WordPress developers looking to advance their skills.

Building your first plugin: The basic structure

To create a WordPress plugin, you first need to understand its basic structure. Every plugin requires at least one main file, which is usually named after the plugin itself. For example… my-first-plugin.phpThe plugin header comments at the top of this file are essential; they provide the WordPress system with basic information about the plugin.

Recommended Reading Learn WordPress plugin development: Build your first custom feature module from scratch。

Create the main file of the plug-in

The main file of a plugin serves as the entry point for the plugin. You need to add a standard plugin information comment block at the beginning of this file. Here is a basic example code:

<?php
/**
 * Plugin Name:       我的第一个插件
 * Plugin URI:        https://example.com/my-first-plugin
 * Description:       这是一个用于学习WordPress插件开发的示例插件。
 * Version:           1.0.0
 * Author:            你的名字
 * License:           GPL v2 or later
 * Text Domain:       my-first-plugin
 */

Save the code in a PHP file and then place it in the appropriate directory. /wp-content/plugins/ A new folder within the directory (for example) my-first-pluginAfter that, you will be able to see and activate it on the “Plugins” page in the WordPress administration panel. Although this plugin has not yet added any functionality, it is now a legitimate plugin that is recognized by WordPress.

Understanding the plugin directory structure

As the functionality of plugins increases, a reasonable directory structure becomes crucial for organizing the code. A typical plugin directory may include the following parts:
- The main plug-in file (such as my-first-plugin.phpLocated in the plugin’s root directory, it contains information about the plugin’s header.
- includes/ Contents: Holds the files for the core functionality classes or function modules.
- admin/ Contents: Contains the code related to the backend administration interface.
- public/ Contents: Holds the code related to the front-end logic.
- assets/ Contents: Stores resource files such as CSS style sheets, JavaScript scripts, and images.
- languages/ Contents: Stores internationalization translation files (.po/.mo).

This modular structure makes the code clearer and facilitates teamwork and maintenance.

Core Development Concepts: Hooks and Filters

The core philosophy of WordPress plugin development is the use of “hooks.” Hooks enable you to insert custom code at specific points in the software’s execution flow, allowing you to modify or extend the default behavior of WordPress. There are mainly two types of hooks: Action Hooks and Filter Hooks.

Recommended Reading From Beginner to Expert in WordPress Plugin Development: A Step-by-Step Guide to Creating Custom Features。

Use action hooks to execute custom code.

Action hooks allow you to perform certain tasks at specific points in the WordPress execution process, such as sending notifications after an article is published or adding code to the page header. add_action() Functions can be used to mount your custom functions onto an action hook.

For example, let's create a function that displays custom information at the bottom of the website's front-page footer. First, you need to define a callback function, and then… add_action() Bind it to wp_footer This hook.

\n// Define a callback function
function myplugin_add_footer_text() {
    echo '<p style="text-align:center;">Thank you for using this plugin!</p>';
}
// 将函数挂载到 `wp_footer` 动作钩子
add_action( 'wp_footer', 'myplugin_add_footer_text' );

When WordPress processes the footer section, it will automatically execute the relevant code. myplugin_add_footer_text() The function outputs the text we have defined.

Using filter hooks to modify data

Filter hooks allow you to “modify” data before it is used or saved. For example, you can change the title of an article or filter the content of comments. add_filter() Functions can be used to mount your custom functions onto a filter hook.

Suppose we want to automatically add a trademark symbol at the end of all article titles. We can bind this function to... the_title Filters.

// 定义一个回调函数，它接收原始标题作为参数
function myplugin_add_trademark_to_title( $title ) {
    // 仅在前端文章列表和单篇文章页面修改，避免影响后台
    if ( ! is_admin() ) {
        $title .= ' ™';
    }
    // 必须返回修改后的值
    return $title;
}
// 将函数挂载到 `the_title` 过滤器钩子
add_filter( 'the_title', 'myplugin_add_trademark_to_title' );

In this example,$title The parameter is the original title text, and the function must return a new value after making modifications to it. This is the key difference between filters and actions: filters must return a value.

Recommended Reading WordPress Plugin Development Beginner's Guide: Creating Your First Functional Module from Scratch。

Add a management page and settings options for the plugin.

A fully functional plugin usually needs to provide a configuration interface in the WordPress backend. This can be achieved by adding a top-level management menu or a sub-menu for settings. WordPress offers a rich API for creating these pages.

Create a menu item for plugin settings.

utilization add_menu_page() Or add_submenu_page() Functions can add a background menu to your plugin. Typically, simple plugins add their settings page as a sub-menu under the “Settings” main menu.

The following code demonstrates how to add a sub-menu page and define the callback function that controls its display.

// 在后台“设置”菜单下添加子菜单
function myplugin_add_settings_page() {
    add_options_page(
        '我的插件设置', // 页面标题
        '我的插件',     // 菜单标题
        'manage_options', // 权限要求（只有管理员可访问）
        'myplugin-settings', // 菜单slug
        'myplugin_render_settings_page' // 用于显示页面内容的回调函数
    );
}
// 使用 `admin_menu` 动作钩子在后台菜单初始化时执行上述函数
add_action( 'admin_menu', 'myplugin_add_settings_page' );

// 定义渲染设置页面的回调函数
function myplugin_render_settings_page() {
    ?>
    <div class="wrap">
        <h1>My plugin settings</h1>
        <form action="/en/options.php/" method="post" data-trp-original-action="options.php">
            <?php
            // 输出设置字段、非ce等安全信息
            settings_fields( 'myplugin_settings_group' );
            do_settings_sections( 'myplugin-settings' );
            submit_button();
            ?>
        <input type="hidden" name="trp-form-language" value="en"/></form>
    </div>
    &lt;?php
}

Use the Settings API to register options.

Manually handling form submissions and validations is cumbersome and insecure. The WordPress Settings API provides us with a standard, secure way to create, validate, and save settings options.

You need to use register_setting(), add_settings_section() and add_settings_field() Use functions such as these to define your settings.

// 在插件初始化时注册设置
function myplugin_register_settings() {
    // 1. 注册一个设置组及其数据
    register_setting(
        'myplugin_settings_group', // 设置组名称，需与 settings_fields() 参数一致
        'myplugin_option_name' // 存储在数据库中的选项名
    );

// 2. 添加一个设置区域（Section）
    add_settings_section(
        'myplugin_section_main', // Section ID
        '主要设置', // 标题
        null, // 可选的描述回调函数
        'myplugin-settings' // 所属的页面slug
    );

// 3. 向该区域添加一个设置字段
    add_settings_field(
        'myplugin_field_text', // 字段ID
        '示例文本输入', // 字段标签
        'myplugin_render_text_field', // 渲染字段HTML的回调函数
        'myplugin-settings', // 页面slug
        'myplugin_section_main' // Section ID
    );
}
add_action( 'admin_init', 'myplugin_register_settings' );

// 渲染文本输入字段的回调函数
function myplugin_render_text_field() {
    $option = get_option( 'myplugin_option_name' );
    $value = isset( $option['text'] ) ? $option['text'] : '';
    echo '<input type="text" name="myplugin_option_name[text]" value="' . esc_attr( $value ) . '" />';
}

By setting up the API, the submission and validation of the form can be managed (you can customize the process as needed). register_setting The definition of validation functions, as well as the process of saving data, are all automatically handled by the WordPress core. This greatly enhances both security and development efficiency.

summarize

WordPress plugin development is a process of transforming creative ideas into functional solutions, and the key to success lies in understanding and mastering the hook system. Start by creating a simple plugin file, then gradually learn how to use action hooks to add new functionality and filter hooks to modify data. Eventually, build professional plugins that are configurable and user-friendly by creating administration pages and utilizing the settings API. Following WordPress coding standards, keeping your code modular, and prioritizing security are essential for developing high-quality plugins. By practicing these steps, you will be able to create powerful and stable custom features for any WordPress website.

FAQ Frequently Asked Questions

What are the basic knowledge requirements for developing WordPress plugins?

You need to have a basic understanding of the PHP programming language, as the plugin is primarily written in PHP. It is also essential to have a basic knowledge of HTML, CSS, and JavaScript, as these are crucial for creating user interfaces and handling front-end interactions. Understanding the basic concepts of MySQL databases (although WordPress provides convenient database manipulation classes) as well as the basic architecture of WordPress itself (such as the template hierarchy and loops) will be very helpful.

How to debug my WordPress plugin?

First, make sure that... wp-config.php The file is open in the program WP_DEBUG and WP_DEBUG_LOGThis will log PHP errors and warnings to… /wp-content/debug.log The content should be stored in a file rather than being displayed directly on the page, to avoid affecting the user experience. Secondly, the following methods can be used: error_log() The function outputs custom debugging information to the log. For complex logic, using the breakpoint debugging features of an IDE (such as Xdebug) is the most efficient approach.

How can my plugin be compatible with different versions of WordPress?

During development, it is advisable to avoid using deprecated functions and to refer to the official documentation to determine the specific WordPress version for which a function was introduced. You can do this by checking the main file of your plugin. @requires at least Or @requires PHP Declare the minimum requirements in the plugin header comments. In the code, you can then use these requirements accordingly. function_exists() Or class_exists() To check whether a certain function or class is available, provide a backward-compatible alternative solution.

How to submit my plugin to the official plugin directory?

First of all, you need to make sure that your plugin fully complies with the official plugin development guidelines and coding standards. Next, apply for an SVN repository on WordPress.org. Submit your plugin code (including the well-formatted README.txt file and the main plugin file) to this SVN repository. /trunk After submitting your plugin, the official team will review it. Once the review is approved, your plugin will be added to the official directory, where it will be available for users around the world to download and install.