How to Create a WordPress Plugin (Step by Step for Beginners)

So you want to create a WordPress plugin but don’t know where to start?

WordPress plugins allow you to add custom features to your website. There are thousands of them available for free and you can even create your own custom WordPress plugins.

In this guide we will show you how to create a WordPress plugin, and how to begin your WordPress plugin development journey.

About Creating Your First WordPress Plugin

WordPress plugins are like apps for your WordPress website. Just like apps on your phone, you can install plugins in WordPress to add new features.

To learn more about WordPress plugins, see our guide on WordPress plugins and how do they work?

You’ll need basic knowledge of coding languages like PHP, CSS, HTML, and JavaScript to write a plugin.

Sounds like a lot of learning, right?

Don’t worry, you can still follow our tutorial. We’ll walk you through the process step by step, and by the end of it you will have enough understanding of WordPress programming to create a simple WordPress plugin.

Note: This tutorial just shows how to write a basic plugin. To keep things simple, we will not dive into advanced WordPress coding skills.

What Do You Need to Create Your First WordPress Plugin?

First, you’ll need a local development environment to test your WordPress plugin on your computer. To set this up, see our guide on how to install WordPress on your Windows computer or Mac).

You can also test your plugin on a staging website. However, if an error occurs, then you may end up breaking your website which will make it inaccessible.

See our guide on how to fix common WordPress errors to tackle those issues.

You will also need a plain text editor to write your code. Notepad or TextEdit will work fine. However, if you want to try something more advanced, then check out these code editors for developers.

With those ready, let’s get started.

Creating Your First WordPress Plugin

The first step is to create a new folder on your desktop or documents folder, and name it something like wpb-plugin-tutorial or my-first-plugin.

Next, you need to create a new file in your text editor and save it inside your plugin folder as wpb-plugin-tutorial.php or my-first-plugin.php. The important thing is the .php extension, but you can name the file what you wish.

You’ll need to open that PHP file with your text editor.

The first thing you need to add to your plugin file is the plugin header. This comment block simply tells WordPress the name of your plugin, version, website, plugin author name, and more.

<?php
/*
Plugin Name:  WPBeginner Plugin Tutorial
Plugin URI:   https://www.wpbeginner.com 
Description:  A short little description of the plugin. It will be displayed on the Plugins page in WordPress admin area. 
Version:      1.0
Author:       WPBeginner 
Author URI:   https://www.wpbeginner.com
License:      GPL2
License URI:  https://www.gnu.org/licenses/gpl-2.0.html
Text Domain:  wpb-tutorial
Domain Path:  /languages
*/

After adding the plugin header, you can start adding the plugin code below it.

For this tutorial, we are going to create a simple plugin that adds a message at the end of each article asking users to follow us on Twitter.

Simply copy and paste the following code below your plugin header block.

function wpb_follow_us($content) {

// Only do this when a single post is displayed
if ( is_single() ) { 

// Message you want to display after the post
// Add URLs to your own Twitter and Facebook profiles

$content .= '<p class="follow-us">If you liked this article, then please follow us on <a href="http://twitter.com/wpbeginner" title="WPBeginner on Twitter" target="_blank" rel="nofollow">Twitter</a> and <a href="https://www.facebook.com/wpbeginner" title="WPBeginner on Facebook" target="_blank" rel="nofollow">Facebook</a>.</p>';

} 
// Return the content
return $content; 

}
// Hook our function to WordPress the_content filter
add_filter('the_content', 'wpb_follow_us'); 

Don’t forget to replace Twitter and Facebook profile URLs with your own before saving your changes.

Now go to the desktop on your computer and create a zip file for the plugin folder.

Mac users can right click on the folder and select ‘Compress wpb-plugin-tutorial’. Windows users can right click on the folder and select Send to » Compressed (zipped) folder.

Installing and Activating Your First WordPress Plugin

Now that we have created the plugin, it is time to test it out.

Head over to the WordPress admin area on your website and visit Plugins » Add New page.

