How to fix the ‘The plugin does not have a valid header’ error when activating a WordPress plugin

You want to extend WordPress’ functionality and decided to download some plugins found in the Official WordPress Plugin repository. After searching the repo, you’ve found two plugins that accomplishes the tasks you needed to implement in your blog. Downloading the plugins gives you two ZIP files that when double-clicked, shows you the contents in the following format:

plugin-a.zip

plugin-a-folder
---- plugin-a-main-file.php
---- plugin-a-readme.txt

plugin-b.zip

plugin-b-folder
---- plugin-b-subfolder
-------- plugin-b-main-file.php
-------- plugin-b-readme.txt

There are two ways to install a plugin. Option 1 is to unzip the file and upload the contents to wordpress_root/wp-content/plugins/ directory. Option 2 is to use the Add New -> Upload option found in the left panel bar of the administrative page of WordPress. Let’s assume the two plugins went through the two installation options.

Installing ‘plugin-a.zip’ using Option 1

1. Unzip the file
2. Upload the contents to wordpress_root/wp-content/plugins/
3. Login as admin and go to Plugins -> Installed.
4. Locate plugin and click Activate link.
5. Result:
   Plugin activated.

Installing ‘plugin-a.zip’ using Option 2

1. Login as admin and go to Plugins -> Add New -> Upload
2. Locate the file plugin-a.zip by clicking the Browse button.
3. Click Install Now button.
4. Result:
   Unpacking the package?
   Installing the plugin?
   Plugin installed successfully.
5. Click Activate Plugin link.
6. Result:
   Plugin activated.

Installing ‘plugin-b.zip’ using Option 1

1. Unzip the file
2. Upload the contents to wordpress_root/wp-content/plugins/
3. Login as admin and go to Plugins -> Installed.
4. Locate plugin and click Activate link.
5. Error: Plugin does not exists in the list.

Installing ‘plugin-b.zip’ using Option 2

1. Login as admin and go to Plugins -> Add New -> Upload
2. Locate the file plugin-b.zip by clicking the Browse button.
3. Click Install Now button.
4. Result:
   Unpacking the package?
   Installing the plugin?
   Plugin installed successfully.
5. Click Activate Plugin link.
6. WordPress ? Error
   The plugin does not have a valid header.

Based on our testing, plugin-b.zip seems to fail on both methods of installation. To find out what is causing the error, we have to understand how the plugin installation works. Upon checking the core files I found this excerpt in get_plugins() function:

* WordPress only supports plugin files in the base plugins directory
* (wp-content/plugins) and in one directory above the plugins directory
* (wp-content/plugins/my-plugin). The file it looks for has the plugin data and
* must be found in those two locations. It is recommended that do keep your
* plugin files in directories.

The plugin data that the function is looking for can be found below:

01

02

/*

03	Plugin Name: Name Of The Plugin

04	Plugin URI: http://URI_Of_Page_Describing_Plugin_and_Updates

05	Description: A brief description of the Plugin.

06	Version: The Plugin's Version Number, e.g.: 1.0

07	Author: Name Of The Plugin Author

08	Author URI: http://URI_Of_The_Plugin_Author

09	License: A "Slug" license name e.g. GPL2

10

*/

11

?>

So in order to properly install and activate a plugin, the following two conditions must be satisfied:

• that a plugin main file (.php) must be placed in plugins root folder or in first-level subdirectory within plugins folder
• and it should contain the necessary plugin data for identification/validation purposes

In the case of plugin-b.zip, although the main PHP file contains the needed plugin data, the validate_plugin() function returned an error since neither the file can be found or check if it contains the plugin data because it is placed in the second level subdirectory, a directory location in which the function is not designed to scan the content.
To fix the plugin-b.zip file, it needs to have the following content structure:

plugin-b.zip

plugin-b-folder
---- plugin-b-main-file.php
---- plugin-b-readme.txt

I hope this post will enlighten WordPress users who wants to maximize their blog’s potential