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
- 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.
- Create the plugin folder and main file. In
wp-content/plugins/, create a folder namedmy-first-plugin. Inside it, create a file namedmy-first-plugin.php. - 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 */ - Prevent direct access. Add a security check to stop people from accessing the file directly. This is a best practice.
if ( ! defined( 'ABSPATH' ) ) { exit; } - 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__ ) ); - Create a dashboard widget. Use the
wp_dashboard_setupaction 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>'; } - 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' ); - Activate the plugin. Go to your WordPress admin, navigate to Plugins, find “My First Plugin”, and click Activate.
- Test the shortcode. Create a new post or page, add the shortcode
[mfp message="Custom message!"], and publish. You should see the message appear. - Add a settings page (optional). To make the plugin more useful, add a settings page under the Settings menu. Use the
admin_menuaction 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.
- Add an uninstall hook (optional but recommended). If your plugin stores options, clean them up on uninstall. Create an
uninstall.phpfile 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
initor$data) can conflict with other plugins or themes. Use a unique prefix likemfp_. - Direct file access. Forgetting the
ABSPATHcheck leaves your plugin vulnerable to direct execution. - Not escaping output. Echoing user input without
esc_html()oresc_attr()can lead to XSS vulnerabilities. - Hardcoding paths. Using hardcoded URLs or paths instead of
plugin_dir_url()orplugin_dir_path()breaks when the site moves. - Calling hooks too early. Some hooks like
initfire 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 isoptions.php. Also, check that the user has themanage_optionscapability. - 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
- Microsoft Surface Duo: The Foldable Phone Story
- Samsung SM-T813 Hard Reset: Step-by-Step Guide
- Best KVM VPS Hosting: Top Picks & Guide
- Mafia Clash Codes: Real Meanings & Usage
- Remove Programs from Mac: Full Uninstall Guide
- Project Sentinel Morning Digest: Data Stack Failure Alerts