is it ok to change the main file name in a WordPress plugin when updating to a new version?

Question

I'm going through a WordPress plugin and restructuring the whole thing, fixed a few bugs, created a new folder structure, and added some shortcodes.

I want to roll out my updates as version 2. I'm wondering, does it matter that I renamed the plugin's main file using my custom prefix?

For example: I changed xmascount.php, to cw_xmascount.php.

Do I just delete all the files and folders of the original version of the plugin from the repository and then upload the new ones?

Answer 1

Very old question, but still relevant. And missing a real answer...

The short answer:

Changing the main plugin file name is not OK in the sense that WordPress depends on the plugin "folder/file-name" name combination to keep track of active plugins. This means that changing either one of those on an update (or via FTP or file manager) on a live site will cause WordPress to loose sight of the plugin.

The plugin will not be loaded anymore (read: "deactivate" without going through the normal deactivation process) and when you visit the WordPress admin Plugins page, you will see an admin error notice about the missing plugin.

But...

There is a way around this :)

The long answer:

The way plugin management (and updates) is set up in WordPress does not allow for a simple name change for the main plugin file. But even though WordPress has not foreseen in elegant solution for plugin developers to change the main plugin file name without breaking updates, the following approach should allow you to do it:

1. Build and test your complete plugin, using your preferred file names. It does not matter what the main plugin file name is, as long as it works in your test environment.
2. Add/recreate an empty file with the original (old) plugin file name in the plugin root. Place the following code example in it and adapt the plugin folder/filename to match your original and new main file names.

<?php
/**
 * My Plugin old main file upgrade routine
 *
 * This is the old plugin main file.
 * Keep it for backward upgrade compatibility.
 *
 * @package My Plugin
 */

defined( 'WPINC' ) || die;

$old = 'old-file-name.php'; // Change this.
$new = 'new-file-name.php'; // Change this.

// Change the active plugin settings to make WP start using the new one.
$active_plugins = (array) get_option( 'active_plugins', array() );

$old_plugin_array = array( basename( __DIR__ ) . '/' . $old );
$active_plugins   = array_diff( $active_plugins, $old_plugin_array );

$new_plugin = basename( __DIR__ ) . '/' . $new;
if ( ! in_array( $new_plugin, $active_plugins ) ) {
    $active_plugins[] = $new_plugin;

    include_once __DIR__ . '/' . $new;
}

// Update active plugins and never come back here.
update_option( 'active_plugins', $active_plugins );

What this does:

When users upgrade the plugin, WordPress (unaware of the file name change) will first attempt to load the old file. Loading the file will run the code, which: gets the active plugins list, then removes the old file reference, adds the new file reference and saves the new active plugins list.

It will also load the new plugin file to make sure there is no "gap" in plugin availability.

The file should only serve once after the plugin upgrade. After that, it will not be used anymore. Nor will it be visible in the WP admin Plugins list.

Notes and caveats:

1. Change only the two file names before the "Change this" comment. Do not add the plugin directory name there.
2. The old main file (with new content) needs to remain in the plugin repository for backward compatibility. Users may upgrade from an older version at any time in the future. If the old file has been removed at that time, the upgrade will just deactivate the plugin (see the "Short answer" above).
3. Make sure to completely replace the old main plugin file content. Do not leave the old plugin headers in there, otherwise your plugin will appear twice on the WP admin Plugins page.
4. I have not tested this on a Windows server. If WordPress saves plugin dir+filename with backslashes on Windows (sorry, I don't know) then this might not work correctly. If anyone knows, please comment...