Best Practices for
Customizing WordPress Plugins

Follow along at
http://iandunn.name/customizing-plugins

Ian Dunn <ian@iandunn.name>
Automattic, Inc

Interaction

Ask questions if anything's unclear
Jump in with comments, tips, etc

Overview

Collaboration
Extending without modifying
Using custom hooks
Overriding Core hook callbacks
Adding custom hooks
Code samples and Q&A throughout

The Problem

Need to customize plugins
very common for developers to customize and extend existing plugins to fit their own needs one of the great advantages of using open-source software
Lose changes when upgrading
but they often do it by making their changes directly to the plugin so if you upgrade the plugin, the files are overwritten and you lose your changes
Manually diff'ing is a chore
if still want to keep plugin updated, then each time new version comes out have to manual diff your version against the canonical one and syncing them up in both directions could make it a little easier use version control create a patch then refresh it every time an update is released
Usually just never upgrade
all that is a pain in the [ass] developers rarely go to the trouble so they miss out on security patches bug fixes new features
There's a better way
so let's talk about how we do the customizations we want without the pain of manually upgrading there are several approaches

Collaborate With the Developer

First, talk to the developer
Before you try anything else, the first thing to do is to send a message to the developer of the plugin and let them know what kinds of changes you need and offer to work with them to build them into the core plugin
Send a patch
If they’re open to it, then you can send them a patch with your changes
Win-win
The great thing about this method is that everyone who uses the plugin will benefit from your work and you’ll have contributed something back to the developer whose work you’ve benefited from.
Won't always work
The developer may not like the idea, though or it may not line up with their vision for the plugin or they might not have time to review your patch so that won’t always work
More options
There are still plenty of options, though.

Extend Without Modifying

If only adding new functionality
The easiest situation is when you just want to add some new functionality to their plugin, but you don’t need to remove or modify anything that the plugin does.
Create separate plugin running alongside
In this case, you can simply write a separate plugin that runs alongside the plugin you’re customizing.

Extend Without Modifying

Example: Google Authenticator – Encourage User Activation
look at a real-world example of this google authenticator - encourage user activation google authenticator is great plugin for enabling two-factor authentication on site but users don't know it's there unless they visit their profile even if they see the option to enable it, they won't always know what it is or why it's important so GAEUA lets admins nag or force users to enable it

Extend Without Modifying

public function __construct() {
    add_action( 'init', array( $this, 'encourage_users_to_enable_2fa' ), 12 );
}

public function encourage_users_to_enable_2fa() {
    if ( ! $user_has_2fa_enabled ) {
		add_action( 'admin_notices', array( $this, 'enable_2fa_notice' ) );

		if ( 'force' == $this->settings['mode'] ) {
            add_filter( 'user_has_cap', array( $this, 'restrict_user_capabilities' ), 10, 3 );
            
            if ( is_admin() ) {
                add_action( 'current_screen', array( $this, 'redirect_to_profile' ) );
            }
        }
    }
}

Using Custom Hooks

Sometimes need to change or remove functionality
If you do need to change or remove functionality from the plugin there’s a much better way than just hacking it and it’s something you’re already familiar with: hooks.
Custom hooks to the rescue
Just like WordPress provides hooks to allow plugins to customize and extend it, plugins themselves can provide hooks to allow other plugins to customize them. So, if you’re lucky, the plugin you want to extend was written by a developer who knew enough and cared enough to include custom hooks that will allow you to extend their plugin. If they did, then your job is pretty easy; you just need to write a separate plugin that runs alongside the plugin you’re customizing, and registers callbacks for the custom hooks that the plugin provides.
Examples: Tagregator, Basic Google Maps Placemarks, CampTix, CampTix Network Tools

Using Custom Hooks

Tagregator

Using Custom Hooks

Tagregator

protected function __construct() {
    $this->media_sources = apply_filters( 'tggr_media_sources', array(
        'TGGR_Source_Twitter'   => TGGR_Source_Twitter::get_instance(),
        'TGGR_Source_Instagram' => TGGR_Source_Instagram::get_instance(),
        'TGGR_Source_Flickr'    => TGGR_Source_Flickr::get_instance(),
    ) );
}

