A Beginner's Guide to WordPress Plugin Development: Building Your First Custom Function Extension from Scratch

Why do we need to develop custom plug-ins?

WordPress is renowned for its powerful scalability, and one of its core secrets is the plugin system. When the website's functional requirements exceed the capabilities of the theme or existing plugins, developing your own plugins becomes the best option. Unlike directly modifying the theme, developing plugins allows you to customize the functionality of your website without compromising its stability or security. functions.php Compared with files, creating a standalone plug-in has significant advantages. The plug-in is separate from the theme, which means that even if you switch themes, the plug-in's functionality can still be fully preserved, ensuring the independence and maintainability of the function. In addition, a well-structured plug-in can be easily migrated and reused across different websites, and even distributed through official or third-party channels.

Developing custom plugins allows you to precisely control the functional logic and avoid the performance overhead and potential code conflicts caused by installing too many general plugins. From simple shortcode generation to complex data processing and workflow management, plugin development opens the door to deeply customizing WordPress for you.

Build your first plug-in infrastructure

A WordPress plugin is essentially one or more components that are located within the WordPress framework. wp-content/plugins/ The PHP files under the directory. The first step in creating a plugin is to establish its basic structure.

Recommended Reading A Beginner's Guide to WordPress Plugin Development: Building Your First Functional Plugin from Scratch。

Create the main plug-in file and add header comments

Firstly, in wp-content/plugins/ Create a new folder within the directory, for example… my-first-pluginThen, create the main PHP file within that folder, which is usually named the same as the folder:my-first-plugin.php。

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

The beginning of the file must contain plugin header comments that comply with WordPress standards, which are key for WordPress to recognize the plugin. These comments provide basic information about the plugin and will be displayed on the plugin management page in the backend.

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

After saving the file, log in to the WordPress backend and go to the “Plugins” page. You should be able to see the plugin named “My First Custom Plugin” appear in the list, and you can activate or deactivate it. At present, it doesn't have any actual functionality.

Create a secure wrapper for the plugin's functionality

In order to avoid conflicts between function names and topics or other plugins, the best practice is to wrap all functions in a class or add a unique prefix to all functions. Here, we use the class method, which provides better encapsulation and organizational structure.

In the main file, after the header comments, we can start defining the main class of the plug-in.

Recommended Reading WordPress Plugin Development Complete Guide: Creating Your First Functional Plugin from Scratch。

if ( ! defined( 'ABSPATH' ) ) {
    exit; // 防止直接访问文件
}

class My_First_Plugin {
    /**
     * 构造方法，用于初始化插件
     */
    public function __construct() {
        // 初始化钩子
        $this->init_hooks();
    }

/**
     * 初始化 WordPress 钩子（动作和过滤器）
     */
    private function init_hooks() {
        // 后续的钩子将在这里添加
    }
}

// 初始化插件
new My_First_Plugin();

Via if ( ! defined( 'ABSPATH' ) ) With this line of code, we've ensured that the file can only be accessed through the WordPress environment, enhancing security. Now, the basic framework of the plugin is ready.

Extend the core functionality of WordPress using hooks

The core of WordPress's plugin API is “hooks”, which allow you to execute custom code at specific points in time or on specific data. Hooks are divided into two types: actions and filters.

Understand and add a simple action hook

Action hooks execute your code when specific events occur, such as publishing an article, loading a management page, etc. They do not return any value; they simply “do” certain tasks.

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

