If you attended my WordCamp Phoenix 2018 talk Building Your First Plugin – A Complete Newbie’s Guide to Creating a Plugin thank you! It should be fairly obvious that a 45 minute WordCamp talk won’t have all the information you need to build a plugin. It’s a massive topic, so that is why I’m writing this blog post. It will serve as a resource for you to refer back to as you continue learning and improve your skills.
When the video from the talk is available on WordPress.tv, I’ll add it here.
You can view the slides from the talk by clicking here.
Demo Plugin
The plugin we developed in the talk is hosted on GitHub, and you can download it any time.
After you download it, you can install it on a WordPress site just like any other plugin. Alternatively, unzip it on your computer, and edit the source files with your favorite text editor.
Text Editors
Speaking of text editors, here are some recommendations if you aren’t sure which one to use:
- For a casual user, you can use the built in Notepad (Windows) or TextEdit (Mac) text editor. They will work fine, but are limited in terms of features, and don’t have tools to assist your development.
- Note: TextEdit must be set to “Plain Text” in the Format menu to work.
- Notepad++ is a good, free and open source text editor for Windows users.
- Atom is another great free and open source program. It will work on Mac, Windows, and Linux computers.
- Sublime Text can be evaluated for free, but ultimately needs a paid license for continued use. However, licenses are a one-time fee per-user and not per-machine so you can use it on as many computers as you want.
- Visual Studio Code is free and open source, and available on Mac, Windows, and Linux computers.
- PHPStorm is a paid option, but it has a lot of nice features in a clean interface. There is a free license available for use on non-commercial open source projects, students, teachers, etc.
- Other editors are available, and it doesn’t hurt to try several. The right one for you will be the one that improves your workflow, and makes your code easier to read and write.
When Should You Code Your Own Plugin?
In the talk, I mentioned that many online tutorials will tell you to put some code in your theme’s functions.php file. While technically, this will work, they often times don’t mention the dangers of putting code in that file.
- You will lose your custom code whenever updating your theme.
- If you put your custom code in your child theme’s functions.php you won’t lose your code when the parent theme gets updated.
- However, if you ever change themes, the custom code will be in the old theme’s functions.php file and won’t carry over to the new theme.
If the change that the code is making is specific to your current theme, then the “danger” about changing themes isn’t much of a concern. For example, if you need to change the appearance of your current theme’s header, chances are this change won’t be necessary in the next theme you use. Losing this change when switching themes isn’t a concern, and is probably the desired outcome anyway.
If the code is not specific to your current theme, put it in a custom plugin. You will also be able to troubleshoot problems easier if each custom plugin does one specific thing.
Best Practices For Coding A Plugin
I’ll always recommend following the WordPress coding standards, and utilizing the built in WordPress functions. You can learn a lot by reading the documentation that WordPress has available.
Those sites have a lot of documentation on WordPress specific functions, that are useful for building a plugin. If you see something in the demo plugin that you’re unsure of, check out the documentation, chances are there’s something about it in there.
Development Environment
Built into WordPress is an editor that you can use to edit a plugin’s code (Plugins > Editor). I highly recommend against using this though. If you were to make an error in your code and save it, it could cause your entire site to stop working. This includes the editor page where you made the change, so you wouldn’t be able to undo the change easily.
Instead, make your changes on a development site. There are several options for development sites.
- Use your host’s staging environment if available. Many hosts offer a staging environment, which is basically a copy of your live site. You can make whatever changes you want to the staging site, and it won’t affect your live site. You can usually merge those changes to your live site with the push of a button.
- Hosts with staging environments: WPEngine, Liquid Web, SiteGround, FlyWheel, GoDaddy. There are others, just be sure to check if it’s available in the hosting plan’s features.
- Use a local development site on your computer. I really like Desktop Server, because it’s free for up to three sites. Plenty for development purposes. The paid version has additional features, which are pretty handy as well. There is also XAMPP, MAMP, and Local By Flywheel.
- Finally, you can also use a separate website. There are inexpensive hosting plans for a few dollars per month that you can use to play around. The worst case scenario is that you break the site. Since it is only serving as a development environment anyway just delete it and start over.
Debugging
On your development site, you should open your wp-config.php file and find the line define( 'WP_DEBUG', false ); and change it to true define( 'WP_DEBUG', true );. WP_DEBUG set to true will allow you to see any errors on your site that would otherwise be suppressed. It’s important that you don’t use this on a live site, though as it could expose security vulnerabilities to your site’s visitors.
There are also plugins that can help with debugging.
- Query Monitor: can help identify which plugin or theme is causing an error.
- Debug Bar: adds a debug menu to the admin bar that shows query, cache, and other helpful debugging information.
- Kint Debugger: a debugging tool to output information about variables and traces in a styled, collapsible format that makes understanding deep arrays and objects easier.
- User Switching: allows you to switch between user accounts. Useful for situations where your plugin behaves differently for different users (membership area, role based output, etc.).
Required Information in Plugins
Every plugin must have the following:
- Its own folder – technically this isn’t “required”, but it is useful for organizing if the plugin will have more than one file. The Hello Dolly plugin, for example, is just a single PHP file. (Side note, if you want some laughs then read the 1-star reviews of Hello Dolly).
- A PHP file with a header comment.
- Note, the very first characters in a PHP file must be
<?php - Your header comment must contain, at a minimum, the plugin’s name. Other than that nothing else is required, however there are plenty of highly recommended things to add.
- Note, the very first characters in a PHP file must be
Header Comment
- Plugin Name: This name is required and should be unique. If you name your plugin WooCommerce (or the same as any other plugin on WordPress.org), you will get an update notice eventually. This will cause the other plugin to replace yours.
- Plugin URL: The homepage of the plugin – can’t use WordPress.org URL
- Description: A short description, which is shown on the Plugins page in WP Admin. Keep under 140 characters.
- Version: 1.0, 1.1, etc. This helps keep track of changes, and lets people know there is a new version available.
- Author: The name of the author, or a comma separated list of author names if more than one
- Author URL: The author’s website
- License: The name of the license that the plugin is distributed under (e.g. GPL2)
- License URL: A link to the license text
- Text Domain: A common string that denotes all text belonging to your plugin. This makes it easier to translate your plugin later on. If you’re building it for yourself and not distributing it, this isn’t necessary.
- Domain Path: The location of your language translation files.
Plugin Code
The rest of the code is completely up to you. Often times developers will post code examples online to help people solve a problem. Search through this site, and you’ll find a few of those code examples. In many cases you can copy and paste the code into your own plugin and it will work just fine. You can also try your hand at coding something from scratch.
Here are a few sites that I’ve learned from, or have useful tutorials:
- Codecademy: Learn to program in PHP, which is required for making your own plugins. Also available are HTML & CSS and JavaScript courses, which can be useful.
- Pippin Williamson / Pippin’s Plugins: This site used to have a paid membership to access many of the tutorials. Pippin has since opened up all of the tutorials to anyone for free! Noteworthy tutorials: Introduction to WordPress Plugin Development 101, and Writing Your First WordPress Plugins, Basic to Advanced.
- Tom McFarlin: This is a paid membership site, but I believe there are a few free tutorials still available too.
- WPBeginner: WPBeginner has tons of great information for people who are just getting started using WordPress. They also have some tutorials that show how to solve certain problems with code examples.
- Tuts Plus: This site has all sorts of tutorials, which are not strictly WordPress related.
- Carrie Dils: Many of the tutorials here are Genesis Framework (theme) related, however there are some that dip into plugin territory. She does a great job explaining when something belongs in a theme vs a plugin in this post.
- WPMUDEV: This site is sort of a mix of theme and plugin reviews, opinion pieces, and code examples.
- Scott DeLuzio: I’d be remiss to leave out my own Intro to WordPress Plugin Development tutorial series ????.
nice article found it very informative
nice article about plugin