A beginners’ guide for building and publishing your first WordPress plugin

Blog No Comments

WordPress is a popular and free content management system (CMS) you can use to build your websites. We believe that 38% of all active websites on the internet are made by WordPress. Today, there are about two billion websites out there but less than 400 million are active websites. So right now we have more than 160 million active WordPress websites that use WordPress plugins and themes. What a huge number! That’s why developers create more WordPress plugins every day. At the time of writing this tutorial, there are 58,000 plugins available in the WordPress plugin repository. Therefore, we can say that there is a good business opportunity for developers in the WordPress plugins world!

Now, what exactly are the WordPress plugins? Briefly, a WordPress plugin is like an application for your website. In other words, they are PHP programs that add more features to your website and make it more useful.

More than 160 million active WordPress websites and billions of users, make you think about learning how to create a WordPress plugin. So let’s start with the following questions:

  • What kind of knowledge do I need to create a WordPress plugin?
  • What kind of tools should I use for developing WordPress plugins?
  • How can I create my own WordPress plugin?
  • How can I publish it in the WordPress repository?

In this complete tutorial, I will answer all these questions and walk you through creating and publishing your first WordPress plugin, step by step.

The essential skills you need to be a plugin developer

Before you start to create a WordPress plugin, you should have a good understanding of programming and working with WordPress. The WordPress CMS is written in PHP as the programming language. So you need to have some PHP programming knowledge to create a WordPress plugin. Also, you need to read and write HTML/CSS scripts.

Don’t worry! There is no need to be a professional programmer. For the level of this tutorial, being able to read codes and being patient to create a plugin, is enough. Furthermore, creating simple WordPress plugins can be a good practice to improve your programming skills.

The essential tools for building a WordPress plugin

In order to create and publish a WordPress plugin, you need to install some software on your computer. In the following you can find a complete list of tools required for this purpose:

  • A test WordPress website on your local server: there are several local server solution packages like XAMPP, WAMP, AMPPS, and MAMP that allows you to install WordPress on your computer. It will help you to test a WordPress plugin safely.
  • A code editor: in this tutorial, we will use Notepad and Notepad++ as the text/code editor. However, you can use your custom program to write the scripts.
  • An email address: Before you can send your plugin for review, you must register on the wordpress.org website. I guess you already have an email!
  • An SVN software: in this tutorial, we would use TortoiseSVN because it’s a free and easy-to-use subversion client and it helps you to manage various versions of your WordPress plugin.

In the following, I will show you how to use these tools to create and publish your WordPress plugin.

Creating a simple WordPress plugin

The first plugin we want to create is a simple functional plugin. In other words, it is a plugin without any user interface (UI) and after installation and activation, it will hide the help tab from your WordPress admin area. Firstly, you need to choose a name for your plugin. I call mine “hide-help-tab-from-dashboard”. Such a long name! There are more than 58,000 plugins on the wordpress.org website so choosing a unique name is not an easy task!

Every WordPress plugin has a PHP file that includes the most important information about the plugin. A complicated and huge plugin has several PHP files. Moreover, it can include a lot of CSS and JS files. But our simple plugin has just a single PHP file.

Creating the main PHP file

in order to create this file, open the Notepad++, and in the top bar click File > New. Then, in the top bar click File > Save as and give your file a name (hide-help-tab-from-dashboard.php) and save it with .php extension. Next, create a new folder with the same name as the file and move the file in it.

Adding header comment to the PHP file

OK! Let’s code now!

Firstly, you need to add a multi-line comment to your file. We call it “header comment” and it tells WordPress that our PHP file is a plugin. Here is the header comment which you should include in all your WordPress plugins.

/**
* Plugin Name:        My Basics Plugin
* Plugin URI:         https://example.com/plugins/the-basics/
* Description:        Handle the basics with this plugin.
* Version:            1.10.3
* Requires at least: 5.2
* Requires PHP:       7.2
* Author:             John Smith
* Author URI:         https://author.example.com/
* License:            GPL v2 or later
* License URI:        https://www.gnu.org/licenses/gpl-2.0.html
* Text Domain:        my-basics-plugin
* Domain Path:        /languages
*/

Now, let’s take a look at this important comment:

  • Plugin name: It is the name of your plugin. Our plugin’s name is ” hide help tab from dashboard”.
  • Plugin URL: Use your own website URL for this line. Remember this URL should be a unique address.
  • Description: This is a short description of the plugin. Keep it to fewer than 140 characters.
  • Version: The current version of the plugin. This is your first plugin so you should write 1.0.0 for this line.
  • Requires at least: This line must show the lowest WordPress version that your plugin will work on.
  • Requires PHP: The lowest required PHP version.
  • Author: Write your name as the author of the plugin here.
  • Author URL: Link your website or profile in this line.
  • License URL: a link to the license (such as https://gnu.org/licenses/gpl-2.0.html)
  • Text domain: use your plugin name with dashes (-) instead of spaces for this line.
  • Domain path: Tell WordPress where the translation files are. In this tutorial, we will not talk about languages and the translation process.

Well! Now that you know what the header comment is, let’s customize it and paste it on the first line of our PHP file. After this, the hide-help-tab-from-dashboard.php file should look like this:

<?php
/**
* Plugin Name:       hide help tab from dashboard
* Description:       this plugin will hide the help tab from the wordpress dashboard.
* Version:           1.0.0
* Requires at least: 3.0.1
* Requires PHP:      7.2
* Author:            amin agha kazemi
* Author URI:        https://aminakazemi.info/
* License:           GPL v2 or later
* License URI:       https://www.gnu.org/licenses/gpl-2.0.html
* Text Domain:       hide-help-tab-from-dashboard
* Domain Path:       /languages
*/
?>

The comment above tells WordPress that this file is a plugin. Don’t forget to Save the file.

Adding functionality to the plugin

In order to add functionality to a plugin, we need to add some WordPress functions to it. The name of our plugin is “hide help tab from dashboard” and it does what it’s supposed to do. The function below will hide the help tab from the WordPress admin area. So go on and paste it below the header comment in your PHP file.

add_filter('contextual_help_list','contextual_help_list_remove');
function contextual_help_list_remove(){
global $current_screen;
$current_screen->remove_help_tabs();
}

Finally, the hide-help-tab-from-dashboard.php file should look like this:

<?php
/**
* Plugin Name:       hide help tab from dashboard
* Description:       this plugin will hide the help tab from the wordpress dashboard.
* Version:           1.0.0
* Requires at least: 3.0.1
* Requires PHP:      7.2
* Author:            amin agha kazemi
* Author URI:        https://aminakazemi.info/
* License:           GPL v2 or later
* License URI:       https://www.gnu.org/licenses/gpl-2.0.html
* Text Domain:       hide-help-tab-from-dashboard
* Domain Path:       /languages
*/

add_filter('contextual_help_list','contextual_help_list_remove');
function contextual_help_list_remove(){
global $current_screen;
$current_screen->remove_help_tabs();
}
?>

Save the file and zip the hide-help-tab-from-dashboard folder (I have used the WinRAR program to zip the folder). then you’ll have what you want … a WordPress plugin! Congratulations!

Testing the plugin

To test the correctness of the plugin, in your WordPress admin area click Plugins > Add New and select Upload Plugin.

After installation and activation, it will hide the help tab from your WordPress admin area. To increase the trust in the correctness of the plugin, simply deactivate it. Then you will see that the help tab appears again on the dashboard’s top bar.

Hiding the help tab is a task or functionality that we have done by using programming languages. You can write more complicated codes to make a better plugin.

Well! Now that you know the structure of a simple WordPress plugin, let’s go further and create a more difficult project.

Creating a WordPress plugin with a beautiful user interface

Most WordPress users prefer a plugin with a settings page or user interface (UI). It makes them have a better feeling about managing and controlling their website. In this step, I will show you how to create a plugin with a settings page. Our case is a plugin that helps users to create a new dashboard widget for their WordPress admin area.

Creating the main PHP file

First, open notepad++ and create a new file as you did before in the previous example. Then, paste the header comment in the first line and customize it like the comment below:

/**
* Plugin Name:       create a custom dashboard widget
* Description:       this plugin will help you to create your custom dashboard widget.
* Version:           1.0.0
* Requires at least: 3.0.1
* Requires PHP:      7.2
* Author:            amin agha kazemi
* Author URI:        https://aminakazemi.info/
* License:           GPL v2 or later
* License URI:       https://www.gnu.org/licenses/gpl-2.0.html
* Text Domain:       create-a-custom-dashboard-widget
* Domain Path:       /languages
*/

Now save the file and name it as “create-a-custom-dashboard-widget.php”. then create a new folder with the same name as the file and relocate the file in it.

Adding functionality to the plugin

The main functions of this plugin have the responsibility to create a new widget for the WordPress dashboard. Here are these functions:

function cacdw_register_settings() {
add_option( 'cacdw_main_option', 'This is an option value.');
register_setting( 'cacdw_options_group', 'cacdw_main_option', 'cacdw_callback' );
}
add_action( 'admin_init', 'cacdw_register_settings' );add_action('wp_dashboard_setup', 'cacdw_my_custom_dashboard_widgets');function cacdw_my_custom_dashboard_widgets() {
global $wp_meta_boxes;wp_add_dashboard_widget('custom_help_widget', 'Custom dashboard widget', 'cacdw_custom_dashboard_help');
}function cacdw_custom_dashboard_help() {
echo '<p> This is a custom text and <a href="https://www.aminakazemi.info" target="_blank">this is a link</a></p>';
}

Copy and paste them below the header comment. After pasting these codes, your PHP file should look like this:

<?php

/**
* Plugin Name:       create a custom dashboard widget
* Description:       this plugin will help you to create your custom dashboard widget.
* Version:           1.0.0
* Requires at least: 3.0.1
* Requires PHP:      7.2
* Author:            amin agha kazemi
* Author URI:        https://aminakazemi.info/
* License:           GPL v2 or later
* License URI:       https://www.gnu.org/licenses/gpl-2.0.html
* Text Domain:       create-a-custom-dashboard-widget
* Domain Path:       /languages
*/

function cacdw_register_settings() {
add_option( 'cacdw_main_option', 'This is an option value.');
register_setting( 'cacdw_options_group', 'cacdw_main_option', 'cacdw_callback' );
}
add_action( 'admin_init', 'cacdw_register_settings' );

add_action('wp_dashboard_setup', 'cacdw_my_custom_dashboard_widgets');

function cacdw_my_custom_dashboard_widgets() {
global $wp_meta_boxes;

wp_add_dashboard_widget('custom_help_widget', 'Custom dashboard widget', 'cacdw_custom_dashboard_help');
}

function cacdw_custom_dashboard_help() {
echo '<p> This is a custom text and <a href="https://www.aminakazemi.info" target="_blank">this is a link</a></p>';
}

?>

Then save the file, zip the folder, and test the plugin in your localhost. After installation and activation, you will see that a new widget appears under the dashboard tab in your WordPress admin area.

Creating a user interface (UI)

Now let’s add a settings page to the plugin. To do that, you need to change the PHP file again. But don’t worry! There is no need to deactivate or delete your plugin. Simply navigate to “wp-admin/plugins/create-a-custom-dashboard-widget” in your localhost. There you can find and open the create-a-custom-dashboard-widget.php file. Thus you can change your plugin’s codes and have a live view of it on your local WordPress site. It’s a pretty good trick for testing and debugging your plugins.

Alright! Let’s get back to adding an interface to the plugin. The code below has the responsibility to add a submenu to the left-hand menu of your WordPress admin area and it will create an empty setting page for the plugin.

function cacdw_register_options_page() {
add_options_page('Page Title', 'Custom dashboard widget', 'manage_options', 'cacdw_plugin', 'cacdw_options_page');
}
add_action('admin_menu', 'cacdw_register_options_page');function cacdw_options_page()
{
?><?php settings_fields( 'cacdw_options_group' ); ?><?php
}

Copy the code above and paste it below the “add_action( ‘admin_init’, ‘cacdw_register_settings’ );” line. Your PHP file should look like this:

<?php

/**
* Plugin Name:       create a custom dashboard widget
* Description:       this plugin will help you to create your custom dashboard widget.
* Version:           1.0.0
* Requires at least: 3.0.1
* Requires PHP:      7.2
* Author:            amin agha kazemi
* Author URI:        https://aminakazemi.info/
* License:           GPL v2 or later
* License URI:       https://www.gnu.org/licenses/gpl-2.0.html
* Text Domain:       create-a-custom-dashboard-widget
* Domain Path:       /languages
*/

function cacdw_register_settings() {
add_option( 'cacdw_main_option', 'This is an option value.');
register_setting( 'cacdw_options_group', 'cacdw_main_option', 'cacdw_callback' );
}
add_action( 'admin_init', 'cacdw_register_settings' );

function cacdw_register_options_page() {
add_options_page('Page Title', 'Custom dashboard widget', 'manage_options', 'cacdw_plugin', 'cacdw_options_page');
}
add_action('admin_menu', 'cacdw_register_options_page');

function cacdw_options_page()
{
?>

<?php settings_fields( 'cacdw_options_group' ); ?>

<?php
}

add_action('wp_dashboard_setup', 'cacdw_my_custom_dashboard_widgets');

function cacdw_my_custom_dashboard_widgets() {
global $wp_meta_boxes;

wp_add_dashboard_widget('custom_help_widget', 'Custom dashboard widget', 'cacdw_custom_dashboard_help');
}

function cacdw_custom_dashboard_help() {
echo '<p> This is a custom text and <a href="https://www.aminakazemi.info" target="_blank">this is a link</a></p>';
}

?>

Now if you save the file and reload the admin page (yoursite.com/wp-admin), you will see a new submenu under the settings menu like the screenshot below:

Customizable dynamic plugin

As you can see, creating a functional WordPress plugin is a simple task. But for beginners, what makes it difficult to create a WordPress plugin is making the functions dynamic or customizable. In a dynamic plugin, the output is customizable via its settings page. In this step, we will try to change the content of our dashboard widget via the premade settings page.

In order to do that, you need to replace the codes below in your create-a-custom-dashboard-widget.php file:

<?php

/* Start Adding Functions Below this Line *//**
* Plugin Name:       create a custom dashboard widget
* Description:       this plugin will help you to create your custom dashboard widget.
* Version:           1.0.0
* Requires at least: 3.0.1
* Requires PHP:      7.2
* Author:            amin agha kazemi
* Author URI:        https://aminakazemi.info/
* License:           GPL v2 or later
* License URI:       https://www.gnu.org/licenses/gpl-2.0.html
* Text Domain:       create-a-custom-dashboard-widget
* Domain Path:       /languages
*/

function cacdw_register_settings() {
add_option( 'cacdw_main_option', 'This is an option value.');
register_setting( 'cacdw_options_group', 'cacdw_main_option', 'cacdw_callback' );
}
add_action( 'admin_init', 'cacdw_register_settings' );

function cacdw_register_options_page() {
add_options_page('Page Title', 'Custom dashboard widget', 'manage_options', 'cacdw_plugin', 'cacdw_options_page');
}
add_action('admin_menu', 'cacdw_register_options_page');

function cacdw_options_page()
{
?>

<!-- setting page -->
<h2>Create a custom dashboard widget</h2>
<hr />
<div id="mainpart">
<form method="post" action="options.php">
<?php settings_fields( 'cacdw_options_group' ); ?>
<h4>write your custom html or text below and click "save changes". then, your widget will appear on your dashboard page. dont forget to use <b>&lt;br/&gt;</b> tag.</h4>
<textarea rows="10" cols="45" id="cacdw_main_option" name="cacdw_main_option"><?php echo get_option('cacdw_main_option'); ?></textarea>
</br>
</br>
<h4>preview:</h4>
<div id="preview">
<?php echo get_option('cacdw_main_option'); ?>
</div>
</br>
<?php  submit_button(); ?>
</form>
</div>
<?php
}

add_action('wp_dashboard_setup', 'cacdw_my_custom_dashboard_widgets');

function cacdw_my_custom_dashboard_widgets() {
global $wp_meta_boxes;

wp_add_dashboard_widget('custom_help_widget', 'Custom dashboard widget', 'cacdw_custom_dashboard_help');
}

function cacdw_custom_dashboard_help() {
echo get_option('cacdw_main_option');
}
/* Stop Adding Functions Below this Line */
?>

As you can see, we just add some fields to the settings page and integrate the content with a text field. Save the file and reload the settings page in your WordPress admin area.

Now your UI has a text input and a live preview of your widget. Feel free and write something in the text field and then click Save. Then in the left-hand menu select the dashboard tab and take a look at your new widget.

Styling the settings page or user interface (UI)

If you can write CSS codes, then you may know that this is the best part of this tutorial. Styling is fun and you can do it as you like. But here are some CSS codes that you can add to your PHP file. These codes make your setting page more beautiful.

<!-- css style -->
<style>
h2 {color:#00b8a9; text-align: center;}
textarea {width: 100%;}
hr {margin-right: 20px;}
#mainpart {
background-color: e3fdfd;
margin-right: 35px;
margin-left: 15px;
margin-top: 25px;
padding: 50px;
border-radius: 15px;
border: 1px solid;
}
#preview {
background-color: #fff;
width: 50%;
padding: 25px;
border-radius: 8px;
box-shadow: 0px 0px 5px 3px #888888;
}
</style>

If you want to learn more about CSS tricks, you can find loads of useful articles here.

Finally, your PHP file should look like this:

<?php

/* Start Adding Functions Below this Line *//**
* Plugin Name:       create a custom dashboard widget
* Description:       this plugin will help you to create your custom dashboard widget.
* Version:           1.0.0
* Requires at least: 3.0.1
* Requires PHP:      7.2
* Author:            amin agha kazemi
* Author URI:        https://aminakazemi.info/
* License:           GPL v2 or later
* License URI:       https://www.gnu.org/licenses/gpl-2.0.html
* Text Domain:       create-a-custom-dashboard-widget
* Domain Path:       /languages
*/

function cacdw_register_settings() {
add_option( 'cacdw_main_option', 'This is an option value.');
register_setting( 'cacdw_options_group', 'cacdw_main_option', 'cacdw_callback' );
}
add_action( 'admin_init', 'cacdw_register_settings' );

function cacdw_register_options_page() {
add_options_page('Page Title', 'Custom dashboard widget', 'manage_options', 'cacdw_plugin', 'cacdw_options_page');
}
add_action('admin_menu', 'cacdw_register_options_page');

function cacdw_options_page()
{
?>

<!-- css style -->
<style>
h2 {color:#00b8a9; text-align: center;}
textarea {width: 100%;}
hr {margin-right: 20px;}
#mainpart {
background-color: e3fdfd;
margin-right: 35px;
margin-left: 15px;
margin-top: 25px;
padding: 50px;
border-radius: 15px;
border: 1px solid;
}
#preview {
background-color: #fff;
width: 50%;
padding: 25px;
border-radius: 8px;
box-shadow: 0px 0px 5px 3px #888888;
}
</style>

