How to Create Your First WordPress Plugin from Scratch (No Experience Needed)
I remember when I first started — the whole thing seemed intimidating. But here’s the truth: building a basic WordPress plugin is much easier than you think.
By the end of this guide, you’ll have a working plugin that displays a notification bar at the top of your website. More importantly, you’ll understand the fundamental concepts that power every WordPress plugin out there.
What Is a WordPress Plugin and Why Should You Build One?
A WordPress plugin is essentially a piece of software that adds new features or extends the functionality of your WordPress site. Think of WordPress as a house and plugins as the furniture and decorations — they make it more functional and personalized.
You might be wondering: “Why would I build my own plugin when there are thousands available?”
Great question! Here are a few reasons:
- Learn how WordPress really works — Building plugins gives you a deep understanding of WordPress internals
- Create exactly what you need — Sometimes existing plugins are too bloated or don’t quite fit your needs
- It’s actually fun — There’s something incredibly satisfying about seeing your code come to life on a website
- Career opportunities — WordPress powers over 40% of the web, and plugin development skills are in demand
Prerequisites: What You Need Before Starting
Don’t worry — you don’t need to be a PHP expert. Here’s what you should have:
Knowledge-wise:
- Basic understanding of PHP syntax (variables, functions, arrays)
- Familiarity with HTML and CSS
- Basic understanding of how WordPress works from a user perspective
Tools you’ll need:
- A local WordPress installation (I recommend Local by Flywheel or XAMPP)
- A code editor (VS Code, Sublime Text, or even Notepad++ will work)
- Access to your WordPress plugins folder
If you don’t have a local WordPress installation yet, grab Local by Flywheel — it’s free and gets you up and running in minutes.
Understanding the Plugin Structure
Before we dive into coding, let’s understand what WordPress needs from a plugin. At its most basic, a WordPress plugin can be a single PHP file. That’s it. Just one file.
WordPress looks for plugins in the wp-content/plugins/ directory. Each plugin lives in its own folder (though single-file plugins can exist without a folder).
Here’s the structure we’ll use for our notification bar plugin:
wp-content/plugins/
└── hello-bar/
└── hello-bar.phpSimple, right? We’ll add more files later if we want to expand it, but this is all we need to start.
Creating Your First Plugin File
Let’s create our plugin! Navigate to wp-content/plugins/ and create a new folder called hello-bar. Inside that folder, create a file called hello-bar.php.
Now, here’s the most important part: the plugin header. This is a special comment block at the very top of your main plugin file that tells WordPress, “Hey, I’m a plugin!”
Open hello-bar.php and add this:
<?php
/**
* Plugin Name: Hello Bar
* Plugin URI: https://yourwebsite.com/hello-bar
* Description: A simple notification bar that displays at the top of your website
* Version: 1.0.0
* Author: Taufik Hidayat
* Author URI: https://yourwebsite.com
* License: GPL v2 or later
* License URI: https://www.gnu.org/licenses/gpl-2.0.html
* Text Domain: hello-bar
*/
// If this file is called directly, abort.
if ( ! defined( 'WPINC' ) ) {
die;
}Let me break down what’s happening here:
- Plugin Name: This is what appears in the WordPress admin panel
- Description: A brief explanation of what your plugin does
- Version: Your plugin’s version number (useful for tracking updates)
- Author: That’s you!
- Text Domain: Used for translations (we’ll use ‘hello-bar’)
The last part (if ( ! defined( 'WPINC' ) )) is a security measure. It prevents people from accessing your plugin file directly by typing in the URL.
Now, save this file and go to your WordPress admin panel. Navigate to Plugins → Installed Plugins, and you should see your “Hello Bar” plugin listed! Go ahead and activate it.
Congratulations! You’ve just created a WordPress plugin. It doesn’t do anything yet, but it’s a real, valid plugin.
Understanding WordPress Hooks: The Foundation of Plugin Development
Here’s where things get interesting. WordPress uses a system called “hooks” that allows plugins to interact with WordPress core without modifying core files.
Think of hooks like electrical outlets in your house. WordPress has outlets (hooks) placed at strategic points throughout its code. Your plugin can “plug into” these outlets to run its own code at specific times.
There are two types of hooks:
1. Action Hooks — These let you run your own code at specific points during WordPress execution. For example, when WordPress is loading the header, or when a post is being saved.
2. Filter Hooks — These let you modify data before WordPress uses it. For example, you can modify the content of a post before it’s displayed, or change the text of a button.
Here’s a simple example:
// Action hook - runs your function at a specific point
add_action( 'wp_footer', 'my_custom_function' );
function my_custom_function() {
echo '<p>This appears in the footer!</p>';
}
// Filter hook - modifies data
add_filter( 'the_title', 'modify_post_title' );
function modify_post_title( $title ) {
return $title . ' - Read This!';
}The action hook adds content to the footer. The filter hook modifies every post title by adding ” - Read This!” at the end.
Building Our Hello Bar Plugin
Now let’s make our plugin actually do something. We’re going to create a notification bar that appears at the top of the website.
Add this code to your hello-bar.php file (below the security check):
/**
* Display the hello bar on the frontend
*/
function hb_display_bar() {
$message = 'Welcome to our website! Check out our latest posts.';
?>
<div id="hello-bar" style="background: #0073aa; color: white; padding: 15px; text-align: center; position: fixed; top: 0; left: 0; right: 0; z-index: 9999;">
<p style="margin: 0; padding: 0;"><?php echo esc_html( $message ); ?></p>
</div>
<style>
body { margin-top: 51px !important; }
</style>
<?php
}
add_action( 'wp_footer', 'hb_display_bar' );Save the file, refresh your website’s homepage, and boom! You should see a blue notification bar at the top of your page.
Let me explain what’s happening:
- We created a function called
hb_display_bar()(thehb_prefix is our namespace to avoid conflicts) - Inside the function, we output HTML for our notification bar
- We used
esc_html()to sanitize the message (always sanitize output for security!) - We hooked this function to
wp_footerusingadd_action(), so it runs when WordPress is building the footer
The inline CSS makes the bar fixed at the top and adds margin to the body so content doesn’t hide behind it.
Adding an Admin Settings Page
A hardcoded message is fine, but what if we want to change it without editing code? Let’s add an admin settings page!
Add this code to your plugin:
/**
* Add settings page to WordPress admin menu
*/
function hb_add_admin_menu() {
add_options_page(
'Hello Bar Settings', // Page title
'Hello Bar', // Menu title
'manage_options', // Capability required
'hello-bar', // Menu slug
'hb_settings_page' // Function that renders the page
);
}
add_action( 'admin_menu', 'hb_add_admin_menu' );
/**
* Render the settings page
*/
function hb_settings_page() {
?>
<div class="wrap">
<h1>Hello Bar Settings</h1>
<form method="post" action="options.php">
<?php
settings_fields( 'hb_settings_group' );
do_settings_sections( 'hello-bar' );
submit_button();
?>
</form>
</div>
<?php
}This code creates a new settings page under Settings → Hello Bar in your WordPress admin. The manage_options capability ensures only administrators can access it.
Saving Settings with the WordPress Options API
Now we need to register our settings so WordPress knows how to save them. Add this code:
/**
* Initialize plugin settings
*/
function hb_settings_init() {
// Register a setting
register_setting( 'hb_settings_group', 'hb_message' );
register_setting( 'hb_settings_group', 'hb_background_color' );
// Add a settings section
add_settings_section(
'hb_main_section',
'Main Settings',
'hb_section_callback',
'hello-bar'
);
// Add settings fields
add_settings_field(
'hb_message_field',
'Notification Message',
'hb_message_field_callback',
'hello-bar',
'hb_main_section'
);
add_settings_field(
'hb_background_color_field',
'Background Color',
'hb_background_color_field_callback',
'hello-bar',
'hb_main_section'
);
}
add_action( 'admin_init', 'hb_settings_init' );
/**
* Settings section description
*/
function hb_section_callback() {
echo '<p>Configure your notification bar settings below.</p>';
}
/**
* Message field HTML
*/
function hb_message_field_callback() {
$message = get_option( 'hb_message', 'Welcome to our website!' );
?>
<input type="text"
name="hb_message"
value="<?php echo esc_attr( $message ); ?>"
class="regular-text"
/>
<p class="description">Enter the message to display in the notification bar.</p>
<?php
}
/**
* Background color field HTML
*/
function hb_background_color_field_callback() {
$color = get_option( 'hb_background_color', '#0073aa' );
?>
<input type="color"
name="hb_background_color"
value="<?php echo esc_attr( $color ); ?>"
/>
<?php
}This uses the WordPress Settings API, which is the proper way to create settings pages. We’re registering two options:
hb_message— The notification texthb_background_color— The background color
The get_option() function retrieves saved values, with default values as the second parameter.
Updating the Frontend Display
Now let’s update our hb_display_bar() function to use these saved settings:
/**
* Display the hello bar on the frontend
*/
function hb_display_bar() {
$message = get_option( 'hb_message', 'Welcome to our website!' );
$bg_color = get_option( 'hb_background_color', '#0073aa' );
// Don't display if message is empty
if ( empty( $message ) ) {
return;
}
?>
<div id="hello-bar" style="background: <?php echo esc_attr( $bg_color ); ?>; color: white; padding: 15px; text-align: center; position: fixed; top: 0; left: 0; right: 0; z-index: 9999;">
<p style="margin: 0; padding: 0;"><?php echo esc_html( $message ); ?></p>
</div>
<style>
body { margin-top: 51px !important; }
</style>
<?php
}
add_action( 'wp_footer', 'hb_display_bar' );Now you can change the message and color from the WordPress admin panel! Try it out: go to Settings → Hello Bar, change the message and color, click “Save Changes”, and refresh your homepage.
Testing and Debugging Tips
As you develop your plugin, you’ll inevitably run into issues. Here are my go-to debugging techniques:
1. Enable WordPress Debug Mode
Edit your wp-config.php file and add:
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );This logs errors to wp-content/debug.log without displaying them on your site.
2. Use var_dump() and error_log()
// Quick and dirty debugging
var_dump( $some_variable );
// Better for production - writes to debug.log
error_log( print_r( $some_variable, true ) );3. Check Your Hooks
Make sure you’re using the right hooks. The WordPress Plugin API reference is your best friend.
4. Deactivate Other Plugins
If something’s not working, try deactivating other plugins to check for conflicts.
5. Use a Plugin Checker
Install the “Plugin Check” plugin from WordPress.org — it scans your plugin for common issues and best practices.
How to Package and Share Your Plugin
Once your plugin is working, you might want to share it with others or just keep a clean backup. Here’s how to package it:
1. Add a readme.txt file (optional but recommended):
=== Hello Bar ===
Contributors: taufikhidayat
Tags: notification, bar, announcement
Requires at least: 5.0
Tested up to: 6.4
Stable tag: 1.0.0
License: GPLv2 or later
A simple notification bar for your website.
== Description ==
Display a customizable notification bar at the top of your website.
== Installation ==
1. Upload the plugin files to `/wp-content/plugins/hello-bar/`
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Go to Settings > Hello Bar to configure
== Changelog ==
= 1.0.0 =
* Initial release2. Create a ZIP file:
Select your hello-bar folder and create a ZIP archive. This ZIP file can be uploaded to any WordPress site through Plugins → Add New → Upload Plugin.
3. If you want to share it on WordPress.org:
The WordPress.org plugin repository is free and gives your plugin credibility. You’ll need to:
- Create a WordPress.org account
- Submit your plugin for review
- Follow their coding standards and guidelines
The review process can take a few weeks, but it’s worth it if you want wide distribution.
Next Steps and Resources
Congratulations! You’ve just built a functional WordPress plugin. Here’s what you can do to level up:
Enhance Your Plugin:
- Add a close button with a cookie to remember closed state
- Create a display conditions system (show only on homepage, specific pages, etc.)
- Add animation effects when the bar appears
- Allow scheduling (show the bar between specific dates)
- Add button/CTA support with custom links
Learn More:
- WordPress Plugin Developer Handbook — The official guide
- WordPress Code Reference — Function and hook documentation
- WordPress Coding Standards — Write clean, professional code
Practice Projects: Try building these plugins to practice:
- Custom login page logo changer
- Disable comments site-wide
- Reading time calculator for posts
- Custom dashboard widget
- Simple contact form
Final Thoughts
When I built my first plugin, I made it way more complicated than it needed to be. I tried to add every feature I could think of, and I got overwhelmed.
Start small. Get something working. Then iterate.
The plugin we built today is simple, but it’s real and functional. You can install it on any WordPress site, and it’ll work. That’s powerful.
Every complex plugin you’ve ever used started with code similar to what we wrote today. The only difference is they kept building on top of the foundation.
Now it’s your turn. What will you build?
If you have questions or want to share what you’ve created, drop a comment below. I read and respond to every single one.
Happy coding!
— Taufik Hidayat