keepcalculator

06 Numbers and Powers

How to Create a WordPress Plugin from Scratch

Card No. 06·70652 · Updated · Standard formula, shown below

This guide walks you through building a WordPress plugin from the ground up, covering everything from setting up the main file to adding settings and shortcodes. You’ll learn the essential structure and best practices, and by the end you’ll have a working plugin you can extend for your own needs.

What You’ll Need

  • A WordPress site (local or hosted) where you can install plugins.
  • Access to the file system (FTP, cPanel, or local folder) to create plugin files.
  • A code editor (like VS Code, Sublime Text, or Notepad++).
  • Basic knowledge of PHP, HTML, and WordPress hooks.

Step-by-Step

  1. Plan your plugin. Decide what your plugin will do. For this guide, we’ll create a simple plugin that adds a custom dashboard widget and a shortcode to display a message.
  2. Create the plugin folder and main file. In wp-content/plugins/, create a folder named my-first-plugin. Inside it, create a file named my-first-plugin.php.
  3. Add the plugin header. Open the file and add the standard plugin header comment. This tells WordPress the plugin name, description, version, and author.
    /**
     * Plugin Name: My First Plugin
     * Description: A simple plugin that adds a dashboard widget and a shortcode.
     * Version: 1.0
     * Author: Your Name
     */
        
  4. Prevent direct access. Add a security check to stop people from accessing the file directly. This is a best practice.
    if ( ! defined( 'ABSPATH' ) ) {
        exit;
    }
        
  5. Define a constant for the plugin path (optional but useful). This makes it easier to reference files later.
    define( 'MFP_PLUGIN_URL', plugin_dir_url( __FILE__ ) );
        
  6. Create a dashboard widget. Use the wp_dashboard_setup action to register a widget. Add a function that outputs the widget content.
    function mfp_add_dashboard_widget() {
        wp_add_dashboard_widget(
            'mfp_dashboard_widget',
            'My Plugin Dashboard',
            'mfp_dashboard_widget_content'
        );
    }
    add_action( 'wp_dashboard_setup', 'mfp_add_dashboard_widget' );
    
    function mfp_dashboard_widget_content() {
        echo '<p>Hello from My First Plugin!</p>';
    }
        
  7. Add a shortcode. Shortcodes let users embed dynamic content in posts and pages. Register one with add_shortcode.
    function mfp_shortcode( $atts ) {
        $atts = shortcode_atts(
            array(
                'message' => 'Hello World!',
            ),
            $atts,
            'mfp'
        );
        return '<p>' . esc_html( $atts['message'] ) . '</p>';
    }
    add_shortcode( 'mfp', 'mfp_shortcode' );
        
  8. Activate the plugin. Go to your WordPress admin, navigate to Plugins, find “My First Plugin”, and click Activate.
  9. Test the shortcode. Create a new post or page, add the shortcode [mfp message="Custom message!"], and publish. You should see the message appear.
  10. Add a settings page (optional). To make the plugin more useful, add a settings page under the Settings menu. Use the admin_menu action and the Settings API.
    function mfp_add_settings_page() {
        add_options_page(
            'My Plugin Settings',
            'My Plugin',
            'manage_options',
            'mfp-settings',
            'mfp_render_settings_page'
        );
    }
    add_action( 'admin_menu', 'mfp_add_settings_page' );
    
    function mfp_render_settings_page() {
        ?>
        <div class="wrap">
            <h1>My Plugin Settings</h1>
            <form method="post" action="options.php">
                <?php settings_fields( 'mfp_settings_group' ); ?>
                <?php do_settings_sections( 'mfp-settings' ); ?>
                <?php submit_button(); ?>
            </form>
        </div>
        <?php
    }
        

    Then register the settings, fields, and sanitization callbacks as needed.

  11. Add an uninstall hook (optional but recommended). If your plugin stores options, clean them up on uninstall. Create an uninstall.php file in your plugin folder and delete the options.
    if ( ! defined( 'WP_UNINSTALL_PLUGIN' ) ) {
        exit;
    }
    delete_option( 'mfp_settings' );
        

Common Mistakes

  • Not using a unique prefix. Functions and variables with generic names (like init or $data) can conflict with other plugins or themes. Use a unique prefix like mfp_.
  • Direct file access. Forgetting the ABSPATH check leaves your plugin vulnerable to direct execution.
  • Not escaping output. Echoing user input without esc_html() or esc_attr() can lead to XSS vulnerabilities.
  • Hardcoding paths. Using hardcoded URLs or paths instead of plugin_dir_url() or plugin_dir_path() breaks when the site moves.
  • Calling hooks too early. Some hooks like init fire before others; make sure you use the right one for your task.

Tips

  • Use a local development environment like Local or XAMPP to test plugins safely.
  • Follow the WordPress Coding Standards for clean, consistent code.
  • Use register_activation_hook() to run setup tasks when the plugin is activated, like creating database tables.
  • Keep your plugin lightweight by loading scripts and styles only when needed (e.g., using wp_enqueue_script() with a conditional).
  • Test with a default theme (like Twenty Twenty-Four) to rule out theme conflicts.
  • Use version control (like Git) to track changes.

Troubleshooting

  • Plugin doesn’t activate. Check for PHP syntax errors by looking at the site’s error log. If you see a white screen, rename the plugin folder via FTP to disable it, then review your code.
  • Shortcode not working. Make sure you’re using the shortcode correctly: [mfp] or [mfp message="..."]. Also, ensure the plugin is active and the content is in a post or page, not a theme file.
  • Dashboard widget not showing. The widget only appears on the main dashboard page. Check that you’re on the right screen and that the function is hooked correctly.
  • Settings not saving. Verify that you’ve called register_setting() with the correct option group and that the form action is options.php. Also, check that the user has the manage_options capability.
  • Conflicts with other plugins. Deactivate other plugins one by one to isolate the issue. Also, try switching to a default theme.

Frequently Asked Questions

Do I need to know PHP to create a WordPress plugin?

Yes, basic PHP is essential. You can start with simple plugins and learn as you go, but you’ll need to understand variables, functions, and arrays at minimum.

Can I create a plugin without using FTP?

Yes, you can use the WordPress admin’s built-in plugin editor, but it’s risky because a syntax error can lock you out. A safer method is using FTP or a file manager in your hosting control panel.

How do I add custom database tables in my plugin?

Use the register_activation_hook() to run a function that creates the table with dbDelta(). Always check if the table exists first and use the $wpdb global.

What is the difference between a plugin and a theme?

A plugin adds functionality to WordPress, while a theme controls the design and layout. Plugins can be used with any theme, and themes can be changed without affecting plugin functionality.

How do I make my plugin translatable?

Use the load_plugin_textdomain() function and wrap strings in __() or _e(). Then create .po and .mo files for each language.

Is it safe to use free plugins from the WordPress repository?

Generally yes, but always check the plugin’s rating, last update, and number of active installs. Read reviews and ensure it’s compatible with your WordPress version.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →