Make it easier to add new WP Super Cache plugins by outside code. (#574)

* Put plugins in wp-content/plugins/wp-super-cache-plugins/

Adding new plugins to WP Super Cache to extend it is complicated but
where they should go should be easy. This patch makes the plugin check
in a particular directory if it exists and load the PHP files there.
The files there won't be deleted when WP Super Cache is updated.

* Add $wpsc_plugins array with plugins to be loaded

Add helper functions to add and delete plugin files from the list to be
loaded by WP Super Cache:
wpsc_add_plugin( $file );
wpsc_delete_plugin( $file );
And this function to return the list of plugins:
wpsc_get_plugins();

* Add documentation on adding/deleting plugins.

readme.txt

@@ -200,7 +200,7 @@ Cached files are served before almost all of WordPress is loaded. While that's g
 This plugin caches entire pages but some plugins think they can run PHP code every time a page loads. To fix this, the plugin needs to use Javascript/AJAX methods or the wpsc_cachedata filter described in the previous answer to update or display dynamic information.
 
 ### Why do my WP Super Cache plugins disappear when I upgrade the plugin? ###
-WordPress deletes the plugin folder when it updates a plugin. This is the same with WP Super Cache so any modified files in wp-super-cache/plugins/ will be deleted. You can define the variable $wp_cache_plugins_dir in wp-config.php or wp-content/wp-cache-config.php and point it at a directory outside of the wp-super-cache folder. The plugin will look there for it's plugins.
+WordPress deletes the plugin folder when it updates a plugin. This is the same with WP Super Cache so any modified files in wp-super-cache/plugins/ will be deleted. You can put your custom plugins in a different directory in a number of ways. You can define the variable $wp_cache_plugins_dir in wp-config.php or wp-content/wp-cache-config.php and point it at a directory outside of the wp-super-cache folder. The plugin will look there for it's plugins. Or if you distribute a plugin that needs to load early you can use the function `wpsc_add_plugin( $filename )` to add a new plugin wherever it may be. Use `wpsc_delete_plugin( $filename )` to remove the plugin file. See [#574](https://github.com/Automattic/wp-super-cache/pull/574/) or [this post](https://odd.blog/2017/10/25/writing-wp-super-cache-plugins/) on writing WP Super Cache plugins.
 
 ### What does the Cache Rebuild feature do? ###
 When a visitor leaves a comment the cached file for that page is deleted and the next visitor recreates the cached page. A page takes time to load so what happens if it receives 100 visitors during this time? There won't be a cached page so WordPress will serve a fresh page for each user and the plugin will try to create a cached page for each of those 100 visitors causing a huge load on your server. This feature stops this happening. The cached page is not cleared when a comment is left. It is marked for rebuilding instead. The next visitor within the next 10 seconds will regenerate the cached page while the old page is served to the other 99 visitors. The page is eventually loaded by the first visitor and the cached page updated. See [this post](https://odd.blog/2009/01/23/wp-super-cache-089/) for more.

wp-cache-phase1.php

@@ -49,6 +49,28 @@
 	}
 }
 
+if ( isset( $wpsc_plugins ) && is_array( $wpsc_plugins ) ) {
+	foreach( $wpsc_plugins as $plugin_file ) {
+		if ( file_exists( ABSPATH . $plugin_file ) ) {
+			include_once( ABSPATH . $plugin_file );
+		}
+	}
+}
+
+if (
+	file_exists( WPCACHEHOME . '../wp-super-cache-plugins/' ) &&
+	is_dir( WPCACHEHOME . '../wp-super-cache-plugins/' )
+) {
+	$plugins = glob( WPCACHEHOME . '../wp-super-cache-plugins/*.php' );
+	if ( is_array( $plugins ) ) {
+		foreach ( $plugins as $plugin ) {
+			if ( is_file( $plugin ) ) {
+				require_once $plugin;
+			}
+		}
+	}
+}
+
 $wp_start_time = microtime();
 
 if ( $wp_cache_not_logged_in && wp_cache_get_cookies_values() ) {

wp-cache.php

@@ -4062,3 +4062,38 @@ function wpsc_update_plugin_list( $update ) {
 		}
 	}
 }
+
+function wpsc_add_plugin( $file ) {
+	global $wpsc_plugins;
+	if ( substr( $file, 0, strlen( ABSPATH ) ) == ABSPATH ) {
+		$file = substr( $file, strlen( ABSPATH ) ); // remove ABSPATH
+	}
+	if (
+		! isset( $wpsc_plugins ) ||
+		! is_array( $wpsc_plugins ) ||
+		! in_array( $file, $wpsc_plugins )
+	) {
+		$wpsc_plugins[] = $file;
+		wp_cache_setting( 'wpsc_plugins', $wpsc_plugins );
+	}
+}
+
+function wpsc_delete_plugin( $file ) {
+	global $wpsc_plugins;
+	if ( substr( $file, 0, strlen( ABSPATH ) ) == ABSPATH ) {
+		$file = substr( $file, strlen( ABSPATH ) ); // remove ABSPATH
+	}
+	if (
+		isset( $wpsc_plugins ) &&
+		is_array( $wpsc_plugins ) &&
+		in_array( $file, $wpsc_plugins )
+	) {
+		unset( $wpsc_plugins[ array_search( $file, $wpsc_plugins ) ] );
+		wp_cache_setting( 'wpsc_plugins', $wpsc_plugins );
+	}
+}
+
+function wpsc_get_plugins() {
+	global $wpsc_plugins;
+	return $wpsc_plugins;
+}