Skip to content

How to build WordPress plugins for a live site

By SiteSelf

Published

A WordPress plugin can be one PHP file with a header, and you can write one in an afternoon. The harder part is making sure it works with the rest of the site, refuses changes from people who should not make them, and survives the next PHP update. This guide builds a small, real plugin and then covers the testing that decides whether it is safe to use.

Key takeaways

  • The WordPress Plugin Handbook only requires a PHP file with a Plugin Name header. Most real failures come later, from conflicts, version mismatches and code that worked locally but not on the live site.
  • Give every function, option and hook a distinctive prefix, check capabilities before writing anything, and follow the handbook’s order: sanitize input, validate it, escape output.
  • Log errors to wp-content/debug.log on staging rather than showing them on the page, then test the packaged ZIP against your real theme and plugins.
  • Code that calls removed functions such as create_function() fails on PHP 8.0 and later, so test on the lowest PHP version you claim to support and on the version your host is moving to.
  • The WordPress.org Plugins Team reviewed 12,713 plugins in 2025 and approved 69.5% of those that went through the process. There is no official average wait.

A clinic’s opening hours appear in the footer, on the contact page and on a landing page. Someone changes Friday’s hours in one place and forgets the other two. A small plugin can fix that with one saved schedule and a shortcode that shows it everywhere.

Writing that plugin is the easy part. WordPress’s Plugin Handbook says the minimum is a PHP file with a Plugin Name header. The work that takes time is everything after: making sure it does not collide with other plugins, only lets the right people change the hours, still runs after a PHP upgrade, and can be removed cleanly.

Do you need a custom plugin at all?

Often you don’t. If a maintained plugin covers most of the need, install it and extend it through its hooks rather than writing a replacement. Our guide on how to install a WordPress plugin safely covers what to check on a listing before you trust it. For new content types, such as a “Webinars” section that the marketing team fills in, CPT UI and Advanced Custom Fields usually do the job without any new code.

Build your own when the requirement really is specific to your business, such as an integration with your booking system or a pricing rule nobody else has. Before you start, decide who will keep it working. A custom plugin keeps costing time after launch, every time WordPress, PHP or WooCommerce changes. Practitioners on r/woocommerce make the same point about payment code: if one freelancer wrote it and only that freelancer understands it, the store depends on one person.

What you need before you write code

  • A disposable WordPress install. Use a local environment or a staging copy of the site, never a folder on the production server.
  • PHP and some HTML. PHP does the work. JavaScript only matters if you build blocks for the editor.
  • Git. Commit from the first working version so you can always get back to it.
  • A one-paragraph scope. For the clinic plugin: one schedule, editable by administrators, shown with [clinic_hours]. If no schedule has been saved, the shortcode shows nothing rather than invented hours. Booking and holiday calendars stay out.
  • The supported versions. Write down the lowest WordPress and PHP versions you will actually test. Only list a version if you can reproduce and fix failures on it.

How to build a working plugin, step by step

  1. Create the folder and main file. In wp-content/plugins, create clinic-hours/clinic-hours.php. WordPress.org expects the main file to match the folder name.
  2. Add the header and a direct-access guard. The header is what makes WordPress list the file on the Plugins screen.
