The Ultimate Guide to WordPress Plugin Development: Core Tips for Building Custom Features from Scratch

Understanding the basic architecture of WordPress plugins

Before starting to write code, it is crucial to understand the basic structure of WordPress plugins. A plugin is essentially one or more PHP files that are located in a specific directory within WordPress’s file system./wp-content/plugins/Within the directory, core functions can be extended using the API (Application Programming Interface) provided by WordPress. The core of a plugin consists of a main file, which must contain specific header comments so that WordPress can recognize and manage it.

The structure of the main file of the plug-in

The entry point for a plugin is usually a PHP file with the same name as the plugin. The header of this file must contain a standardized comment that provides metadata to WordPress. This comment should include at least the plugin name, description, version, author, and license information. For example, for a plugin named “My Custom Widget,” its main file would contain the following comment:my-custom-widget.phpThe beginning of… might look like this:

<?php
/**
 * Plugin Name: My Custom Widget
 * Plugin URI: https://www.example.com/my-custom-widget
 * Description: 这是一个用于演示的自定义小工具插件。
 * Version: 1.0.0
 * Author: Your Name
 * Author URI: https://www.example.com
 * License: GPL v2 or later
 * Text Domain: my-custom-widget
 */

The “Plugin Name” field in this comment is the only required field for WordPress to identify a plugin. Although the other fields are optional, it is recommended to fill them in completely for the sake of plugin standardization and maintainability. The “Text Domain” field is used for internationalization and is crucial for adding multi-language support to the plugin in the future.

Recommended Reading WordPress Plugin Development Guide: Building Customized Functional Modules from Scratch。

Best Practices for Plugin Directory Structure

For simple plugins, a single PHP file may be sufficient. However, for plugins with complex functionality, a clear and modular directory structure is essential. A typical professional plugin directory may include the following parts:

UltaHost WordPress Hosting

30-day refund guarantee, unlimited bandwidth and database usage, free DDoS protection; purchase for 3 years and get a discount of 50%.

access page

• Main Fileplugin-name.phpThe plugin’s initialization file, which contains file header comments as well as the core logic or the loader.
• includes/ Or src/The “directory” is used to store the core PHP class files and functional modules.
• admin/The “Directory” section is specifically used to store the code and pages related to the backend management interface.
• public/ Or frontend/The “directory” contains the logic for handling the front-end display of the website.
• assets/The directory contains static resources such as JavaScript, CSS, and images.
• languages/The “directory” stores the internationalization translation files (.po/.mo files).
• uninstall.phpAn optional but recommended file, used to clean up data such as database options when users delete plugins.

This structured organization not only makes the code easier to maintain and facilitates teamwork, but it also aligns with the best practices of modern PHP development.

Master the core development tools: action and filter hooks.

The core philosophy of WordPress plugin development is the “Hook” system. The Hook mechanism allows your plugin to “interact” with WordPress’s core processes at specific points in time, enabling you to modify or add new functionality without directly altering the core code. There are mainly two types of Hooks: Action Hooks and Filter Hooks.

The application of action hooks

Action hooks execute your custom code when specific events occur. For example, when an article is published, or when the menu in the administration backend is initialized.add_action()Functions can be “mounted” to an action hook.

Assume you want to automatically add a copyright statement at the end of each article. You can usethe_contentThis filter (note that it is actually a filter, but its functionality is similar to that of an action) is used to log events after a user logs in. Here is an example of how to use an action hook:wp_footerExample of displaying information at the bottom of a website page:

Recommended Reading Mastering WordPress Plugin Development: Building Custom Features from Scratch。

function myplugin_add_footer_text() {
    echo '<p style="text-align:center;">Thank you for using this site!</p>';
}
add_action( 'wp_footer', 'myplugin_add_footer_text' );

When WordPress executes…wp_footerThis action point is usually located within the topic…footer.phpCall in the middlewp_footer()Whenever that function is called, all the functions that are mounted to it will be triggered, including the one we just defined.myplugin_add_footer_text。

The application of filter hooks

Filter hooks are used to modify data. They receive a variable, which, after being processed by your function, must be returned as the modified variable. This is one of the most powerful ways to change the default behavior of WordPress.add_filter()The function is mounted.

