My First WordPress Plugin: What I Learned Along the Way

rmeow — Tue, 07 Apr 2026 14:35:28 +0000

Hi there! 👋

I'm not a WordPress expert. Actually, I'm pretty new to plugin development. But recently I decided to build my first plugin and submit it to WordPress.org — and wow, I learned a lot more than I expected.

Here's what the process taught me. Hopefully it helps someone else starting out.

How It Started

I run a small website called CalHolidays — basically a free holiday calendar with countdown widgets for days until Easter, Mother's Day, Father's Day, and so on.

People kept asking me: "Can I add these countdowns to my own website?"

Technically, yes — I had iframe embed codes. But for WordPress users, that's not ideal. They wanted something simpler. Something they could just drag into their sidebar, configure in two clicks, and forget about.

So I thought: why not make a WordPress plugin?

What I Built (Spoiler: It's Simple)

The plugin is straightforward:

Adds a Holiday Countdown Widget to WordPress
Users select a holiday (Easter, Mother's Day, Father's Day)
Widget shows "X days until [holiday]"
Auto-updates every year — no maintenance needed

It's not revolutionary. But it solves a real problem for my users.

The Development Process

Here's roughly what I did, and what I wish I knew earlier.

1. Plugin Structure Is Simpler Than I Thought

I expected WordPress plugins to be complex. But the minimum structure is surprisingly minimal:

holiday-countdown-widget/
├── holiday-countdown-widget.php    (main file)
├── readme.txt                       (for WordPress.org)
├── LICENSE                          (GPL v2 required)
├── css/
│   └── styles.css
└── assets/
    ├── icon-256x256.png
    └── screenshots...

The main PHP file handles:

Widget registration (using WP_Widget class)
Shortcode registration ([holiday_countdown])
Enqueueing CSS

2. WordPress.org Submission Has Rules

This is where I got surprised — twice.

First rejection: My readme.txt said "Tested up to: 6.5" but WordPress wanted 6.9 (current version).

Second rejection: I updated readme.txt to 6.9, but forgot to update the same value in my PHP file header. They must match.

Lesson: Keep readme.txt and PHP header synchronized. WordPress checks both.

3. Plugin Check Plugin (Yes, That's Its Name)

There's a plugin called Plugin Check that scans your plugin before submission.

Run it locally. It catches issues like:

Missing LICENSE file
Incorrect headers
Code quality problems

I didn't use it initially. Now I wish I did.

4. Screenshots and Icons Matter

WordPress.org requires:

Plugin icon (256x256 PNG)
Screenshots showing your plugin working

I created these using SVG → PNG conversion. Not fancy, but they show the plugin is real and functional.

What I Learned

Here's my takeaway list for anyone building their first plugin:

Before you start:

✅ Read the Plugin Developer Guidelines
✅ Study an existing simple plugin's structure
✅ Set up a local WordPress test environment

During development:

✅ Keep your plugin simple — don't over-engineer
✅ Use WordPress APIs (Widget API, Shortcode API) instead of reinventing
✅ Test with WP_DEBUG enabled

Before submission:

✅ Run Plugin Check plugin
✅ Make sure readme.txt and PHP headers match
✅ Include GPL v2 LICENSE file
✅ Add proper screenshots and icon

After submission:

✅ Be patient — review takes 1-7 days
✅ If rejected, read the feedback carefully and fix exactly what they ask
✅ The review team is helpful, not scary

Where Things Stand Now

My plugin is currently awaiting review. 🤞

If approved, it'll be available at wordpress.org/plugins/holiday-countdown-widget — and CalHolidays users will have an easier way to embed countdowns.

For me, this was a learning experience more than anything. I'm not claiming to be an expert now — but I understand WordPress plugins a lot better than before.

Final Thoughts

If you're thinking about building a WordPress plugin:

Just start.

Pick a simple problem. Build a simple solution. Submit it. Learn from the feedback.

You don't need to be a senior developer. You just need patience and willingness to read documentation.

Feel free to ask questions in the comments. I'm still learning, but happy to share what I've picked up along the way.

Resources I found helpful:

WordPress Plugin Developer Handbook
Plugin Check Plugin
readme.txt Validator
CalHolidays Countdown Widgets — what inspired this project

Thanks for reading! If this helped you, drop a comment or follow me here. I'll update when the plugin gets approved (or if I learn something new from the review process).

DEV Community: rmeow