The difference between the plugin (main) file and the plugin's slug is a place where the WordPress Codex could do much better.
I understand your confusion as I have felt it too recently (mixed with frustration).
This is what I have learned by doing some "detective work" on the WordPress core code.
The plugin file
This is the unique way WordPress identifies and records a plugin. It is made up of the plugin's directory AND the main plugin file (the one with the file header containing the various plugin details like version, author, etc.).
It would look something like this:
If you look at the active plugins data (returned by
get_option( 'active_plugins' ) ), you will see that WordPress only needs this plugin file to properly identify plugins.
You could choose to think of it as your plugin's main file relative path (relative to the
wp-content/plugins/ directory that is). You could "compose" the absolute path of the main plugin file with something like this:
trailingslashit( WP_PLUGIN_DIR ) . $plugin_main_file
The core itself generates the plugin file like this:
$plugin_main_file = plugin_basename( trim( $plugin_main_file_absolute_path ) );
The plugin slug
One would expect the plugin "slug" to be some sort of standardized ID for the plugin like the post slug is for posts - so you could use this "slug" to provide it to WordPress core functions and get things going.
Not really. After searching the core for references to plugin slugs (or themes for what matters) and finding almost nothing, I think I have a grasp on it.
The only real slugs are those for things accessible via a unique URL: posts, pages, taxonomies, etc. That is the whole point of taking the name of something (like a post title) and generating a URL friendly version of that: to use it in a URL.
But where do we use theme/plugins "slugs" in URLs?
We don't do that on individual WordPress installations - neither in the WP admin or the frontend.
However, there is a place very much entangled with the WordPress code, the WordPress.org site. People are having a hard time distinguishing between the two, including that it got somehow common among developers to consider the WordPress.org theme or plugin slugs should work the same as a post or page slug.
They serve the same purpose but on separate websites. On WordPress.org they are used to uniquely identify a theme from others, and a plugin from the rest (in URLs like
But when it comes to individual WordPress installations, the same uniqueness can't be guaranteed because there is no authority to enforce it (like on WordPress.org). It could work if all the plugins and themes came from WordPress.org, but thankfully that is not the case.
What does the WordPress code do with theme/plugin slugs?
The WordPress core code doesn't rely on theme/plugin slugs to do things like installing, activating, updating, deleting themes or plugins.
For themes, it relies on the theme directory since the main entry point into a theme is the
style.css file (you can't use another CSS file to hold your theme details header).
For plugins, it relies on the plugin directory AND the main plugin file, since plugins can call their main file however they like.
The only thing the core uses theme/plugins slugs for is when it handles themes and plugins from the WordPress.org directory: fetching lists of plugins, checking for updates, reporting back to the directory usage data, and so on.
To wrap things up about plugin slugs: whenever you find plugin data with the
slug entry, 99% of the time it will refer to the WordPress.org slug of the plugin.
How do we go about identifying plugins?
If you want to programmatically activate, update, deactivate or delete a certain plugin on a WordPress installation, you need to use the plugin file. You can get it like this from your plugin's main file:
$plugin_file = plugin_basename( __FILE__ );
If you want to target a certain plugin from another plugin, things get a bit trickier since you need to rely on a bit of "guesswork".
You could hard-code the plugin name, search the plugin in the list of all plugins (see get_plugins()) and get the plugin file from there.
If you know a class or function that is defined by that plugin you could use reflection (see this answer for classes and this one for functions).
I hope this helps you and others that might have a hard time dealing with "plugin slugs". It could have saved me a couple of hours :)