WordPress Plugin Development Beginner's Guide: Creating Your First Custom Plugin from Scratch

Why develop your own WordPress plugin?

In the WordPress ecosystem, plugins are the core of extending website functionality. Although there are thousands of plugins available on the market, developing your own plugins offers unique advantages. Firstly, it allows you to create custom features that perfectly meet your specific needs, avoiding the cumbersome code or unnecessary features associated with generic plugins. Secondly, self-developed plugins can be deeply integrated with your theme or other custom code, ensuring better compatibility and performance. Furthermore, by developing plugins, you can separate your business logic from the theme code – this is a best practice in WordPress development. As a result, even if you change your theme in the future, the core functionality of your website will still work properly, improving its maintainability.

For developers, learning how to develop plugins is an excellent way to gain a deeper understanding of the WordPress architecture. You will come across action hooks.add_actionFilter hooksadd_filterShortcodesadd_shortcodeCore concepts such as these. Mastering this knowledge will not only enable you to create plugins, but also help you customize existing themes and plugins more efficiently.

Environment Configuration and Preparation Before Development

Before starting to write the first line of code, it is crucial to set up a suitable development environment. This not only improves efficiency but also helps to avoid errors.

Recommended Reading Introduction to WordPress Plugin Development: From Beginner to Expert: Sharing Practical Experience and Core Techniques。

Build a local development environment

It is recommended to use local server software such as Local by Flywheel, XAMPP, or MAMP. These tools can quickly set up a WordPress environment on your computer that includes Apache, MySQL, and PHP. Compared to online servers, local development allows you to test and debug your projects more swiftly, without the risk of affecting your live website.

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

After installing WordPress locally, you need towp-content/pluginsCreate a dedicated folder for your new plugin in the directory. It is recommended to use a short, lowercase English name without spaces, for example:my-first-plugin。

Understanding the basic structure of plugins

The simplest WordPress plugin can consist of just one main file. This file must contain specific plugin header comments, which WordPress uses to identify the plugin’s information. You also need a security measure, namely direct access protection, which is usually achieved by performing checks.ABSPATHAre constants defined for a specific purpose?

The following is an example of a minimized plugin main file. The file can be named…my-first-plugin.phpAnd place it in the folder that was just created:

<?php
/**
 * Plugin Name:       我的第一个插件
 * Plugin URI:        https://yourwebsite.com/my-first-plugin
 * Description:       这是一个用于学习的入门级WordPress插件。
 * Version:           1.0.0
 * Author:            你的名字
 * License:           GPL v2 or later
 */

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

Place the folder that contains this file in the specified location.wp-content/pluginsAfter the directory is created, you will be able to see the plugin on the “Plugins” page in the WordPress administration panel, and you can activate it there.

Recommended Reading The Ultimate Guide to WordPress Plugin Development: Building Custom Functionality from Scratch。

Create the first core feature.

Now, let’s add some actual functionality to the plugin. We will create a simple feature that automatically adds a custom piece of text at the end of the article content.

Modify the content of the article using a filter

WordPress provides a large number of filter hooks, which allow you to modify data before it is saved to the database or displayed in the browser. To modify the content of an article, we can use these filter hooks.the_contentFilters.

In your main plugin file, add the following function and hook call after activating the hook:

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 my_first_plugin_add_text_to_content( $content ) {
    // 确保只在主循环的单篇文章页面执行
    if ( is_single() && in_the_loop() && is_main_query() ) {
        $additional_text = '<p><em>Thank you for reading this article! This article is supported by “My First Plugin”.</em></p>';
        $content .= $additional_text;
    }
    return $content;
}
// 将函数挂载到‘the_content’过滤器上
add_filter( 'the_content', 'my_first_plugin_add_text_to_content' );

This function first performs a series of conditional checks to ensure that the additional text is only displayed on individual article pages, and does not affect the home page, archive pages, or any other pages. After that, it appends a custom HTML paragraph to the original content.$contentAfter the variable, the modified content is returned.

Create a simple management settings page.

In order to allow users to customize the text they want to add, we need to create a setting option for them. This involves adding a menu item and a settings page in the WordPress administration panel.

First, useadd_actionThe hook adds a sub-menu page to the administrator menu:

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

// 创建管理菜单
function my_first_plugin_add_admin_menu() {
    add_options_page(
        '我的第一个插件设置', // 页面标题
        '我的插件设置',       // 菜单标题
        'manage_options',     // 所需权限
        'my-first-plugin',    // 菜单slug
        'my_first_plugin_settings_page' // 显示页面的回调函数
    );
}
add_action( 'admin_menu', 'my_first_plugin_add_admin_menu' );

Next, define the callback function for the display settings page.my_first_plugin_settings_pageAnd handle the form saving logic:

\n// Set the HTML content of the page
function my_first_plugin_settings_page() {
    ?>
    <div class="wrap">
        <h2>My first plugin settings</h2>
        <form method="post" action="/en/options.php/" data-trp-original-action="options.php">
            <p><strong>Output:</strong>  
  
</p>
        <input type="hidden" name="trp-form-language" value="en"/></form>
    </div>
    &lt;?php
}

// 注册设置、区域和字段
function my_first_plugin_settings_init() {
    register_setting( &#039;my_first_plugin_settings_group&#039;, &#039;my_first_plugin_custom_text&#039; );

add_settings_section(
        &#039;my_first_plugin_section&#039;,
        &#039;自定义文本设置&#039;,
        null,
        &#039;my-first-plugin&#039;
    );

add_settings_field(
        &#039;my_first_plugin_text_field&#039;,
        &#039;要在文末添加的文本&#039;,
        &#039;my_first_plugin_text_field_render&#039;,
        &#039;my-first-plugin&#039;,
        &#039;my_first_plugin_section&#039;
    );
}
add_action( &#039;admin_init&#039;, &#039;my_first_plugin_settings_init&#039; );

// 渲染文本输入字段
function my_first_plugin_text_field_render() {
    $option = get_option( &#039;my_first_plugin_custom_text&#039;, &#039;感谢您阅读这篇文章！本文由“我的第一个插件”提供支持。&#039; );
    echo &#039;<textarea name="my_first_plugin_custom_text" rows="3" cols="50">' . esc_textarea( $option ) . '</textarea>';
}

Finally, modify the function that appends text previously so that it takes options as input.my_first_plugin_custom_textRead the content from:

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 my_first_plugin_add_text_to_content( $content ) {
    if ( is_single() && in_the_loop() && is_main_query() ) {
        $custom_text = get_option( 'my_first_plugin_custom_text', '' );
        if ( ! empty( $custom_text ) ) {
            $additional_text = '<p><em>'. wp_kses_post($custom_text)'.'</em></p>';
            $content .= $additional_text;
        }
    }
    return $content;
}

Plugin security, optimization, and preparation for distribution

A qualified plugin not only needs to function properly, but also must be secure, efficient, and easy to maintain.

Data Validation, Escaping, and Security

Security is the lifeline of plugin development. Never trust data provided by users or directly retrieved from the database. Data must be escaped before being displayed on the page. In the previous code, we used…esc_textarea()On the management page, escape the output and use it.wp_kses_post()On the article page, HTML is filtered to allow only safe post content tags to pass through. For form processing, it is recommended to use the built-in mechanisms provided by WordPress, which include non-validation and permission checks.sanitize_text_field()Use functions such as… to clean the data.

Code Organization and Performance Optimization

As the number of plugin functions increases, it becomes difficult to manage all the code in a single main file. A good practice is to split the code into separate files based on their functionality. For example, you can create…includes/admin/The directory contains all the code related to the administration backend.includes/public/The directory contains the front-end functionality code.includes/class-*.phpStore class definitions.

In terms of performance, hooks should be used with caution. Make sure that the functions inside the hooks are only executed when necessary, for example, based on conditional statements. For option values that need to be retrieved from the database and are used multiple times on the front end, it’s advisable to store them in global variables or use object caching to avoid repeated database queries.

Ready to release your plugin?

If you plan to release the plugin in the official WordPress plugin directory or make it available for more people to use, there are several aspects that need to be addressed. First of all, make sure that the comments in the plugin header are complete and accurate. Secondly, write a clear…readme.txtThe file follows the official WordPress format requirements, detailing the plugin’s features, installation steps, and common issues. Finally, a thorough testing process is conducted, including compatibility tests on various PHP versions, different WordPress versions, as well as when used with various themes and other popular plugins.

summarize

Through this guide, we have completed the entire process of creating a fully functional WordPress plugin from scratch, including a user-friendly administration panel. We learned about the basic structure of plugins, how to interact with the WordPress core using action and filter hooks, how to create administration pages, and gained an initial understanding of the importance of plugin security and organization. The essence of plugin development lies in understanding WordPress’s event-driven architecture and knowing when to insert your custom code at the right moments. With this foundation, you can go on to explore more advanced topics such as custom post types, metadata, REST API endpoints, and the creation of database tables, and gradually build powerful, professional-level plugins.

FAQ Frequently Asked Questions

What are the basic knowledge requirements for developing WordPress plugins?

It will be very helpful for you to master the basic syntax of the PHP programming language and the concepts of object-oriented programming. You should also have a basic understanding of HTML, CSS, and JavaScript. Familiarity with the basic operations of WordPress and its core concepts, such as articles, pages, and taxonomies, is essential. Most importantly, you need to understand WordPress's hook mechanism (Actions and Filters), as this is the primary way plugins interact with WordPress.

What are the differences between the functions of plugins and themes, and how should one choose between them?

Themes primarily control the appearance and layout of a website, while plugins are used to add additional functionality. A good rule of thumb is: if a feature is closely related to the visual presentation of the website, it should be integrated into the theme; if the feature is independent (such as a contact form, SEO optimization, or e-commerce functionality), it should be implemented as a plugin. By designing features as plugins, you can ensure that they are not lost when you switch to a different theme. This is considered the best practice in WordPress development.

Can I create multiple PHP files within a plugin?

Absolutely! This is indeed the recommended approach, especially for complex plugins. You can split the different functional modules into separate files, and then manage them through the main plugin file.require_onceOrinclude_onceUse statements to introduce them. A good file structure helps with code organization and team collaboration.

How to debug the plugin I developed?

A common debugging method in WordPress development is to enable…WP_DEBUGYou can do that on the website.wp-config.phpIn the document, it will be stated that...define( 'WP_DEBUG', true );This will display PHP errors, warnings, and notifications on the screen. A more secure approach is to set both options at the same time.WP_DEBUG_LOGFortrue\n, record the error intowp-content/debug.logThe file is contained within the document. Additionally, using browser developer tools and debugging plugins such as Query Monitor can greatly improve efficiency.

My plugin needs to be compatible with as many older versions of WordPress as possible.

It depends on your target users. Generally, it is recommended to ensure compatibility with at least the first two versions of the current major version. You can refer to the official WordPress statistics to understand the version distribution. In your code, you can use conditional statements to handle different version scenarios.function_exists()To check whether a certain function or class is available, in order to ensure backward compatibility, within the plugin…readme.txtIn the file, it is necessary to clearly state the version of WordPress for which the test was successful.