You need to click on the ‘Upload Plugin’ button at the top to upload your plugin. This will show you the plugin upload box.

Go ahead and click on the Choose File button to select the zip file you just created. Next, click on the Install Now button to upload and install the plugin.

Once it’s installed, go ahead and activate the plugin.

You can now visit your website to see the plugin in action. You will be able to see the new paragraph at the end of all your single posts.

Submitting Your Plugin to WordPress.org Plugin Repository

If you want your plugin to be discovered and used by other WordPress users, then you can submit it to WordPress.org’s plugin repository.

To do that, first, you will need to create a ‘Read Me’ file for your plugin. Open a blank text file and save it as readme.txt in your plugin folder.

This readme.txt file needs to meet WordPress.org’s readme file syntax. The information you add in the readme.txt file will be displayed on your plugin’s page on WordPress.org.

Here is a sample readme.txt file that you can use as a starting point.

=== Your Plugin Name ===
Contributors: WPBeginner
Tags: wpbeginner, plugin tutorial
Requires at least: 5.5
Tested up to: 5.8
Stable tag: 1.0
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html

A WordPress plugin to teach beginners how to write a WordPress plugin. 

== Description ==

This simple plugin is part of our beginner's guide to writing a WordPress plugin. 

== Installation ==

1. Upload the plugin folder to your /wp-content/plugins/ folder.
1. Go to the **Plugins** page and activate the plugin.

== Frequently Asked Questions ==

= How do I use this plugin? =

Answer to the question

= How to uninstall the plugin? =

Simply deactivate and delete the plugin. 

== Screenshots ==
1. Description of the first screenshot. 
1. Description of the second screenshot. 

== Changelog ==
= 1.0 =
* Plugin released. 

Now let us explain a little bit about how the WordPress plugin readme file syntax works, so you can customize it for your plugin.

The first line of the plugin’s read me is your plugin name. This name will appear in the WordPress.org plugin directory as your plugin’s title.

The next line is Contributors. These are the user IDs responsible for managing your plugin on WordPress.org. If you don’t already have a WordPress.org user account, then you can create a free WordPress.org user account to get your user ID.

The ‘Requires at least’ and ‘Tested up to’ refer to the WordPress versions your plugin works with. The ‘Stable tag’ is the version of your own plugin.

You can leave the ‘License’ fields as GPL, and the URL the same.

Then, you can edit the Description area to explain what your plugin does.

After editing your plugin’s readme file, don’t forget to save your changes.

Now your plugin is ready to be reviewed by WordPress.org’s plugins team. To submit your plugin you will need a free WordPress.org account.

Visit the Add Your Plugin page and if you are not already logged in, then click on the login button at the top right corner of the screen.

Once logged in, you’ll be able to upload and submit your plugin for review. Simply click on the Select File button to select your plugin’s zip file and then click on the Upload button.

The WordPress.org plugin review team will then take a look at your plugin code for common errors and security checks. Once approved, you’ll receive an email from the plugins team.

This email will contain a link to the Subversion (SVN) repository of your plugin hosted on WordPress.org.

Using Subversion (SVN) to Upload Your Plugin

Subversion is a version control software. It allows users to make changes to files and directories while keeping a record of changes, managing different versions, and allowing collaboration.

You’ll need an SVN client installed on your computer to upload your plugin to WordPress.org.

Windows users can use SilkSVN or TortoiseSVN (free). Mac users can install SmartSVN or Versions App on their computers.

In this article, we will show you screenshots of Versions App for Mac. However, the process is very similar in all SVN apps with a GUI.

Once installed, you need to open the Versions app and checkout a copy of your WordPress plugin’s repository. Simply click on the ‘New Repository Bookmark’ button.

This will bring up a popup where first you need to provide a name for this bookmark. You can name it after your plugin. After that you need to add your WordPress plugin’s SVN repository URL.

Click on create button to connect with your repository.

The Versions App will now download a copy of your plugin’s repository to your computer. Next, right click on your repository name in the browser view and then select ‘Checkout’.

