Often you need to determine fi le and folder paths within your plugins. For example, you might have an image in your plugin folder that you want to display. Generally speaking, it isn ’ t a good idea to hardcode a directory path in a plugin. WordPress can be confi gured to run in a million different ways, so assuming you know the proper directory paths is a mistake. This section looks at the proper way to determine fi le and folder paths in your WordPress plugin.
A common task in any plugin is referencing fi les and folders in your WordPress installation. You can reference fi les in your code in two ways: using the local server path or by using a standard URL.
Think of the local server path as nothing more than the directory path on a computer. The local server path is generally used whenever you need to include something that is local on your server. A URL is typically used to link to something external to your server, but that doesn ’ t mean you can ’ t link to images and such using the URL path.
WordPress features the ability to move the wp – content directory to a different location. Because of this you shouldn ’ t hardcode directory paths in WordPress, but rather use the available functions to determine the correct path.
The Local Path
Here ’ s one common question in plugin development: What is the proper way to determine the local path to your plugin fi les? To determine the local path to your plugin, you need to use the plugin_dir_path() function. The plugin_dir_path() function extracts the physical location relative to the plugins directory from its fi lename.
[sourcecode language=”php”]< ?php plugin_dir_path( $file ); ? >[/sourcecode]
Parameters:
- $file – (string) (required) — The fi lename of a plugin
Now look at an example on how to determine the local path to your plugin folder:
[sourcecode language=”php”]< ?php echo plugin_dir_path( __FILE__ ); ? >[/sourcecode]
You can see you pass the _FILE__ PHP constant to the plugin_dir_path() function. This produces the full local server path to your plugin directory:
/public_html/wp-content/plugins/my-custom-plugin/
What if you need to get the local path to a fi le in a subdirectory inside your plugin directory? You can also use the plugin_dir_path() function along with the subdirectory and fi les you want to reference:
[sourcecode language=”php”]< ?php echo plugin_dir_path( __FILE__ ) .’js/scripts.js’; ? >[/sourcecode]
This code would produce the following results:
/public_html/wp-content/plugins/my-custom-plugin/js/scripts.js
As you can see, this function will be instrumental in developing a solid WordPress plugin. Using the proper methods to access your plugin fi les and directories can ensure maximum compatibility with all WordPress installations, regardless of how custom it is.
The URL Path
Functions are also available to help determine URLs in WordPress. Following is a list of those functions:
- plugins_url() — Full plugins directory URL (for example,http://example.com/wp – content/plugins )
- includes_url() — Full includes directory URL (for example, http://example.com/wp – includes )
- content_url() — Full content directory URL (for example, http://example.com/wp – content )
- admin_url() — Full admin URL (for example, http://example.com/wp – admin/ )
- site_url() — Site URL for the current site (for example, http://example.com )
- home_url() — Home URL for the current site (for example, http://example.com )
The site_url() and home_url() functions are similar and can lead to confusion in how they work. The site_url() function retrieves the value as set in the wp_options table value for siteurl in your database. This is the URL to the WordPress core fi les. If your core fi les exist in a subdirectory /wordpress on your web server, the value would be http://example.com/wordpress .
The home_url() function retrieves the value for home in the wp_options table. This is the address you want people to visit to view your WordPress web site. If your WordPress core fi les exist in /wordpress , but you want your web site URL to be http://example.com the home value should be http://example.com .
The plugins_url() function will be one of your best friends when building plugins in WordPress. This function can help you easily determine the full URL to any fi le within your plugin directory.
[sourcecode language=”php”]< ?php plugins_url( $path, $plugin ); ? >[/sourcecode]
Parameters:
$path – (string) (optional) — Path relative to the plugins URL
$plugin – (string) (optional) — Plugin fi le that you want to be relative (that is, pass in _FILE__ )
For example, say you want to reference an image fi le to use as an icon in your plugin. You could easily accomplish this using the following example:
[sourcecode language=”php”]< ?php
echo ‘ < img src=”’ .plugins_url( ‘images/icon.png’ , __FILE__ ). ‘” > ’;
? >[/sourcecode]
The fi rst parameter value you pass to the function is the relative path to the image fi le you want to include. The second parameter is the plugin fi le that you want to be relative, which in this case you can simply send in the PHP constant _FILE__ . The preceding code would generate the HTML img tag as follows:
< img src=”http://example.com/wp-content/plugins/my-custom-plugin/images/icon.png” >
Following are some of the advantages to using the plugins_url() function to determine plugin URLs:
- Supports the mu – plugins plugin directory.
- Auto detects SSL, so if SSL is enabled in WordPress, the URL returned would contain https.
- Uses the WP_PLUGIN_URL constant, meaning it can detect the location of the plugin even if
- the user has moved it to a custom location.
- Supports Multisite using the WPMU_PLUGIN_URL constant.