Tagregator - Vine Media Source

function vms_register_custom_media_sources( $media_sources ) {
    require_once( dirname( __FILE__ ) . '/classes/tggr-source-vine.php' );
    $media_sources[ 'TGGR_Source_Vine' ] = TGGR_Source_Vine::get_instance();

    return $media_sources;
}
add_filter( 'tggr_media_sources', 'vms_register_custom_media_sources' );

Using Custom Hooks

Basic Google Maps Placemarks

North Carolina Fire Station Mapping Project

Using Custom Hooks

Basic Google Maps Placemarks

public function get_map_placemarks( $attributes ) {
    // [...]
		
    foreach( $published_placemarks as $placemark ) {
        // [...]
		
        $default_icon = apply_filters(
            'bgmp_default-icon',
            plugins_url( 'images/default-marker.png', __FILE__ ),
            $post_id
        );
	
        // [...]
    }

    return apply_filters( 'bgmp_get-map-placemarks-return', $placemarks );
}

Using Custom Hooks

Snippet

function set_BGMP_default_icon_by_category( $icon_url, $placemark_id ) {
    $placemark_categories = wp_get_object_terms( $placemark_id, 'bgmp-category' );

    foreach ( $placemark_categories as $category ) {
        switch ( $category->slug ) {
            case 'restaurants':
                $icon_url = 'restaurants.png';
            break;
		
            case 'book-stores':
                $icon_url = 'book-stores.png';
            break;
        }
    }

    return $icon_url;
}
add_filter( 'bgmp_default-icon', 'set_BGMP_default_icon_by_category', 10, 2 );

Using Custom Hooks

CampTix

Using Custom Hooks

CampTix Network Tools

Using Custom Hooks

CampTix

if ( $doing_upgrade ) {
    $this->log( 'Upgrade already in progress, aborting concurrent attempt.', 0, null, 'upgrade' );
} else {
    // [...]
}

function log( $message, $post_id = 0, $data = null, $module = 'general' ) {
    do_action( 'camptix_log_raw', $message, $post_id, $data, $module );
}

add_action( 'camptix_log_raw', array( $this, 'camptix_log_meta' ), 10, 4 );
function camptix_log_meta( $message, $post_id, $data, $section ) {
    if ( $post_id ) {
        // [...]
	
        update_post_meta( $post_id, 'tix_log', $log );
    }
}

Using Custom Hooks

CampTix Network Tools

add_action( 'camptix_log_raw', array( $this, 'camptix_log_db' ), 10, 4 );
function camptix_log_db( $message, $post_id, $data_raw, $section = 'general' ) {
    // [...]
		
    $wpdb->insert( $table_name, array(
        'blog_id' => $blog_id,
        'object_id' => $post_id,
        'message' => $message,
        'data' => $data,
        'section' => $section,
    ) );
	
    // [...]
}

Using Custom Hooks

The downside: they don't always exist
Unfortunately, most developers don't add custom hooks yet, so you won’t always be able to rely on them. But even without them, there are still two more ways that you can customize the plugin that are better than just hacking it.

Overriding Their Core Callbacks

Analyze their Core hook callbacks
The plugin you want to customize integrated with WordPress by registering callback functions for Core hooks.
Remove their hooks
So, you can simply remove their callbacks, and replace them with your own.
Add your own in their place
Then inside your callbacks, you can call functions from the other plugin that you need in order to recreate the parts of their functionality that you want, and avoid the parts that you don’t.
Example: Google Authenticator – Per User Prompt
real-world example GA plugin is great for adding 2FA to your site, but it adds the prompt for the token on the same screen as un/pw that means that all users see it, even if they don't have 2fa enabled for their account users are confused pain for multi-user sites PUP addon moves the prompt to a second screen that only shows to users who have it enabled, after they enter the un/pw author didn't want to change it and custom hooks wouldn't help in this case need to unhook it from WP and then re-add a modified version

Overriding Their Core Callbacks

Google Authenticator

Overriding Their Core Callbacks