For example, to modify the length of an article summary, you can use…excerpt_lengthFilter:

hosting.com Shared Hosting

High performance with AMD EPYC CPUs, NVMe SSD storage and LiteSpeed, 24/7, 24x7 expert in-house support, advanced security measures including SSL, brute force, malware and DDoS protection, savings of up to 73%

access page

function myplugin_custom_excerpt_length( $length ) {
    // 将默认的55个单词改为20个单词
    return 20;
}
add_filter( 'excerpt_length', 'myplugin_custom_excerpt_length' );

Another common use case is to modify the output of article content. The following code adds a prompt box before the content of all articles:

function myplugin_add_content_notice( $content ) {
    if ( is_single() ) {
        $notice = '<div class="notice">This article is original content. Please indicate the source if you repost it.</div>';
        $content = $notice . $content;
    }
    return $content;
}
add_filter( 'the_content', 'myplugin_add_content_notice' );

Understanding and proficiently using various hooks is key to becoming an efficient WordPress developer. The official WordPress plugin manual provides a complete list of all available hooks.

Build a plugin backend management interface

Most plugins require a configuration page that allows website administrators to set various options. WordPress provides a rich API for creating beautiful, standardized administrative management pages.

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

Create a top-level management menu and page.

utilizationadd_menu_page()The function can add a top-level menu item and its corresponding settings page for your plugin in the background sidebar. You need to provide parameters such as the page title, menu title, permissions, menu alias, and callback function.

The following code example creates a top-level menu page named “My Plugin Settings”:

InterServer Shared Hosting

Shared hosting $2.50 USD per month , first month $0.1 USD promo code tryinterserver, 461 cloud apps scripts, one click install.

access page

function myplugin_add_admin_menu() {
    add_menu_page(
        '我的插件设置',          // 页面标题
        '我的插件',             // 菜单标题
        'manage_options',       // 权限（通常为manage_options，仅管理员可见）
        'myplugin-settings',    // 菜单别名（slug），用于URL
        'myplugin_settings_page_html', // 用于渲染页面内容的回调函数
        'dashicons-admin-generic', // 菜单图标（使用Dashicons）
        80                     // 菜单位置
    );
}
add_action( 'admin_menu', 'myplugin_add_admin_menu' );

// 定义渲染页面内容的回调函数
function myplugin_settings_page_html() {
    // 检查用户权限
    if ( ! current_user_can( 'manage_options' ) ) {
        return;
    }
    ?>
    <div class="wrap">
        <h1></h1>
        <form action="/en/options.php/" method="post" data-trp-original-action="options.php">
            <?php
            // 输出设置字段、非ces等（需要与settings API配合使用）
            settings_fields( 'myplugin_options' );
            do_settings_sections( 'myplugin-settings' );
            submit_button( '保存设置' );
            ?>
        <input type="hidden" name="trp-form-language" value="en"/></form>
    </div>
    &lt;?php
}

Handle options securely using the settings API.

Directly using forms to submit and process data poses security risks. WordPress’s Settings API provides a secure and standardized way to register, validate, and save settings options. It automatically handles nonce validation, permission checks, and data cleaning.

Using the Settings API typically involves three steps:
1. Registration Settings: Useregister_setting()Define a set of options along with their validation callbacks.
2. Add a settings section: Use itadd_settings_section()Add a block to the page.
3. Add setting fields: Useadd_settings_field()Add specific input fields within the block.

Here is a simplified example showing how to register a text option field:

function myplugin_settings_init() {
    // 1. 注册一个设置选项组
    register_setting( 'myplugin_options', 'myplugin_options_field', array(
        'sanitize_callback' => 'myplugin_sanitize_text_field' // 清理函数
    ) );

// 2. 添加一个设置区块
    add_settings_section(
        'myplugin_section_main',
        '主要设置',
        null, // 可选的区块描述回调函数
        'myplugin-settings'
    );

// 3. 为区块添加一个字段
    add_settings_field(
        'myplugin_field_text',
        '示例文本',
        'myplugin_field_text_html', // 渲染字段HTML的回调函数
        'myplugin-settings',
        'myplugin_section_main',
        array( 'label_for' => 'myplugin_field_text' )
    );
}
add_action( 'admin_init', 'myplugin_settings_init' );