Let's add a feature: automatically add a customized text at the end of each article's content. We will use the_content This filter (yes, although it's called a filter, it's often used to add content. Technically, it's a filter because it receives and returns content). But to demonstrate a pure action first, we'll also add an action that displays a message in the backend management panel.

Firstly, in init_hooks Add a hook registration in the method:

private function init_hooks() {
    // 在文章内容末尾添加信息的过滤器
    add_filter( 'the_content', array( $this, 'append_custom_text' ) );
    // 在管理栏添加节点的动作
    add_action( 'admin_bar_menu', array( $this, 'add_admin_bar_node' ), 999 );
}

Then, define the corresponding callback method in the class:

Recommended Reading A Complete Guide to WordPress Plugin Development: From Beginner to Expert in Building Custom Features。

/**
 * 在文章内容末尾添加自定义文本（过滤器回调）
 *
 * @param string $content 原始文章内容。
 * @return string 修改后的文章内容。
 */
public function append_custom_text( $content ) {
    if ( is_single() && in_the_loop() && is_main_query() ) {
        $custom_text = '<p><em>This article is technically supported by “My First Plugin”.</em></p>';
        $content .= $custom_text;
    }
    return $content;
}

/**
 * 在管理工具栏添加一个自定义节点（动作回调）
 *
 * @param WP_Admin_Bar $wp_admin_bar WordPress 管理栏对象。
 */
public function add_admin_bar_node( $wp_admin_bar ) {
    $args = array(
        'id'    =&gt; 'my_plugin_node',
        'title' =&gt; '我的插件',
        'href'  =&gt; admin_url( 'plugins.php' ),
        'meta'  =&gt; array( 'class' =&gt; 'my-plugin-node' )
    );
    $wp_admin_bar-&gt;add_node( $args );
}

Now, after activating the plugin, the added text will appear at the bottom of each article on the front-end, and a “My Plugins” menu item will also appear in the top management bar on the back-end.

Modify the data output using a filter

Filters are used to modify the data passed at a specific point. It receives a value and must return the modified value. We used it above. append_custom_text The method is actually a filter callback. Let's create another more typical filter example: modifying the length of the article abstract.

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

In init_hooks Add the following to:

add_filter( 'excerpt_length', array( $this, 'custom_excerpt_length' ), 999 );

Then define the callback method:

/**
 * 修改文章摘要的默认字数长度
 *
 * @param int $length 默认的摘要长度。
 * @return int 修改后的摘要长度。
 */
public function custom_excerpt_length( $length ) {
    // 将摘要长度设置为 30 个字
    return 30;
}

Implement a configurable plugin options page

In order to make the plugin more flexible, it is usually necessary to provide users with a settings page. WordPress provides a “Settings API” to create option pages in a safe and standardized manner.

Create a management menu and sub-pages

First, we need to add a menu item in the WordPress backend. We will use add_options_page The function adds a sub-page under the “Settings” main menu.

In init_hooks Add actions to the middle:

add_action( 'admin_menu', array( $this, 'add_plugin_admin_menu' ) );

Define the method for adding a menu:

/**
 * 向 WordPress 后台添加插件设置页面
 */
public function add_plugin_admin_menu() {
    add_options_page(
        '我的插件设置',          // 页面标题
        '我的插件',             // 菜单标题
        'manage_options',       // 所需权限
        'my-first-plugin',      // 菜单 Slug
        array( $this, 'display_plugin_admin_page' ) // 回调函数
    );
}

Use the settings API to register and render fields

Next, we need to define display_plugin_admin_page Methods to render the page content and register settings, fields, and chapters.

First, add another hook to register the settings:

add_action( 'admin_init', array( $this, 'register_plugin_settings' ) );

Then, implement the relevant methods:

/**
 * 使用 WordPress 设置 API 注册设置、字段和章节
 */
public function register_plugin_settings() {
    // 注册一个设置，存储到一个选项 `my_first_plugin_options`
    register_setting(
        'my_first_plugin_options_group', // 选项组名
        'my_first_plugin_options'        // 选项名
    );

// 添加一个设置章节
    add_settings_section(
        'my_first_plugin_main_section',  // 章节 ID
        '主要设置',                      // 章节标题
        array( $this, 'render_section_description' ), // 章节描述回调
        'my-first-plugin'                // 页面 Slug
    );

// 向章节中添加一个文本字段
    add_settings_field(
        'custom_text_field',             // 字段 ID
        '自定义文本',                    // 字段标题
        array( $this, 'render_text_field' ), // 字段渲染回调
        'my-first-plugin',               // 页面 Slug
        'my_first_plugin_main_section'   // 所属章节 ID
    );
}

/**
 * 渲染设置章节的描述文字
 */
public function render_section_description() {
    echo '<p>Here, you can configure the settings for your first plugin.</p>';
}

/**
 * 渲染自定义文本输入字段
 */
public function render_text_field() {
    $options = get_option( 'my_first_plugin_options' );
    $value = isset( $options['custom_text_field'] ) ? $options['custom_text_field'] : '';
    echo '<input type="text" name="my_first_plugin_options[custom_text_field]" value="' . esc_attr( $value ) . '" class="regular-text" />'echo '<p class="description">The text entered here will be displayed at the end of the article.</p>'/**
 * Render the main content of the plugin management page
 */
public function display_plugin_admin_page() {
    // Check user permissions
    if ( ! current_user_can( 'manage_options' ) ) {
        return;
    }
    ?&gt;
    <div class="wrap">
        <h1></h1>
        <form action="/en/options.php/" method="post" data-trp-original-action="options.php">
            <?php
            // 输出安全字段、章节和字段
            settings_fields( 'my_first_plugin_options_group' );
            do_settings_sections( 'my-first-plugin' );
            submit_button( '保存设置' );
            ?>
        <input type="hidden" name="trp-form-language" value="en"/></form>
    </div>
    &lt;?php
}

Finally, we need to modify the previous one. append_custom_text The method reads the text saved by the user from the options:

public function append_custom_text( $content ) {
    if ( is_single() && in_the_loop() && is_main_query() ) {
        $options = get_option( 'my_first_plugin_options' );
        $custom_text = isset( $options['custom_text_field'] ) && ! empty( $options['custom_text_field'] ) ?
            '<p><em>'`. esc_html($options['custom_text_field'])`.'</em></p>' :
            '<p><em>This article is technically supported by “My First Plugin”.</em></p>';
        $content .= $custom_text;
    }
    return $content;
}

Now, users can customize the text displayed at the end of the article in the “Settings” -> “My Plugins” page.

summarize

Through this guide, we have comprehensively covered the basic process of developing a WordPress custom plugin: starting from creating the basic file structure and secure code packaging, to in-depth understanding and application of WordPress's core extension mechanisms - action and filter hooks, and finally implementing a configurable plugin that includes a backend settings page. We demonstrated how to use the WordPress settings API in a standardized manner to create an options page, which ensures the safe storage of data and the consistency of the interface.

Mastering these fundamentals is a solid step towards more complex plugin development. Later on, you can explore more advanced topics such as customizing database tables, creating shortcodes, adding widgets, writing REST API endpoints, and implementing AJAX interactions. Remember, good code organization, thorough security checks (such as capability checks, data cleaning, and escaping), and adherence to WordPress coding standards are key to developing high-quality, maintainable plugins.

FAQ Frequently Asked Questions

What prerequisite knowledge is needed for plugin development?

You need to have a basic knowledge of the PHP programming language, including concepts such as syntax, variables, functions, classes, and objects. At the same time, having a basic understanding of HTML, CSS, and JavaScript will also be very helpful, especially when creating plugins involving front-end interactions or complex backend interfaces. It's essential to understand the basic operations and architecture of WordPress.

How to debug the plugin that is being developed

First of all, make sure that in your… wp-config.php The document will WP_DEBUG Set it to trueThis will enable the error reporting feature of WordPress. Use the developer tools in your browser (the Console and Network tabs) to check for JavaScript errors and network requests. For PHP code, you can use error_log() The function logs variables or information into the server's debug log, or uses a dedicated debugging plug-in to trace the code execution process and the state of variables.

Can we move the functions.php code of the theme directly to the plugin?

In many cases, this is possible, but attention must be paid to the issues related to path and URL references. This can be used within the topic. get_template_directory_uri() To obtain the theme directory URI, it should be changed to use it in the plug-in. plugin_dir_url(FILE)Similarly, the theme directory path function get_template_directory() It should also be replaced with a plug-in plugin_dir_path(FILE)In addition, make sure that all the functions in the code are properly packaged in classes or prefixed functions to avoid conflicts.

What should be paid attention to when developing commercial plug-ins?

For the commercial plug-ins distributed by the development plan, more attention needs to be paid to code quality, security, and scalability. It is necessary to conduct thorough internationalization and localization preparations (using ). __()、_e() Translate the following Chinese (Simplified) sentence into English and explain it in detail: The function and text fields need to be translated. The code should comply with WordPress coding standards. It is necessary to consider the license (usually GPL) and the subsequent update mechanism. It is also crucial to provide clear and detailed user documentation and technical support channels for the plugin. In the 2026 ecosystem, ensuring the plugin's compatibility with the new version of WordPress, PHP versions, and popular themes and other plugins is an important part of ongoing maintenance.

How to add multi-language support to a plugin

WordPress uses the GNU gettext technology to achieve internationalization (i18n). Firstly, all the strings that need to be translated in the plug-in should be wrapped in a specific function, such as __('文本', 'my-first-plugin') \nUsed to return the translation,_e('文本', 'my-first-plugin') It is used for outputting translations. Then, use a tool like Poedit to scan the plugin source code and generate .pot Template files. Translators create the corresponding language versions based on this template. .po Translate the following Chinese (simplified) sentence into English and explain it in detail: \n files, and compile them into machine-readable ones. .mo Document. Finally, it is necessary to load_plugin_textdomain() The function is integrated into the plugin initialization code to load the translation file at the correct path.