<?php
/**
 * Plugin Name:       Clinic Hours
 * Description:       One opening-hours schedule, shown anywhere with [clinic_hours].
 * Version:           1.0.0
 * Requires at least: 6.5
 * Requires PHP:      7.4
 * License:           GPLv2 or later
 * Text Domain:       clinic-hours
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}
  1. Pick a prefix and use it everywhere. The handbook’s Best Practices page warns that generic global names collide with other plugins and themes. It also says wrapping functions in function_exists() doesn’t fix this in general, because your plugin still breaks if someone else’s function loads first. Use something distinctive, such as clhr_, or a PHP namespace.
  2. Register the shortcode on init and return the output. Shortcode callbacks must return their output. If they echo it, the content appears in the wrong place on the page.
function clhr_render_hours() {
    $hours = get_option( 'clhr_hours', '' );
    if ( '' === $hours ) {
        return '';
    }
    return '<div class="clhr-hours">' . nl2br( esc_html( $hours ) ) . '</div>';
}

function clhr_register_shortcode() {
    add_shortcode( 'clinic_hours', 'clhr_render_hours' );
}
add_action( 'init', 'clhr_register_shortcode' );
  1. Add a settings page through the Settings API. Put the menu on admin_menu and the setting on admin_init. Give the setting a sanitize callback, and make the page require a capability. manage_options is the usual choice for site-wide settings. If you are unsure which roles have which capability, see WordPress user roles explained.
function clhr_add_settings_page() {
    add_options_page( 'Opening hours', 'Opening hours', 'manage_options', 'clhr-hours', 'clhr_render_settings_page' );
}
add_action( 'admin_menu', 'clhr_add_settings_page' );

function clhr_register_settings() {
    register_setting( 'clhr_settings', 'clhr_hours', array(
        'type'              => 'string',
        'sanitize_callback' => 'sanitize_textarea_field',
        'default'           => '',
    ) );
}
add_action( 'admin_init', 'clhr_register_settings' );

function clhr_render_settings_page() {
    if ( ! current_user_can( 'manage_options' ) ) {
        return;
    }
    ?>
    <div class="wrap">
      <form method="post" action="options.php">
        <?php settings_fields( 'clhr_settings' ); ?>
        <label for="clhr_hours">Hours, one line per day</label>
        <textarea id="clhr_hours" name="clhr_hours" rows="7" class="large-text"><?php echo esc_textarea( get_option( 'clhr_hours', '' ) ); ?></textarea>
        <?php submit_button(); ?>
      </form>
    </div>
    <?php
}
WordPress plugin settings page with an opening hours textarea
A custom options screen registered under the Settings menu takes advantage of built-in save handling and nonce validation while leaving permission checks in your code. · Source: timscheman.com
  1. Handle the lifecycle on purpose. Use register_activation_hook() to set defaults without overwriting saved data. Put permanent cleanup in uninstall.php and guard it with WP_UNINSTALL_PLUGIN. Deactivating a plugin should never delete anyone’s settings.
<?php
// uninstall.php
if ( ! defined( 'WP_UNINSTALL_PLUGIN' ) ) {
    exit;
}
delete_option( 'clhr_hours' );

If your plugin registers a custom post type, flush the rewrite rules from the activation and deactivation hooks, as the handbook shows. A new post type that returns 404s right after activation usually has stale rewrite rules. The activation itself did not fail.

Which security rules apply to every plugin?

The Plugin Handbook’s Common Issues page, which collects what the review team rejects most often, gives the order: sanitize input early, validate it against what is actually allowed, and escape output when you render it. These steps don’t replace each other. Data that was sanitized when saved still gets esc_html(), esc_attr() or esc_url() when it is printed.

The Settings API handled the nonce and the save for you in step 5. Once you write your own handler, on admin-post.php, AJAX or a REST route, all of these checks are your job:

  • Check current_user_can() before changing anything. is_admin() only tells you the request is for an admin screen. It doesn’t tell you the user is an administrator.
  • Verify a nonce with check_admin_referer() or wp_verify_nonce(). A nonce stops forged requests but grants no permission by itself.
  • Give every REST route a real permission_callback.
  • Use $wpdb->prepare() whenever a query contains variables.

Test this directly. Log out, send the request yourself, and confirm nothing changed. Repeat as a logged-in Subscriber, then again with a bad nonce. Hiding the form proves nothing. If the handler returns 200 and saves anyway, the plugin is vulnerable.

How to test it before it reaches the live site

On your local or staging install, turn on logging and keep errors off the page. WordPress’s debugging handbook recommends this setup in wp-config.php:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Warnings now go to wp-content/debug.log. Read the log after activating the plugin, after saving the settings and after loading a page with the shortcode, even if everything looks fine. Turn logging off afterwards. A debug log left where the public can read it can expose sensitive information.

Then work through these checks:

  1. Run Plugin Check. The handbook describes it as a tool for testing whether your plugin meets the directory’s required standards. It runs most of the checks used on new submissions. It reads your code but never runs it, so a clean result does not mean the plugin works.
  2. Lint against the WordPress Coding Standards. Fix the errors and review the warnings rather than suppressing them.
  3. Test on a copy of the real site. A clean install doesn’t have your theme, cache or checkout plugins. Staging does. Turn off real emails and payments on the copy first.
  4. Test the ZIP, not your source folder. Build it, install it on a clean site, and open the archive to make sure there are no .env files or credentials in it and no built assets missing.
  5. Test the lowest PHP version you claim to support, then record the versions you actually tested in the readme.

Extra rules for WooCommerce plugins

If your code touches orders, use WooCommerce’s CRUD methods such as wc_get_order() rather than get_post(). That way it works with High-Performance Order Storage (HPOS), WooCommerce’s dedicated order tables. WooCommerce’s HPOS recipe book covers the details. Test with HPOS turned on before you declare compatibility. A compatibility declaration you haven’t tested hides the warning a store owner would otherwise see.

What a correct result looks like

The plugin activates with nothing new in debug.log. The Opening hours page appears under Settings for administrators and is refused for Editors. If you change the hours once, every page with [clinic_hours] shows the new schedule, and pages without the shortcode don’t change. When you deactivate the plugin, the hours disappear and the rest of the layout stays intact. Deleting the plugin removes its option, and nothing else.

What to do when the plugin breaks the site

If you see a critical error or a white screen, use the Recovery Mode link WordPress emails you if one arrives. If you are locked out, rename the plugin’s folder in wp-content/plugins over SFTP or your host’s file manager. WordPress deactivates it on the next load. Then read the log. The PHP message and file path tell you far more than “there has been a critical error”.

The most common causes, roughly in the order they show up in support forums:

  • A conflict with another plugin or the theme. Reproduce it on staging, or use the Health Check plugin’s troubleshooting mode, which turns off plugins and switches the theme only for your session. Then turn plugins back on one at a time and repeat the exact action that failed. Some conflicts only show up during checkout, for example. Our guide to fixing plugins that are not working walks through this.
  • A version mismatch. In a 2026 wordpress.org thread, a site owner’s move from PHP 8.3 to 8.5 was blocked by create_function(), which was deprecated in PHP 7.2 and removed in 8.0. The fix was a development release from the plugin’s author. The reverse happens too: code calls a recent core function on an older WordPress install.
  • Local and live are different. One developer on the wordpress.org forums wrote a payment gateway that ran fine locally and white-screened the live site. The cause was how a callback was named. This is why you test on a copy of production and not only on your laptop.
  • Memory exhaustion. Before you raise WP_MEMORY_LIMIT, find the query or loop that is using the memory. A higher limit hides the fault without fixing it.

Stop and get help if the failure only happens on the live store, if it involves payments or orders, or if you can’t reproduce it on staging. Then the question is no longer about code. It is about protecting revenue while you work. If you would rather describe the feature and have it built and checked on your existing site, that is the work SiteSelf’s custom development covers. It needs hosting (SSH) access for code changes.

WordPress critical error screen after a plugin fails
WordPress displays a vague critical error notice to visitors, concealing the specific file paths and PHP errors needed to pinpoint the failure. · Source: wordpress.org

Frequently asked questions

Can ChatGPT or another AI tool write a WordPress plugin?

It can write a first draft in minutes, and for a small plugin on one site that draft is often a reasonable start. What the AI tool won’t do is test the plugin against your theme, your plugins and your PHP version, or check that the permission checks really refuse the wrong users. Treat generated code as something to review line by line and test on staging, not as finished work.

How long does WordPress.org plugin review take?

The Plugin Developer FAQ says there is no official average. The Plugins Team reported reviewing 12,713 plugins in 2025, with a 69.5% approval rate among submissions that went through the process. Packaging mistakes, such as an archive that is not a real ZIP, are a common reason for avoidable rejections.

Do I have to publish my plugin on WordPress.org?

No. A plugin for one site can stay private, and you can upload it as a ZIP from Plugins, then Add New. Publishing on WordPress.org means a GPL-compatible license and passing review. It also means supporting users whose sites look nothing like yours.

Should I use a custom database table?

Usually not for settings. One prefixed option is simpler and is removed cleanly on uninstall. Use a table when you store many records that need their own queries and indexes, and plan the migrations so an interrupted upgrade can safely run again.

How do I declare that my plugin needs another plugin?

Add the Requires Plugins header, which the Plugin Handbook supports. The header doesn’t guarantee the dependency is active or working, so check for it after plugins have loaded and before you call its functions.

Give your WordPress site its first task.

Connect the site you already have, add your agent to Slack or Telegram, and tell it what you need.

Connect your site

Start with 2,500 free credits. No credit card needed.