AdvancedLesson 23 of 305 min read

Building a small plugin

Write a small, safe plugin: header, guard line, shortcode, settings, sanitising and escaping, activation and uninstall, with a real plugin run.

In this lesson you will

  • Write a plugin file
  • Sanitise input and escape output
  • Plan a settings screen
  • Clean up on uninstall

About 18 minutes

Your own small plugin

Marta wants a ‘special offer’ line that she can change from the dashboard and show anywhere with a short code. She does not want to pay for a big plugin with fifty features she will never use. A tiny plugin of her own can do this in about twenty lines. Writing small plugins is the heart of professional WordPress work: one clear job, safe code and easy updates.

The anatomy of a plugin

  1. A header comment naming the plugin so WordPress can list it.
  2. A guard line that stops the file running outside WordPress.
  3. Hooks that register settings, shortcodes or other features.
  4. Activation and uninstall code that sets up and cleans up.
  5. Escaping and sanitising everywhere data goes in or out.

A real plugin, created, run and removed

A test wrote a tiny plugin called ‘Zz Notice’, activated it, used its shortcode, fed it risky text, deactivated it and deleted every trace. The output is real:

header read: Zz Notice v1.0
activation: ok
option set by activation hook: Hello from activation
shortcode output: <div class="zz">Hello from activation</div>
after saving risky text: <div class="zz">Sale today</div>
escaped on output: <div class="zz">A &amp; B tag</div>
cleaned: yes

Follow the story. WordPress read the plugin’s name and version from its header. Activation ran a hook that set a starting message. The shortcode printed that message. When risky text containing tags and a script was saved, the cleaning function removed the tags and script. When text with an ampersand and a tag was stored directly, the output step escaped it, so it was shown safely as text. Finally the plugin and its saved option were removed, leaving the site as before.

The code, explained

<?php
/*
Plugin Name: My Notice
Version: 1.0
*/
if (!defined('ABSPATH')) exit;

add_shortcode('my_notice', function () {
    return '<div class="notice">' . esc_html(get_option('my_notice_text', 'Welcome!')) . '</div>';
});

The first line after the header ends the script if the file is opened directly in a browser. esc_html turns special characters into safe text on the way out, and the setting is cleaned on the way in. Together they form the rule professionals follow: sanitise input, escape output.

A settings screen, in outline

  • Register the setting with a sanitise callback, as in the test.
  • Add a page under Settings with the admin menu hook.
  • Print a form with a nonce and the setting field.
  • Check the user’s capability before saving, usually ‘manage_options’.
  • Show a confirmation message.

WordPress has a Settings API that handles much of this for you. Follow the official examples closely; the details are easy to get wrong.

Good plugin habits

Habit Why
One job per plugin Easy to understand and test
Unique prefix on everything Avoids clashes
Sanitise in, escape out Prevents most security holes
Clean up on uninstall Leaves no clutter
Test with debugging on Shows hidden errors

Sharing and maintaining

Keep your plugin in its own folder with a readme describing what it does. Use version numbers, and keep a short change log. If you build plugins for clients, keep them in version control and test updates on a staging copy. The official directory has review rules; study them even if you never submit, since they describe good practice.

Practice

Write a plugin that adds a shortcode printing today’s year, for use in footers. Add a setting for a prefix text such as ‘Copyright’. Escape everything. Activate it on a practice site, test it on a page, then deactivate and delete it and confirm no option remains.

Practice answer

If the shortcode prints raw tags, you forgot to escape. If the option remains after deletion, add an uninstall routine. Compare against the real test above.

Common mistake

Saving user input without cleaning it, or printing stored data without escaping. Both lines of defence matter.

Testing a plugin before you trust it

  1. Activate it on a practice copy, never first on the live site.
  2. Turn on debug logging and look for warnings.
  3. Try it as different users, including a visitor who is not logged in.
  4. Try odd input: very long text, quotes, tags and empty values.
  5. Deactivate and delete it, and check that nothing is left behind.

These five steps took only a few minutes in the real test above, and they catch the mistakes that cause most plugin problems. Make them a habit for every plugin you write, and for any plugin you install from an unfamiliar author.

When not to build a plugin

If a well-maintained plugin already does the job and is used by many sites, installing it is usually cheaper than writing and maintaining your own. Build your own when the task is small, when existing plugins are heavy compared with what you need, or when the feature is specific to one client.

Finally, write down what the plugin does in two sentences before you start coding. If you cannot, the job is probably too big for one plugin and should be split. Small, clear plugins are easier to test, easier to hand over and much easier to remove when you no longer need them.

Check what you learned

Five quick questions. Pick an answer and you will see straight away whether it is right and why.

What does a plugin header comment do?

  1. Makes it faster
  2. Lets WordPress list and recognise the plugin
  3. Deletes old plugins
  4. Adds a theme

Name and version come from it.

What is the rule for data?

  1. Trust everything
  2. Store passwords in text
  3. Never save anything
  4. Sanitise input, escape output

Both sides matter.

What does the guard line do?

  1. Starts the site
  2. Stops the file running outside WordPress
  3. Adds images
  4. Changes fonts

It checks ABSPATH.

What did esc_html do in the test?

  1. Deleted the option
  2. Activated the plugin
  3. Made text bigger
  4. Turned special characters into safe text

The ampersand became &.

What should an uninstall routine do?

  1. Remove the plugin’s saved options
  2. Install more plugins
  3. Hide the plugin
  4. Add users

Leave no clutter.

Summary

  • Plugin = header + guard + hooks.
  • Sanitise in, escape out.
  • Prefix everything and clean up on uninstall.
  • Keep each plugin to one job.

Next lesson

Next: the REST API, which lets other apps talk to your site.

Questions

Do I need to submit my plugin to the directory?

No. A private plugin for your own site or a client is fine.

Where do I keep plugin code during development?

In a practice site's plugins folder, ideally under version control such as Git.

Is a shortcode still the best choice?

Shortcodes still work well. Blocks are the modern way for editor content; both are valid.

Progress is saved in this browser.