Google Authenticator - Per User Prompt

Overriding Their Core Callbacks

Google Authenticator

function init() {
    add_action( 'login_form',   array( $this, 'loginform' ) );
    add_action( 'login_footer', array( $this, 'loginfooter' ) );
    add_filter( 'authenticate', array( $this, 'check_otp' ), 50, 3 );
}

Overriding Their Core Callbacks

Google Authenticator - Per User Prompt

public function register_hook_callbacks() {
    // Remove Google Authenticator's callbacks
    remove_action( 'login_form',          array( GoogleAuthenticator::$instance, 'loginform' ) );
    remove_filter( 'authenticate',        array( GoogleAuthenticator::$instance, 'check_otp' ), 50, 3 );
	
    // Register our callbacks
    add_filter( 'authenticate',           array( $this, 'validate_application_password' ), 10, 3 );
    add_filter( 'authenticate',           array( $this, 'maybe_prompt_for_token' ), 25, 3 );
    add_action( 'login_form_gapup_token', array( $this, 'prompt_for_token' ) );
    add_filter( 'wp_login_errors',        array( $this, 'get_login_error_message' ) );
}

Overriding Their Core Callbacks

Google Authenticator - Per User Prompt

public function maybe_prompt_for_token( $user, $username, $attempted_password ) {
    if ( is_a( $user, 'WP_User' ) ) {	// they entered a valid username/password
        if ( 'enabled' == trim( get_user_option( 'googleauthenticator_enabled', $user->ID ) ) && ! $this->is_using_application_password ) {
            $login_nonce  = $this->create_login_nonce( $user->ID );
			
            wp_safe_redirect( $redirect_url );
            die();
        }
    }
	
    return $user;
}

Overriding Their Core Callbacks

Google Authenticator - Per User Prompt

public function prompt_for_token() {
    $redirect_to = isset( $_REQUEST['redirect_to'] ) ? $_REQUEST['redirect_to'] : '';
    $action_url  = add_query_arg( array( 'action' => 'gapup_token' ), wp_login_url( $redirect_to ) );
	
    $user = get_user_by( 'id', absint( $_REQUEST['user_id'] ) );
	
    $error_message = $this->process_token_form( $_POST, $user );
	
    require_once( dirname( __FILE__ ) . '/views/token-prompt.php' );
    exit();
}

Overriding Their Core Callbacks

Google Authenticator - Per User Prompt

<?php login_header(); ?>
		
<form action="<?php echo esc_url( $action_url ); ?>" method="post" autocomplete="off">
    <input type="hidden" name="user_id"           value="<?php echo absint( $user->ID ); ?>" />
    <input type="hidden" name="gapup_login_nonce" value="<?php echo esc_attr( $_REQUEST['gapup_login_nonce'] ) ?>" />
    <input type="hidden" name="redirect_to"       value="<?php echo esc_attr( $redirect_to ) ?>" />

    <?php GoogleAuthenticator::$instance->loginform(); ?>

    <p class="submit">
        <input type="submit" name="gapup_token_prompt" value="<?php esc_attr_e( 'Log In' ); ?>" />
    </p>
</form>

<?php login_footer( 'user_email' ); ?>

Overriding Their Core Callbacks

Need to monitor base plugin updates
because tightly integrating, need to monitor plugin commits in case changes to base plugin will break your addon, or require changes wporg lets you subscribe to email notifications for each new commit watch their trunk, so you can release an update before they release theirs maintain backcompat with current version was only worth it b/c ga ux was so frustrating other plugins may be simpler to replace though
Won't always work
Sometimes overriding their hooks isn’t ideal, though, because their functions aren’t modular enough to allow you to call individual pieces that you need without also invoking the things you don’t want. Even in that situation, though, there’s still one more method you can fall back on that’s better than just hacking all your changes into the plugin.

Adding Custom Hooks

