Professional WordPress Plugin Development. Brad Williams

to true for plugins that can only be activated across the entire network on a multisite installation

      Plugin License

      When distributing your plugin to others, it's important to have a clear license so that you both protect your own copyright and make sure anyone who receives your plugin has a clear understanding of what their rights are. WordPress is licensed under the GNU General Public License (GPL), version 2 or later. Any plugins distributed should use a license that is compatible with the GPL.

      The GPL recommends placing the following copyright notice in every source file for your plugin. However, most plugins only place this after the plugin header in the primary plugin file.

<?php /* Copyright (C) <year> <name of author> This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */

      You need to replace the <year> and <name of author> snippets in that notice with the year the code was created and your name. Once you add the notification to your plugin file(s), it will then be licensed under the GPL.

      If working with a client or employer and not distributing the plugin to the public in any way, your plugin may not need a license. Copyright and/or license should be determined by your contract and what you and your client/employer agree to.

DETERMINING PATHS

      Perhaps one of the toughest hurdles to jump when building WordPress plugins is simply figuring out the appropriate path when loading or referencing a file. Because you as a plugin developer do not control how the user chooses to set up their WordPress installation, you cannot rely on a specific pattern.

      Plugin Paths

      There are two types of paths that you might be concerned with when building WordPress plugins. The first is the local path to files on the server. The second is URL paths, which may be necessary for loading JavaScript files, CSS stylesheets, or other assets. You may also need to link to a specific URL within the WordPress installation itself.

      Because WordPress provides the ability for users to move their wp‐content folder (where plugins are located) to any location on the server, it's important to use the standard WordPress functions for determining the correct path.

      Local Paths

      Local paths reference locations on the server. PHP provides easy methods for determining paths for almost every case needed. However, to be on the safe side, it's best to use WordPress functions where possible. The plugin_dir_path() function provides an easy way to get the filesystem directory path to your plugin.

      <?php $path = plugin_dir_path( $file ); ?>

      Parameters:

       $file (string, required): The filename in the current directory path

      The following example will print the path of the current directory of the file passed in with a trailing slash using PHP's __FILE__ constant:

<?php echo plugin_dir_path( __FILE__ ); ?>

      That code should output a path similar to the following:

      /public_html/wp-content/plugins/pdev/

      Any file can be passed into the function. The resulting path will point to wherever the file lives in your plugin. If passing in __FILE__ from the primary plugin file, it'll be the path to the root of your plugin. If passing it in from a subfolder in your plugin, it will return the path to the subfolder in your plugin.

      Assuming you needed to load a file named /src/functions.php from your plugin that houses some custom functions, use the following code:

      <?php include plugin_dir_path( __FILE__ ) . '/src/functions.php'; ?>

      It is common practice for plugin authors to store this path as a variable or constant in the plugin's primary file for quick access to the plugin's root folder path, as shown in the following example code:

      <?php define( 'PDEV_DIR', plugin_dir_path( __FILE__ ) ); ?>

      This allows you to reference PDEV_DIR any time you need it from anywhere in the plugin without having to think about file paths.

      URL Paths

      Referencing URL paths can be tougher than local paths because there's usually no good way to determine this via standard PHP functions or constants alone. You'll need to rely on WordPress to get the correct path.

      The primary use case for getting a URL path will be determining the path to an asset (e.g., JavaScript, CSS, or image files) within your plugin. WordPress provides the plugin_dir_url() function to handle this use case.

      <?php $url = plugin_dir_url( $file ); ?>

      Parameters:

       $file (string, required): The filename in the current directory path

      WordPress will automatically convert any filename passed in to an appropriate URL equivalent. See the following example of passing in the filename from within the primary plugin file:

      <?php echo plugin_dir_url( __FILE__ ); ?>

      That code will output something like the following URL with a trailing slash:

      https://example.com/wp-content/plugins/pdev/

      If you wanted to determine the path of a JavaScript file located at /public/js/example.js in your plugin, you'd use the following code:

      <?php $url = plugin_dir_url( __FILE__ ) . 'public/js/example.js'; ?>

      You can use this to correctly get the URL path to any location in your plugin. Like its plugin_dir_path() counterpart, you can pass in any filename in your plugin to determine the appropriate URL for any location.

WordPress also provides a plugins_url() function. plugin_dir_url() is a wrapper for this function. For most purposes, these two functions can almost be used interchangeably, but there are some important differences.

      <?php $url = plugins_url( $path = '', $plugin = '' ); ?>

      Parameters:

       $path (string, optional): A path to append to the end of the URL

       $plugin (string, optional): The full path to a file within the plugin

      If no parameters are provided, the function will return the URL to the plugin's directory for the WordPress installation. It also does not add a trailing slash to the end of the URL. For most cases, it's usually best to stick with plugin_dir_url(). However, this function is available if needed.

      Other than determining the URL path to files within your plugin, you may need to determine the URL for a particular page or directory within the WordPress installation. WordPress has a number of useful functions that return the necessary information.

       site_url(): URL path to where WordPress is installed

       home_url(): URL path to the site's homepage

       admin_url(): URL path to the WordPress admin

       rest_url():