It's also good practice for the name to reflect what the plugin actually does. For example, you wouldn't want to name a forum plugin “Joe's Plugin” because that doesn't tell potential users anything about what your plugin does.
You also need to consider whether your plugin name is too generic. It's possible that the name has already been taken by another plugin developer. You can check existing plugins in the WordPress Plugin Directory (https://wordpress.org/plugins).
Because there are thousands of existing plugins, some developers prefix their plugin name with their business name. For example, if your business name is “Super Duper,” you might name a potential forum plugin “Super Duper Forums.” This allows you to better attach your brand to your plugin and keep the name unique.
Using a Folder
While WordPress does allow plugins to be a single file, it is generally not good practice to use this method. Instead, it is standard practice to use a folder to contain your plugin. The vast majority of plugins will contain multiple files, such as PHP files, CSS and JavaScript assets, and other build files.
When creating a plugin, it should ideally match your plugin name. Plugin folder names should be hyphenated and lowercase. It should not contain spaces, underscores, uppercase letters, or nonalphanumeric characters. The plugin folder name must also match the plugin text domain when preparing your plugin for translations (see Chapter 11, “Internationalization”) if you plan to submit it to the official plugin repository.
Using the previous “Super Duper Forums” plugin as an example, its folder name should be super‐duper‐forums.
BEST PRACTICES
With any code base, developers should follow a common set of best practices. This is no different with WordPress plugins. By strictly following the practices laid out in this section, you'll have a solid foundation for your plugin. You'll also learn how to organize your plugin files and subfolders.
Namespace Everything
If you have a function named get_post(), it will conflict with WordPress’ own get_post() function and result in a fatal error. That's not a good user experience. Writing good code means making sure that your code doesn't conflict with other developers' code. The best way to ensure that is to prefix or namespace all your classes, functions, and anything else within the global namespace.
Throughout most of WordPress’ existence, it has supported versions of PHP versions earlier than 5.3, which is the version of PHP that standardized namespaces. This meant that it was standard practice to use a faux namespace by prefixing classes and functions. Prefixes should be unique to the plugin. The WordPress coding standards recommend naming classes and functions using snake case. Therefore, a function named get_post() would become prefix_get_post(), and a class named Post would become Prefix_Post.
WordPress 5.2 changed its minimum PHP requirements to PHP 5.6. This means that plugin authors who want to support the same PHP versions as WordPress are no longer tied to the old practice of using prefixes. For this reason, it's probably best to look at other standards for naming, such as those outlined in the PHP‐FIG standards (https://www.php-fig.org).
For the purposes of this book, the recommendation for namespacing your code will be to use the built‐in method of namespacing in PHP. Namespaces allow you to group your code under a unique name so that it doesn't conflict with other developers' code. Using the “Super Duper Forums” plugin example, your namespace would be called SuperDuperForums.
Namespaces must be the first code, excluding the opening <?php tag and inline comments, in a PHP file. In the following example, see how a custom class named Setup is handled. Because it is under the SuperDuperForums namespace, there's no need to prefix it.
<?php namespace SuperDuperForums; class Setup { public function boot() {} }
Class and function names are not the only consideration when namespacing code. There are other times when you'll have things in the global namespace that might conflict with other plugins running in WordPress. Such cases may include storing options in the database (see Chapter 3, “Dashboard and Settings”) or loading a JavaScript file (see Chapter 6, “JavaScript”). In such cases, it's generally best practice to prefix option names with your plugin name, such as super_duper_forums_ option_name, and prefix script handles similarly, such as super‐duper‐forums‐ script‐name.
You may have noticed that the option name used snake case (underscores) and the script handled used kebab case (hyphenated) in the previous example. The difference in practice has arisen over the years and can be confusing to new plugin developers. In general, anything referred to as a handle is in kebab case, and everything else is in snake case. Often such differences are superficial and not overly important. When in doubt, stick with snake case, and you'll be alright.
File Organization
When building your plugin, it's important to think about how your files should be organized. While you can change some things around later, getting started with a solid structure will make it easier to build out the plugin's features in the long run.
The most important and only required file for any plugin to have is its primary PHP file. This file can be named anything and must sit in the root of your plugin folder. If your primary file is named plugin.php, it will be located at /super‐duper‐forums/plugin.php.
There are two common practices for naming the primary plugin file. Many plugin authors name this file the same as the folder, such as super‐duper‐forums.php. The less‐common practice is to simply name this plugin.php. You may decide to choose something else entirely. Over time as you develop plugins, you'll likely want to have a standard naming scheme that best suits you or your team.
In modern plugin development, you'll most likely have JavaScript build tools, config files, and all sorts of other files that take up space in the root of your plugin folder. Putting all your plugin files in the root will likely clutter things and make it hard to find things. It's best to only keep your primary plugin file in the root and all other plugin code within subfolders. The exception to this rule would be the uninstall.php file (see the “Uninstall.php” section later in this chapter).
Folder Structure
In professional development, it's important to create a folder structure that is understandable at a glance and easy to maintain. Most plugin developers will create separate folders to house their PHP code apart from resources, assets, or other front‐end code in a folder with a name such as /src, /inc, /includes, or /app. Within the larger PHP development community, it is standard practice to name this folder /src because this is the folder where your “source” code lives.
The naming of the assets or resources folder is also varied with plugins. Often this folder is named /assets, /dist, or /public. Most likely, you'll want to have separate development and production folders if you use a build system such as webpack to bundle your final asset files.