You will be asked to provide a name for the folder and select a location where you want to store it on your computer. You can use the same folder name as your plugin directory and click on checkout button to continue.

Versions app will now create a local copy of your plugin on your computer. You can view it under your plugin’s repository or browse it under Finder app.

Now you need to copy your plugin files and paste them inside the trunk folder of your local repository.

As you do that, you will notice a question mark icon next to new files in the Versions app.

Since these files didn’t exist before, you need to ‘Add’ them. Select the new files and click on the Add button to add these files in your local folder.

Now that your plugin files are added into subversion, you are now ready to upload them. Basically, you will be syncing changes in your local folder and the subversion directory.

Click on your local repository to select it and then click on the ‘Commit Changes’ button.

A new popup would appear and you will see the list of changes and a box to add a commit message.

Your SVN app will now sync your changes and commit them to your plugin’s repository.

Now that you have uploaded your plugin files to the trunk, it’s time to tag them to a version.

Go to the local copy of your plugin and copy the files inside the trunk folder. After that you need to open the tags folder and inside it create a new folder.

Name this folder after a version name. Make sure that it matches the version you have entered in your plugin’s header. In the sample code above, we have used version 1.0 for our plugin.

After adding the 1.0 folder in /tags/ folder. You will notice the question mark icon next to the folder name in the Version app.

Since this is a new folder, you will need to click on the Add button to include the folder and all its file in the repository.

After that you can go ahead and click on the commit button to sync your changes. You can continue editing your plugin files in the local copy.

Once you are done with your changes, simply click on the commit button to sync them with WordPress.org repository.

If you have made some major changes to your plugin, then you’ll want to add a new version by adding a new folder named after version number. Make sure that the version number matches your plugin’s header.

You can now preview your plugin on WordPress.org plugins directory.

Adding Artwork to Your Plugin on WordPress.org

WordPress.org allows you to add artwork and screenshots with your plugins. These items need to follow standard naming practices and should be uploaded using Subversion.

Plugin Header Banner

This is the large image that appears on top of the plugin page. It could be in 772 x 250 or 1544 x 500 pixels in jpeg or png file formats. It should always be named like this:

• banner-772×250.jpg or banner-772×250.png
• banner-1544×500.jpg or banner-1544×500.png

Plugin Icon

This is a smaller square shaped image file displayed as plugin icon in search results and plugin listings. It could be in 125 x 125 or 250 x 250 pixels in jpeg or png file formats.

This icon file should be named like this:

• icon-128×128.jpg or icon-128×128..png
• icon-256×256.jpg or icon-256×256.png

Screenshots

Screenshot files should be named using the following format:

• screenshot-1.png
• screenshot-2.png

You can add as many as you like. These screenshots should appear in the same order as the screenshot descriptions in your readme.txt file.

Once you have prepared all the artwork, you can place them into the assets folder of your plugin’s local copy.

After that you will notice a question mark icon next to assets folder. Click on the add button to add new assets file into your repository.

Finally, go ahead and click on the commit button to upload your files to WordPress.org repository. After a while you will be able to see the artwork appear on your plugin page.

Further Resources to Learn WordPress Plugin Development

WordPress plugins can be as simple as the one we showed you above. They can also be much more powerful like an eCommerce plugin, or membership plugins, contact form, or photo gallery plugins.

These more powerful WordPress plugins can also have addons. These addons work like plugins that extend other plugins.

Here are some resources that will help you learn more ways to add functionality into your WordPress plugins.

1. Adding a shortcode in WordPress
2. functions.php file tricks that you can now use in a site-specific plugin.
3. Creating custom post types and taxonomies.
4. Properly adding stylesheets and javascript in WordPress.

We hope this article helped you learn how to create a WordPress plugin. You may also want to take a look at these top WordPress plugins and study their source code for more examples.

If you liked this article, then please subscribe to our YouTube Channel for WordPress video tutorials. You can also find us on Twitter and Facebook.