OOP, extended API, example plugin #6

Merged
merged 4 commits into from Jun 28, 2012

2 participants

@franz-josef-kaiser
Collaborator
  • OOP: I completely moved the plugin to an OOP concept to get rid of all the public functions.
  • Extended API: The API now comes with an array of arguments. This means that I deprecated the $key argument, as it can simply be built from the label, which makes it easier. I then added in the support for a root, so we can use the WP_CONTENT_DIR, WP_PLUGIN_DIR, WPMU_PLUGIN_DIR and the root as containers for additional plugin directories. It now also works (and this was the main reason for this), if you defined an external location for your plugins. I got several local installations, that all together share the local domain plugins.dev for their plugins. This saves me from copy/pasting and updating plugins in several installations and makes development much easier. Moving the arguments to an array will make altering the API arguments much easier later on. I took some time to make shure, that we'll guide people on how to use the new API without breaking existing installations, so everything's backwards compatible. The last thing that was added, is guidance on when to hook the plugin. It's a simply call to _doing_it_wrong() if the current_filter() isn't plugins_loaded. This prevents the usage of the muplugins_loaded hook, but it isn't a loss, as the filter wouldn't help anything, as the plugin runs later.
  • Example Plugin: I added an example plugin to show how stuff works and should be done.
  • Readme: I also added a small changelog to keep people on trac. I got some code somewhere, where we could also extend the plugin info in the list table and move the changelog to a separate file, but that's code for another patch.

Everything's tested in different cases, but you know what: We're all humans and bugs are built in :)

@franz-josef-kaiser franz-josef-kaiser commented on the diff Jun 28, 2012
inc/admin.php
-class CD_APD_Admin
+
+if ( ! class_exists( 'CD_APD_Admin' ) )
+{
+ add_action( 'plugins_loaded', array( 'CD_APD_Admin', 'instance' ) );
@franz-josef-kaiser
Collaborator

Hooking the main class into plugins_loaded on priority 10. This will allow people better control via hooks. It also makes sure, the new static $instance only runs once.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@franz-josef-kaiser franz-josef-kaiser commented on the diff Jun 28, 2012
inc/api.php
+
+
+/**
+ * Registers a new plugin directory.
+ *
+ * @since 0.1
+ * @uses _get_new_plugin_directory_root()
+ * @param array $args An Array of arguments: 'dir' = Name of the directory, 'label' = What you read above the list table, 'case' = Where the dir resides.
+ * @param string $deprecated_dir (deprecated arg) The new plugin directory. Either a full path or a folder name within wp-content.
+ * @param string $deprecated_label (deprecated arg) The nice name of the plugin directory. Presented in the list table.
+ * @return bool TRUE on success, FALSE in case the $key/$label is already in use.
+ */
+function register_plugin_directory( $args, $deprecated_dir = '', $deprecated_label = '' )
+{
+ // The call was too late (or too early in case of a MU-Plugin)
+ if ( 'plugins_loaded' !== current_filter() )
@franz-josef-kaiser
Collaborator

Make sure we run stuff on the right filter. If not, we're adding a note for the user that she/he should fix stuff.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@franz-josef-kaiser franz-josef-kaiser commented on the diff Jun 28, 2012
inc/api.php
+ * @return bool TRUE on success, FALSE in case the $key/$label is already in use.
+ */
+function register_plugin_directory( $args, $deprecated_dir = '', $deprecated_label = '' )
+{
+ // The call was too late (or too early in case of a MU-Plugin)
+ if ( 'plugins_loaded' !== current_filter() )
+ {
+ _doing_it_wrong(
+ __FUNCTION__
+ ,__( 'Registering a new plugin directory should be done during the `plugins_loaded` hook on priority `0`.', 'cd_apd_textdomain' )
+ ,'0.1'
+ );
+ }
+
+ // Deprecating single arguments
+ if ( ! is_array( $args ) )
@franz-josef-kaiser
Collaborator

Moving input arguments to an array...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@franz-josef-kaiser franz-josef-kaiser commented on the diff Jun 28, 2012
inc/api.php
+ {
+ $info = debug_backtrace();
+ // The key now gets built from the label: Converted to lowercase alphanumeric string.
+ _deprecated_argument(
+ __FUNCTION__
+ ,'0.3'
+ ,sprintf(
+ __( "%sYou need to specify the arguments – when registering new plugin directories – as associative array.%s%s", 'cd_apd_textdomain' )
+ ,'<br /><blockquote><strong>'
+ ,'</strong></blockquote>'
+ ,"The call was from within: <code>{$info[ 0 ]['file']}</code> in the function: <code>{$info[ 1 ]['function']}()</code>.<br />"
+ )
+ );
+
+ // Fix for back compat
+ $args = array(
@franz-josef-kaiser
Collaborator

...and making sure stuff doesn't break and is backwards compatible.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@franz-josef-kaiser franz-josef-kaiser commented on the diff Jun 28, 2012
inc/api.php
+ );
+
+ return true;
+}
+
+
+/**
+ * Retrieves the root path for the new plugin directory.
+ *
+ * @internal Callback function for register_plugin_directory()
+ *
+ * @since 0.3
+ * @param string $case Valid: 'content', 'plugins', 'muplugins', 'root'.
+ * @return string $root The root path based on the WP filesystem constants.
+ */
+function _get_new_plugin_directory_root( $root )
@franz-josef-kaiser
Collaborator

Now we're supporting all different sorts of locations. The switch makes sure, we can easily add in additional cases. Maybe we should also add an filter?

@chrisguitarguy
Owner
case 'content':
default:
    $root = apply_filters("adp_root_{$root}", WP_CONTENT_DIR);

Probably a good idea. Makes it more flexible.

@franz-josef-kaiser
Collaborator
case 'content' :
    $root = WP_CONTENT_DIR;
    break;

default :
    $root = apply_filters( "adp_root_{$root}", WP_CONTENT_DIR );
    break;

...to move 'content' away from any other behavior. This would allow to add whatever/custom/etc... as arg and then make use of the filter.

@chrisguitarguy
Owner

Sounds good to me.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
franz-josef-... added some commits Jun 28, 2012
@chrisguitarguy chrisguitarguy merged commit 1e71dcb into chrisguitarguy:master Jun 28, 2012
@chrisguitarguy

Merged! Will test tonight.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment