Skip to content

How to Create a Custom Plugin in WordPress

By ali 8 min read

Create a custom plugin in WordPress using PHP, hooks, shortcodes, and custom functionality

Creating a custom plugin in WordPress is a great way to add unique functionality to your website without modifying WordPress core files or relying on multiple third-party plugins.

Whether you want to create a custom shortcode, add a settings page, register a custom post type, or integrate an external API, a custom plugin gives you complete control over your functionality.

In this guide, we’ll walk through the process of creating a basic WordPress plugin, adding custom functionality, loading CSS and JavaScript files, and following important development and security practices.

1. Set Up Your WordPress Development Environment

Before creating a plugin, set up a local WordPress installation or staging website. This allows you to develop and test your code without affecting your live website.

You will need:

  • A working WordPress installation.
  • A code editor such as Visual Studio Code.
  • Access to your WordPress files.
  • Basic knowledge of PHP, HTML, CSS, and JavaScript.
  • A local or staging environment for testing.

It is always a good idea to keep a backup of your website before making significant changes.

2. Create a New Plugin Directory

Every WordPress plugin should have its own directory inside the wp-content/plugins/ folder.

Open your WordPress installation and navigate to:

wp-content/plugins/

Create a new folder for your plugin. For this tutorial, we’ll use the following name:

geekerhub-custom-plugin

You can choose any unique folder name that describes your plugin’s purpose. Avoid spaces in the folder name and use lowercase letters with hyphens where appropriate.

3. Create the Main Plugin PHP File

Inside the newly created folder, create a PHP file named:

geekerhub-custom-plugin.php

Your plugin directory should now look like this:

geekerhub-custom-plugin/
 geekerhub-custom-plugin.php

The main PHP file contains the plugin header, which provides WordPress with information about your plugin.

Add the following code to the file:

<?php
/**
 * Plugin Name: GeekerHub Custom Plugin
 * Description: A simple custom WordPress plugin.
 * Version: 1.0.0
 * Author: GeekerHub
 * Text Domain: geekerhub-custom-plugin
 */

// Prevent direct access to this file.
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

The plugin header includes important information:

  • Plugin Name: The name displayed in the WordPress Plugins screen.
  • Description: A short explanation of what the plugin does.
  • Version: The current plugin version.
  • Author: The plugin developer or organization.
  • Text Domain: The identifier used for translation functions.

The ABSPATH check prevents the PHP file from running when accessed directly outside the normal WordPress environment.

4. Add an Activation Hook

WordPress provides activation and deactivation hooks that allow you to perform specific tasks when a plugin is activated or deactivated.

For example, you might use an activation hook to create a custom database table or initialize default plugin settings.

Add the following code to your main plugin file:

function geekerhub_custom_plugin_activate() {

    // Add activation tasks here.
    // Example: Set default plugin options.

    add_option(
        'geekerhub_custom_plugin_version',
        '1.0.0'
    );
}

register_activation_hook(
    __FILE__,
    'geekerhub_custom_plugin_activate'
);

The register_activation_hook() function registers a callback that WordPress runs when the plugin is activated.

You can also register a deactivation hook when your plugin needs to perform cleanup tasks, such as clearing scheduled events.

function geekerhub_custom_plugin_deactivate() {

    // Add deactivation tasks here.
}

register_deactivation_hook(
    __FILE__,
    'geekerhub_custom_plugin_deactivate'
);

Do not delete important user data during deactivation unless that is explicitly part of your plugin’s intended behavior. Data removal is generally better handled through a separate uninstall process.

For more information, see the official WordPress activation and deactivation hooks documentation.

5. Add Custom Functionality Using WordPress Hooks

Now you can start adding the functionality your plugin is designed to provide.

WordPress provides two main types of hooks:

  • Actions: Allow you to execute custom code at specific points during WordPress execution.
  • Filters: Allow you to modify data before WordPress uses or displays it.

For example, you can use the wp_footer action to display a simple message in your website’s footer.

function geekerhub_custom_footer_message() {

    echo '<p>Welcome to GeekerHub!</p>';
}

add_action(
    'wp_footer',
    'geekerhub_custom_footer_message'
);

This code adds a message to the footer whenever the theme executes the wp_footer() function.

For more information about actions and filters, refer to the official WordPress Hooks documentation.

6. Create a Custom Shortcode

Shortcodes are useful when you want website administrators or editors to display custom functionality inside posts and pages.

For example, let’s create a shortcode that displays a simple welcome message.

function geekerhub_custom_welcome_shortcode() {

    return '<div class="geekerhub-welcome">
        Welcome to our website!
    </div>';
}

add_shortcode(
    'geekerhub_welcome',
    'geekerhub_custom_welcome_shortcode'
);

After adding this code to your plugin, you can use the following shortcode in a WordPress post or page:

[geekerhub_welcome]

WordPress will execute the shortcode callback and display the returned HTML content.

Always return shortcode output instead of directly printing it with echo. This helps WordPress place the generated content correctly.

7. Organize Your Plugin Files

As your plugin grows, keeping all functionality in one PHP file can make the code difficult to maintain.

You can organize your plugin into separate files for different responsibilities.

For example, use this directory structure:

geekerhub-custom-plugin/
│
├── geekerhub-custom-plugin.php
│
├── includes/
│   ├── custom-functions.php
│   └── custom-shortcodes.php
│
├── admin/
│   └── admin-functions.php
│
├── assets/
│   ├── css/
│   │   └── style.css
│   │
│   └── js/
│       └── script.js
│
└── readme.txt

You can load your additional PHP files from the main plugin file using require_once.

require_once plugin_dir_path( __FILE__ ) .
    'includes/custom-functions.php';

require_once plugin_dir_path( __FILE__ ) .
    'includes/custom-shortcodes.php';

This approach separates different parts of your plugin and makes future updates easier.

8. Load CSS and JavaScript Files Properly

If your plugin needs custom styles or JavaScript, use WordPress’s enqueue functions instead of directly printing script or stylesheet tags.

For example, add the following code to your main plugin file:

function geekerhub_custom_plugin_assets() {

    wp_enqueue_style(
        'geekerhub-custom-plugin-style',
        plugin_dir_url( __FILE__ ) . 'assets/css/style.css',
        array(),
        '1.0.0'
    );

    wp_enqueue_script(
        'geekerhub-custom-plugin-script',
        plugin_dir_url( __FILE__ ) . 'assets/js/script.js',
        array(),
        '1.0.0',
        true
    );
}

add_action(
    'wp_enqueue_scripts',
    'geekerhub_custom_plugin_assets'
);

This example loads the CSS and JavaScript files on the frontend of your website.

If the assets are needed only in the WordPress administration area, use the admin_enqueue_scripts action instead.

For more details, check the official WordPress documentation on enqueuing scripts and styles.

9. Add Security to Your Custom Plugin

Security should be considered from the beginning of plugin development. A plugin may process user input, save settings, handle form submissions, or perform administrative actions. Each of these operations should be handled carefully.

Follow these important practices:

  • Sanitize input: Clean incoming data using functions such as sanitize_text_field() and sanitize_email().
  • Validate data: Check that submitted values meet the expected format and requirements.
  • Escape output: Use functions such as esc_html(), esc_attr(), and esc_url() when displaying dynamic data.
  • Check permissions: Use current_user_can() before allowing users to perform privileged actions.
  • Use nonces: Add and verify WordPress nonces for actions such as processing administrative forms and handling requests.
  • Use secure database queries: Use the WordPress database API and prepared queries when handling variable values.

For example, if you want to display a value safely, you can use:

$message = 'Welcome to GeekerHub';

echo esc_html( $message );

When building a settings page, make sure the user has the required capability and verify the submitted nonce before saving settings.

For additional guidance, read the official WordPress Plugin Security Handbook.

10. Test Your Custom WordPress Plugin

After adding the functionality, activate your plugin from the WordPress administration dashboard.

Navigate to:

WordPress Dashboard → Plugins → Installed Plugins

Find your custom plugin and click Activate.

Test the plugin carefully in your development or staging environment.

Check the following:

  • Does the plugin activate without errors?
  • Does the shortcode display the expected output?
  • Are CSS and JavaScript files loading correctly?
  • Does the plugin work with your active theme?
  • Does it conflict with other installed plugins?
  • Are user permissions and form submissions handled correctly?
  • Does the plugin work when WordPress debugging is enabled?

Testing with different user roles and common WordPress configurations can help you identify issues before releasing your plugin.

11. Add Plugin Documentation

Good documentation makes your plugin easier to use, maintain, and distribute.

Create a readme.txt file inside your plugin directory. Include information such as:

  • Plugin name and description.
  • Installation instructions.
  • Available features.
  • Shortcodes and their usage.
  • Configuration instructions.
  • Requirements and compatibility information.
  • Changelog and version details.

If you plan to publish your plugin in the WordPress Plugin Directory, follow its readme.txt guidelines.

12. Optimize and Maintain Your Plugin

Creating a plugin is only the first step. You should also maintain it as WordPress, PHP, and other plugins evolve.

Consider these development practices:

  • Use WordPress functions and APIs instead of recreating existing functionality.
  • Avoid loading unnecessary scripts and styles.
  • Use unique function names or PHP namespaces to reduce naming conflicts.
  • Keep your code organized and follow WordPress coding standards.
  • Test your plugin after WordPress and PHP updates.
  • Remove unused code and fix reported errors.
  • Maintain version numbers and document important changes.

These practices make your plugin easier to maintain and reduce the chance of compatibility problems.

13. Deploy Your Plugin to a Live Website

Once your plugin has been tested successfully, you can move it to your live WordPress website.

You can deploy it by uploading the plugin folder to:

wp-content/plugins/

Alternatively, compress the plugin directory into a ZIP file and upload it through:

WordPress Dashboard → Plugins → Add New Plugin → Upload Plugin

After uploading the plugin, activate it from the Plugins screen and verify that all functionality works correctly on the live website.

If you plan to distribute your plugin publicly, review the WordPress Plugin Directory requirements before submitting it.

Conclusion

Creating a custom WordPress plugin is a practical way to extend your website with functionality that matches your specific requirements. By creating a plugin directory, adding a valid plugin header, registering hooks, building shortcodes, and loading assets correctly, you can develop a well-organized plugin.

Remember to follow WordPress coding and security practices, test your code in a development environment, and document your functionality. With regular practice, you can build custom plugins that are easier to maintain, extend, and distribute.