Last resort: mod the plugin gracefully
If it’d be too much work to replace their Core hook callbacks with your own, you may need to hack the plugin directly, but instead of putting all your changes into it, simply add the custom hooks that you need, then put the rest of your functionality in a separate plugin.
Add custom hooks
Submit a patch
Then, you can submit a patch to the plugin’s developer and ask them to include the custom hooks you need in the next release of the plugin. If they do, then you can freely upgrade to new releases and your custom plugin will run cleanly alongside theirs.
Refresh and apply patch to upgrades
But even if they don’t, then you can still upgrade by manually patching your custom hooks into each new release. That’s not ideal, but it’s much better than having to patch in all of your changes, or just not upgrade at all.
Example: ACF-WPML Helper
had a client who used Advanced Custom Fields extensively, but also had neded to use WPML to translate all pages into multiple languages at the time, ACF used custom db tables instead of custom post types/meta, so WPML wasn't aware of any of the ACF data and couldn't translate it so wrote plugin to sit in between ACF and WPML and act as a middle man so that they could talk to each other

Adding Custom Hooks

WPML

function save_translation( $data ) {
    // [...]

    if ( $field_type == 'custom_field' ) {
        $field_translation = html_entity_decode( $field_translation );
        update_post_meta( $new_post_id, $field_name, $field_translation );

        // mod - ian@iandunn.name, 2011-07-26
        do_action( 'icl_save_translation_custom_fields', $new_post_id, $job, $field_name, $field_translation );
    }
		
    // [...]
}

Adding Custom Hooks

ACF-WPML Helper

add_action( 'icl_save_translation_custom_fields', array( $this, 'import_custom_field' ), 10, 4 );
public function import_custom_field( $new_post_id, $job, $field_name, $field_translation ) {
    $acf_post_TRID           = $this->get_ACF_post_TRID( $job->original_doc_id, $field_name );
    $source_ACF_post_id      = $this->get_ACF_post_id( $acf_post_TRID, $job->source_language_code );
    $destination_ACF_post_id = $this->get_ACF_post_id( $acf_post_TRID, $job->language_code );
    $field_type              = $this->get_ACF_field_type( $field_name, $source_ACF_post_id );
	
    // Check if field already has previous value stored in database
    $value_ids = $wpdb->get_col( $wpdb->prepare( $query, $new_post_id, $field_name, $field_name ) );

    if( $value_ids ) {
        $this->update_imported_value( $field_name, $field_type, $value_ids, $field_translation );
    } else {
        $this->insert_imported_value( $field_name, $field_type, $job->original_doc_id, $source_ACF_post_id, $destination_ACF_post_id, $field_translation, $new_post_id );
    }
}

Best Practices forCustomizing WordPress Plugins

Follow along at http://iandunn.name/customizing-plugins

Interaction

Overview

The Problem

Collaborate With the Developer

Extend Without Modifying

Extend Without Modifying

Extend Without Modifying

Using Custom Hooks

Using Custom Hooks

Tagregator

Using Custom Hooks

Tagregator

Tagregator - Vine Media Source

Using Custom Hooks

Basic Google Maps Placemarks

Using Custom Hooks

Basic Google Maps Placemarks

Using Custom Hooks

Snippet

Using Custom Hooks

CampTix

Using Custom Hooks

CampTix Network Tools

Using Custom Hooks

CampTix

Using Custom Hooks

CampTix Network Tools

Using Custom Hooks

Overriding Their Core Callbacks

Overriding Their Core Callbacks

Google Authenticator

Overriding Their Core Callbacks

Google Authenticator - Per User Prompt

Overriding Their Core Callbacks

Google Authenticator

Overriding Their Core Callbacks

Google Authenticator - Per User Prompt

Overriding Their Core Callbacks

Google Authenticator - Per User Prompt

Overriding Their Core Callbacks

Google Authenticator - Per User Prompt

Overriding Their Core Callbacks

Google Authenticator - Per User Prompt

Overriding Their Core Callbacks

Adding Custom Hooks

Adding Custom Hooks

WPML

Adding Custom Hooks

ACF-WPML Helper

Takeaways

Additional Resources

Articles, videos, etc

Plugin Examples Used

Q&A

Any questions / comments / tips?

Best Practices for
Customizing WordPress Plugins

Follow along at
http://iandunn.name/customizing-plugins