Plugin Portability: Basename of your Plugin

Plugins in wordpress are to be identified by their so called “plugin basename”. That is basically the filename of the plugins PHP-file if it is placed directly inside /wp-content/plugins or the subdirectory and the PHP-filename.

This basename is important to know when you add hooks to your plugin, for example the plugin_action_links hook, or even more concrete the plugin_action_links_{$plugin_file} hook.

So how to obtain the basename to your plugin? Gladly there is a function available to deal with it. If you’re operating in the same plugin PHP-File, you can use it with the __FILE__ magic constant:

$basename = plugin_basename(__FILE__);

And what if your plugin extends from a base plugin class which should automatically set the basename to a protected member on instanziation? Well then you can use some little reflection to find out the concrete filename the class was defined in (much likely your plugin PHP-File):

$meta = new ReflectionClass($this);
$file = $meta->getFileName();
$base = plugin_basename($file);

That easy it is.

Related Ticket: #14182

Watch on: Mitcho Erlewine: Abstract Your Code! (I missed the actual example How-To to abstract your plugins code, so I hope my post is of little help here [starting 5:10].)

This entry was posted in Plugin Plugout, Pressed and tagged , , , , , , , , , , . Bookmark the permalink.

5 Responses to Plugin Portability: Basename of your Plugin

  1. mtekk says:

    This is fine to use to figure out the basename if you don’t know what it should be, however there are some major pitfalls with this if a user changes a directory name. It all has to do with how the plugin updater works.

    Case in point. Rename a plugin’s containing directory (e.g. rename the directory for Breadcrumb NavXT from breadcrumb-navxt to breadcrumbs, and uncomment line 79 in breadcrumb_navxt_admin.php so it is basename “mobile”). Now change the version in the plugin’s headers to an older version. In the WordPress admin, it will prompt you to upgrade the plugin. Let WordPress upgrade the plugin. Now you’ll see WordPress will use a specific basename (breadcrumb-navxt, not breadcrumbs), different from the one you just changed it to and you now have two copies of the plugin. Fun right?

    • hakre says:

      That looks like that the automatic upgrade feature is making it’s own assumptions w/o reflecting the status quo properly. I assume it blindly takes over the plugin “slug” from the repository instead reflecting the current configuration.

      So this is an error with the updater and should not be an argument against making the usage of someones own plugins more modular.

      But it’s good that you comment, I’ve seen that “hardencoded” string in the breadcrumb admin class. Infact I was doing a refactoring into some other plugin and I ran over this issue and wanted to approach it somehow for the beginning.

      Is there a ticket in trac regarding the problem in the upgrader?

      On a first quick search I could reveal this one, which speaks somehow of it’s own as well: #11495 – Directory Problems with Core Upgrade.

      • mtekk says:

        I think I know why they use the slug from the plugin directory. It gives a valid directory name that will not have a name collision with another plugin from the directory.

        As for a ticket on trac, I haven’t really bothered searching/reporting this yet, primarily because I don’t think people should be changing the basename directory of a plugin. I still haven’t seen a reason that the basename of a plugin would need to be changed by an end user (I’m a bad sheep as I ask questions instead of blindly following).

        The other reason is there are many more important bugs that keep getting punted from release to the next that I highly doubt anything would get fixed if it ends up requiring a significant amount of thought to fix and a core developer is not interested in it (example of this is the page/post status needs a reworking/rethought, there is a ticket I was working on and came to this conclusion, asked for input from a core developer and nothing has happened in a year now). WordPress should really take the rest of the year off from adding new features and just fix the bugs in the current software (yes I want two or more pure bug fixing development cycles as that’s what I see is needed). Really, if a year from now WP 3.0.5 was the current release, but they fixed half of the bugs in trac, I’d consider that a ton of progress.

        -John Havlik

        • hakre says:

          Okay, well, then using the plugin_basename() function at least in own plugins saves in case users are renaming the plugin file.

          So renaming a plugin – can be useful in case you create a fork or you just do it for some tests or so. That said, it can always save the plugin dev some hassles in the end.

          And even: Renaming the base directory can be a must in case of a name collision, for example if the original developer is not available any longer to rename the plugin.

          And only because there are other bugs, it does not mean that it ain’t worth to report. That helps to have deficiencies documented and that can turn out helpful in the future.

          Related Ticket: #14182 – and you’re right there are even more issues related to upgrade / version check.

          • mtekk says:

            Not to get on a huge rant/in a argument about this, but the way I see it, the plugin repository is the guide for basenames. If your plugin has a collision with a basename of a plugin in the directory, it is up to you to rename your plugin, and at that point you will know what needs to change in your code for this. Likewise, if you are forking code, you should know what needs to be changed if you change the basename (or at least know where to go looking).

            I guess my original point, from my first comment, was that, in my opinion, plugin_basename() is purely there for developer convenience. It also has pitfalls (allows users to do bad things) that leads me to believe it should not be in “production” code.

            As for bug reporting, I still maintain my position in my second comment:

            As for a ticket on trac, I haven’t really bothered searching/reporting this yet, primarily because I don’t think people should be changing the basename directory of a plugin. I still haven’t seen a reason that the basename of a plugin would need to be changed by an end user.

            -John Havlik

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.