Professional WordPress Plugin Development. Brad Williams
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.
The following is an example of how a plugin folder structure may be organized. Some of the files in this list are covered later in this chapter.
plugin.php: Primary plugin file
uninstall.php: Uninstall file
/src: PHP source codeActivator.php: Activation classDeactivator.php: Deactivation classPlugin.php: Primary plugin class
/resources: Development asset files
/css: Development CSS/js: Development JavaScript
/public: Production asset files/css: Production CSS/js: Production JavaScript
This is a clean structure that will help you maintain your plugin code over time. You may choose a different structure for your own projects.
NOTE The most important thing is consistency. In a professional environment, more than one developer will often be working on code, so it's important that your team understands where to find and edit code.
When using namespaces as described in the “Namespace Everything” section of this chapter, it is standard practice to have a folder structure that matches how your namespaces and subnamespaces are set up so that it is easy to autoload the files using a system that follows the PHP‐FIG autoloading standard (https://www.php-fig.org/psr/psr-4).
With a fully qualified class name of PDEV\Post\Edit, you'd have the following structure within your /src folder:
/Post: SubnamespaceEdit.php: Class file
Following this structure will tie your code and namespace structure directly to your folder structure. It makes it simple for you and other developers to navigate your project's files and folders by just looking at the namespace and class name.
This is the standard used by the larger PHP community and has been for many years. Much of the WordPress community is still light‐years behind in following this standard, but it is beginning to catch on with more and more plugin developers.
PLUGIN HEADER
For WordPress to recognize a plugin, the plugin's primary PHP file must have what's called a plugin header at the top of the file. This tells WordPress that this particular file is the file that it must load to your plugin. WordPress plugins can be and do anything, but this is the only hard requirement for a plugin to function.
Creating the Header
The plugin header is nothing more than a normal PHP inline code comment with some special formatting that WordPress can recognize. The following is an example of a plugin header:
<?php /** * Plugin Name: My Plugin * Plugin URI: https://example.com/plugins/pdev * Description: A short description of the plugin. * Version: 1.0.0 * Requires at least: 5.3 * Requires PHP: 5.6 * Author: John Doe * Author URI: https://example.com * License: GPL v2 or later * License URI: https://www.gnu.org/licenses/gpl-2.0.html * Text Domain: pdev * Domain Path: /public/lang */
Each line is called a header file and provides some info to WordPress about your plugin. The only required field for the plugin to work is the Plugin Name field. Each field should be straightforward to understand. The following is a brief description of what each field sets:
Plugin Name: The name for your plugin
Plugin URI: A URI with more information about your plugin
Description: A brief summary that describes what your plugin does
Version: The current version of your plugin, which should be incremented with each update
Requires at least: The minimum version of WordPress required for your plugin to work
Requires PHP: The minimum version of PHP required for your plugin to work
Author: Your or your team/business name
Author URI: The link to your website
License: The license that the plugin is distributed under
License URI: A link to the full text of the license
Text Domain: The text domain used for internationalizing your plugin (see Chapter 11 for more information)
Domain Path: The relative path to where translation files are located in your plugin
Network: An optional field that