// 字段渲染函数
function myplugin_field_text_html() {
    $options = get_option( 'myplugin_options_field' );
    $value = isset( $options['text'] ) ? $options['text'] : '';
    ?>
    <input type="text" id="myplugin_field_text" name="myplugin_options_field[text]" value="<?php echo esc_attr( $value ); ?>" class="regular-text">
    <?php
}

// 数据清理函数
function myplugin_sanitize_text_field( $input ) {
    $sanitized_input = array();
    if ( isset( $input['text'] ) ) {
        $sanitized_input['text'] = sanitize_text_field( $input['text'] );
    }
    return $sanitized_input;
}

Implementing the front-end functionality of the plugin and the short code

Plugins are not limited to the backend; more importantly, they provide functionality for the website’s front end. In addition to modifying content through hooks, as mentioned earlier, shortcodes are a powerful tool for providing dynamic functionality to content editors and template files.

Creating and using shortcodes

Short codes allow users to send messages to a specific number by using a simple tag, such as .[my_gallery]Embed complex functionality within articles or pages. Use…add_shortcode()A function is used to register a short code.

The following code creates a simple snippet that displays a button with a custom greeting:

function myplugin_hello_shortcode( $atts, $content = null ) {
    // 解析短代码属性，并提供默认值
    $attributes = shortcode_atts(
        array(
            'name' => '访客',
            'color' => 'blue',
        ),
        $atts,
        'hello' // 短代码标签
    );

// 确保颜色值安全
    $color = esc_attr( $attributes['color'] );
    $name = esc_html( $attributes['name'] );

// 构建输出
    $output = '<button style="background-color: ' . $color . '; padding: 10px; color: white; border: none;">';
    $output .= '你好，' . $name . '！';
    $output .= '</button>';

// 如果短代码是封闭式的（有内容），则包含内容
    if ( ! is_null( $content ) ) {
        $output .= '<div>'`. do_shortcode($content)`.'</div>';
    }

return $output;
}
add_shortcode( 'hello', 'myplugin_hello_shortcode' );

Users can use it in the article editor in the following way:
* [hello name="张三" color="red"]
* [hello]点击我！[/hello]

Add custom widgets to the plugin.

Widgets are content blocks that are displayed in areas such as the WordPress sidebar or footer. To create a custom widget class, you need to extend the existing framework.WP_WidgetThe base class should implement several key methods: the constructor, the method for generating front-end output, and the method for updating the form.

Create a simple tool that displays the titles of the latest articles:

class Myplugin_Recent_Posts_Widget extends WP_Widget {
    // 构造方法：定义小工具ID、名称和描述
    public function __construct() {
        parent::__construct(
            'myplugin_recent_posts',
            '我的插件：近期文章',
            array( 'description' => '显示您网站的最新文章列表。' )
        );
    }

// 前端显示逻辑
    public function widget( $args, $instance ) {
        echo $args['before_widget'];
        if ( ! empty( $instance['title'] ) ) {
            echo $args['before_title'] . apply_filters( 'widget_title', $instance['title'] ) . $args['after_title'];
        }

$posts = get_posts( array( 'numberposts' => $instance['number'] ?: 5 ) );
        echo '<ul>';
        foreach ( $posts as $post ) {
            setup_postdata( $post );
            echo '<li><a href="/en/' . get_permalink( $post->ID ) . '/">' . get_the_title( $post-&gt;ID ) . '</a></li>';
        }
        wp_reset_postdata();
        echo '</ul>';

echo $args['after_widget'];
    }

// 后台小工具表单
    public function form( $instance ) {
        $title = ! empty( $instance['title'] ) ? $instance['title'] : '近期文章';
        $number = ! empty( $instance['number'] ) ? $instance['number'] : 5;
        ?&gt;
        <p>
            <label for="<?php echo esc_attr( $this->get_field_id( 'title' ) ); ?>">Title:</label>
            <input class="widefat" id="<?php echo esc_attr( $this->get_field_id( 'title' ) ); ?>" name="<?php echo esc_attr( $this->get_field_name( 'title' ) ); ?>" type="text" value="<?php echo esc_attr( $title ); ?>">
        </p>
        <p>
            <label for="<?php echo esc_attr( $this->get_field_id( 'number' ) ); ?>">Display the number of articles:</label>
            <input id="<?php echo esc_attr( $this->get_field_id( 'number' ) ); ?>" name="<?php echo esc_attr( $this->get_field_name( 'number' ) ); ?>" type="number" min="1" value="<?php echo esc_attr( $number ); ?>">
        </p>
        &lt;?php
    }

// 更新小工具设置
    public function update( $new_instance, $old_instance ) {
        $instance = array();
        $instance[&#039;title&#039;] = ( ! empty( $new_instance[&#039;title&#039;] ) ) ? sanitize_text_field( $new_instance[&#039;title&#039;] ) : &#039;&#039;;
        $instance[&#039;number&#039;] = ( ! empty( $new_instance[&#039;number&#039;] ) ) ? absint( $new_instance[&#039;number&#039;] ) : 5;
        return $instance;
    }
}

// 注册这个小工具
function myplugin_register_widget() {
    register_widget( &#039;Myplugin_Recent_Posts_Widget&#039; );
}
add_action( &#039;widgets_init&#039;, &#039;myplugin_register_widget&#039; );

summarize

WordPress plugin development is a process that combines PHP programming with a deep understanding of the WordPress core architecture. A successful start involves establishing a file structure and a main file header that adhere to established standards. Next, mastering action hooks and filter hooks is crucial for making full use of WordPress’s powerful extension capabilities; these allow your code to intervene or modify the data flow at precise moments. To provide a user-friendly configuration experience, it is essential to utilize WordPress’s Admin Menu API and Settings API to create a secure and standardized backend management interface. Finally, by implementing shortcodes and custom widgets, you can seamlessly integrate the plugin’s functionality into the website’s front-end content and layout, offering users flexible ways to display content. By following these key techniques, you can systematically create WordPress plugins that are powerful, well-structured, and easy to maintain.

FAQ Frequently Asked Questions

What are the prerequisites for developing a WordPress plugin?

You need to have a solid foundation in PHP programming, as well as a basic understanding of HTML, CSS, and JavaScript. Familiarity with object-oriented programming (OOP) concepts will be very beneficial for developing large-scale plugins. In addition, a local development environment (such as Local by Flywheel, XAMPP, MAMP) and an Integrated Development Environment (IDE) for code editing (such as VS Code, PhpStorm) are essential tools.

How can I ensure that the plugins I develop are both secure and high-performance?

In terms of security: Always validate and clean user input, using built-in WordPress functions such as…sanitize_text_field(), esc_html(), wp_kses()When processing forms and Ajax requests, it is essential to use nonce validation. Make use of the predefined WordPress database operation classes (such as…)$wpdbThis is to prevent SQL injection attacks. In terms of performance: scripts and styles are only loaded when necessary (by using…)wp_enqueue_script()And set dependencies and loading conditions reasonably. Cache time-consuming query results using the Transients API. Avoid performing a large number of unnecessary database queries during the plugin initialization process.

How should I debug and test my plugin?

During the development phase, please…wp-config.phpEnable in the file.WP_DEBUGandWP_DEBUG_LOGThis will log PHP errors and warnings to a log file, making it easier to troubleshoot issues. You can use the browser developer tools to view network requests and JavaScript errors. For debugging the code logic,error_log()Functions and plugins like “Query Monitor” are excellent tools. Be sure to test them on different versions of PHP and WordPress to ensure compatibility.

How can I add internationalization support to my plugin?

First of all, set the correct values in the comments at the top of the main file header.Text Domain(For example: `my-plugin-text-domain`). In the code, replace all strings that need to be translated with…__()"Or"_e()Wrap the function in a function, and pass your text domain as an argument. Then, use tools like Poedit to create the necessary files or resources..potTemplate files, and generate versions in different languages based on them..poand.moTranslate the file and place it inside the plugin./languages/Catalog.

After the development is complete, how do I release my plugin?

You can choose to publish your plugin in the official WordPress plugin directory, which is the most widespread distribution method. This requires your plugin to comply with the GPL license and undergo a rigorous code review process. Alternatively, you can distribute it on your own website or through third-party marketplaces. Regardless of the method you choose, it is essential to provide clear documentation, update logs, compatibility information, and establish a plan for ongoing maintenance and updates.