<!-- setting page -->
<h2>Create a custom dashboard widget</h2>
<hr />
<div id="mainpart">
<form method="post" action="options.php">
<?php settings_fields( 'cacdw_options_group' ); ?>
<h4>write your custom html or text below and click "save changes". then, your widget will appear on your dashboard page. dont forget to use <b>&lt;br/&gt;</b> tag.</h4>
<textarea rows="10" cols="45" id="cacdw_main_option" name="cacdw_main_option"><?php echo get_option('cacdw_main_option'); ?></textarea>
</br>
</br>
<h4>preview:</h4>
<div id="preview">
<?php echo get_option('cacdw_main_option'); ?>
</div>
</br>
<?php  submit_button(); ?>
</form>
</div>
<?php
}

add_action('wp_dashboard_setup', 'cacdw_my_custom_dashboard_widgets');

function cacdw_my_custom_dashboard_widgets() {
global $wp_meta_boxes;

wp_add_dashboard_widget('custom_help_widget', 'Custom dashboard widget', 'cacdw_custom_dashboard_help');
}

function cacdw_custom_dashboard_help() {
echo get_option('cacdw_main_option');
}
/* Stop Adding Functions Below this Line */
?>

Congratulations! You have created the second plugin in this tutorial. Save the file and test it on your local WordPress website.

Important tip: remember, all the WordPress plugins in the WordPress repository must have unique function names, namespaces, defines, class names, and permalinks. This prevents your plugin from conflicting with other plugins or themes. A good way to do this is with a prefix. For example, we used ” CACDW” as the prefix in our code. The “CACDW” prefix stands for Create a Custom Dashboard Widget”.

Learn more about creating WordPress plugins here.

Publishing the plugin

We assume that you have created a unique WordPress plugin for yourself and now you want to share it with others. To do that, you should publish it as a free plugin on the wordpress.org website.

Here are the steps that you need to follow to publish your plugin:

  1. Create a readme.txt file
  2. Sign up on the wordpress.org site
  3. Send your plugin for review and validation
  4. Preparing the logo and banner (after approval)
  5. The final step for publishing the plugin by using the SVN (a release system)

Creating a readme.txt file

The readme.txt file contains all the important information about a WordPress plugin. There is a drafted or pre-written readme.txt file that you can use to create your file. Find it here.

Customize the content above (check the link) based on your own plugin. We did that before and here is the result:

=== create a custom dashboard widget ===
Contributors: (aminak35)
Tags: customize wordpress dashboard, custom dashboard widget
Requires at least: 3.0.1
Tested up to:  5.6
Stable tag: 4.3
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
this plugin will help you to create your custom dashboard widget.== Description ==
this plugin will help you to create your custom dashboard widget using html code.== Installation ==
This section describes how to install the plugin and get it working.
e.g.
1. Upload `create-a-custom-dashboard-widget.php` to the `/wp-content/plugins/` directory
2. Activate the plugin through the 'Plugins' menu in WordPress== Frequently Asked Questions ==
= How can I create my own dashboard widget? =
In your wordpress admin area go to Settings > Custom dashboard widget. use HTML to crate your custom widget.== Screenshots ==1. Plugin setting page
2. Your custom widget in the dashboard page

You can simply use Notepad or Notepad++ to create a TXT file. Just write your content like above and save it with a .txt extension. Don’t forget to relocate it to your plugins folder.

Registering on the wordpress.org website

It’s a simple task. Visit the wordpress.org site and click on the Register button. Then choose a unique username and email and click Create Account. Next, you need to check your inbox to confirm the email you have entered.

Send your plugin for review and validation

After you log in, you need to navigate to “wordpress.org/plugins/developers/add“.

From here, you can select and send your zip file for review.

Tip: as you may already know, your zip file should contain the plugin (PHP file) and the readme.txt file.

Once you send your plugin, it will be manually reviewed for errors and issues. The review managers will email you more information about the approval process of your plugin.

Preparing the logo, banner, and screenshots

Once your plugin is approved (up to 7 days later), you will receive an email with a URL to your plugin. It will include an SVN address to take the final step for publishing your plugin. But before doing that, we recommend you to prepare a logo and banner for your plugin. They must have certain sizes, names, and extensions like the following:

  • Icon-128×png
  • Icon-256×png
  • Banner-772×png

Also, you can create several screenshots to show on your plugin page on the wordpress.org website. If you want to do that, don’t forget to mention them in your readme.txt file (like I did before). Name the screenshots as “screenshot-1” and “screenshot-2” and so on.

The final step for publishing the plugin by using a release system

Now that your plugin is ready for publishing, it’s time to take the final step! Do the following:

First, install TortoiseSVN on your computer. Then, create a new folder with the same name as your plugin and Right-click on your new folder and select “SVN Checkout”. Finally, Login and paste your pre-received SVN in the first field and click ok. (like the screenshot below)

Please wait! And once you see the “Completed” message, click ok again. This will create some new directories in the folder. Then open the folder, and paste all your images (the logo, banner, and screenshots) into the “assets” directory. Also, copy and paste main files (PHP file and readme.txt file) in the “trunk” directory.

Once you do the previous steps, right-click on your plugin’s folder and select “SVN Commit”. Then, write a custom message and click ok.

That’s it! You have published your first WordPress plugin. You can go to the plugin’s Public URL and download it for the first time.

Summary

In this tutorial, we have created two different WordPress plugins. Also, we learned how to publish our first plugin on the WordPress repository. Now you can start to create several plugins using some free programs and skills. I hope this tutorial helped you learn how to be a WordPress developer. Thanks for reading this far.

Guide author: Amin A. Kazemi

We really appreciate you for visiting PremiumCoding and reading this article! Now you might also want to check out our Themes here.