The Right Way to Customize a WordPress Plugin

Video: I presented on this topic at WordCamp Dayton 2014.

It’s very common for developers to customize and extend existing plugins to fit their own needs, which is one of the great advantages of using open-source software. They often do it by making their changes directly to the plugin, though, which creates a security vulnerability and becomes a maintenance hassle.

If you hack a plugin to make your changes, then you create a situation where, in order to upgrade, you have to go through an annoying process of manually diff’ing your version against the canonical one and then syncing them up in both directions. You could make it a little easier by using version control to create a patch against the canonical source, and then refresh it every time an update is released, but it’s still a pain, and developers rarely go to the trouble of doing that, so they miss out on security patches and new features.

Collaborate With 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. If they’re open to it, then you can send them a patch with your changes. 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.

The developer may not like the idea, though, or it may not line up with their vision for the plugin, so that won’t always work. There are still plenty of options, though.

Extend Without Modifying

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. In this case, you can simply write a separate plugin that runs alongside the plugin you’re customizing.

You can see a real-world example of this by looking at the code for Google Authenticator – Encourage User Activation.

Using Custom Hooks

If you do need to change or remove functionality from the plugin, though, there’s a much better way that just hacking it, and it’s something you’re already familiar with: hooks.

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.

Unfortunately, most developers haven’t learned to 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 Callbacks

The plugin you want to customize integrated with WordPress by registering callback functions for Core hooks. So, you can simply remove their callbacks, and replace them with your own. 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.

If you’d like to study a real-world example of this method, check out Google Authenticator – Per User Prompt.

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

If it’d be too much work to replace their Core hook callbacks with your own, you could hack the plugin directly, but instead of putting all your changes into it, simply add the custom hooks that you need, and then put the rest of your functionality in a separate plugin.

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.

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.

51 thoughts on “The Right Way to Customize a WordPress Plugin”

  1. Found this from the Child Plugins thread on WP Ideas.

    I’ve been looking for some sort of functionality like a child plugin but have come to the realization, like you, that hooks and filters are the best way. That doesn’t solve the problem for the user end like you indicated. Woocommerce is a great example of a plugin that allows overrides. You can copy files from the plugin directory to a directory in your theme, and the plugin will use the theme file instead of the plugin file. They also have hooks and filters to make customization easy as well.

    This is a good article, but I’m still convinced that an overriding feature, without modifying the original plugin, would be ideal, at least in the cases I’ve seen.

    Reply

    • Is WooCommerce doing that for template files, or for any file in the plugin?

      For template files, I agree that plugins should let them be overridden by the theme, and I have my plugin skeleton setup to do that. But for overriding the actual behavior of a plugin, I still think that hooks are the best way to go.

      If a plugin allowed it’s regular files to be overriden (via something similar to locate_template()), then that could easily break when the plugin changes versions, etc. Another approach would be to make all functions “pluggable” like Core does with some things, but that’d be impractical for every function in a plugin. I think that being able to unhook specific functions and filter the results of others is the cleanest and most precise way to modify a plugin.

      Reply

      • I think it would only be for template files for WC.

        I agree with you that hooks and filters would be the way to go. Communicating with the developer seems like the best solution at this point, if there are none built in.

        Reply

        • Super late answer but yes, you can add a woocommerce.php and override the default plugin on top of being able to overwrite templates. Plugin authors should take notes.

          Reply

  2. How To Extend A WordPress Plugin Without Losing Your Changes

  3. Extending Your WordPress Plugin | ClarkWP WordPress Magazine

  4. Wordpress Plugin Conflict Mayhem: How to Remove Damaging WP Plugins and Identify Junk Plugins - Great Website Plans

  5. Hi Ian,

    I have a question concerning customize WordPress plugins. I have a website that has 8-9 plugins that had been customized in the plugins folders. But now I can’t update those plugins since it will remove all the modified files in the plugins folder. Is there a faster way to find those code I had modified in the plugins folder and put them in the theme folder so that I can update the plugins periodically.

    Thanks,
    John

    Reply

    • Hi John, the best way to find your modifications is with a diff tool like DeltaWalker (OS X) or WinMerge (Windows). It’ll let you compare the two folders side-by-side to see any differences.

      I wouldn’t recommend putting your modifications in your theme, though; that’s a bad practice for many reasons. Instead, you can create a functionality plugin.

      Reply

    • The Wordfence plugin can scan the plugin files and compare them to the WordPress plugin db and find the things that have changed.

      Reply

  6. Hello, Ian

    Long thinking and reading information how integrate ability extends themes.
    In result i create custom function, that receive params and include template file, but file path may be rewrited by apply_filters().
    Then user can create plugin, add hook into “template file path”, and render it template.

    Reply

  7. Hi,

    I have developed a child plugin solution that brings WooCommerce’s way of template overrides into separate plugins. Thus your overrides are save from being overwritten by theme updates. And they don’t have to be built-in like WooCommerce is in many themes. Additionally, my solution allows you to put the overrides into the theme’s directory, as well (like WooCommerce does in /shop/).
    Those child plugins can also have special CSS loaded after the built-in CSS and a functions.php that is loaded before the parent plugin’s functions.php. Thus you can even override functions add action and filter hooks without putting them into the theme’s or the parent plugin’s directories.

    My article: http://www.hinnerk-altenburg.de/weblog/child-plugins-for-wordpress-child-theme-for-plugins/
    Installable example plugins: https://github.com/hinnerk-a/wp-plugintheming

    I am looking forward to your feedback!
    Thanks,
    Hinnerk

    Reply

    • It doesn’t look like there are any custom hooks in there, and you’d have to remove everything up the stack to ob_callback() if you wanted to override their callback, which would be painful.

      I’d recommend reaching out to the developer and explaining what you’re trying to do, and ask them to add some custom filters/actions that would allow you to do it.

      Reply

  11. ¿Plugins hijos o dependientes? – El modo correcto de personalizar plugins | Ayuda WordPress

  12. Thank you so much for explaining how to properly modify plugins. My developers do this all the time but I never truly understood what they are doing. Props to you for sharing the knowledge!

    Reply

  13. I’ve found a useful pattern to patch any plugin:
    -find the function you need to modify inside the plugin directory
    -in theme (child) file functions.php use the following:


    if ( function_exists('my_plugin_function') ){
    remove_action ('CALLED_HOOK','my_plugin_function');
    add_action ('CALLED_HOOK','my_NEW_plugin_function');
    }
    else{
    add_action( 'admin_notices', 'my_plugin_patch_error' );
    }
    function my_plugin_patch_error() {
    $class = 'notice notice-error';
    $message = __( ' plugin patch (functions.php line ...) not workng any longer');
    printf( '%2$s', $class, $message );
    }
    function my_NEW_plugin_function(){
    //modified function here
    }

    In this way you will get notified in admin area whenever the function patched does’nt exist any longer so that you can review the code and eventually replace the patch

    Reply

    • This solution worked perfect! Thank you, Andrea Somovigo, this is going to come in handy for so many jobs in the future now!!!

      Reply

  15. [WordPress] 開發外掛時初始化（Initial）與進入點（Entry Point）的幾個做法 - 一介資男

  17. Extender un Plugin de WordPress con Código y Funciones Sin Perder Tus Cambios

  19. Hello Ian,

    I tried to edit a plugin of the website of a friend.
    I was almost done but when I saved the last changes everything blacked out. Now I’m only getting blanc pages with everything on the website and admin. She is in a meeting right now, so I’m hoping to fix it myself. Can I do that without accesing the FTP?

    I hope you cant help me.

    Kind regards,
    Iris

    Reply

  20. That is very interesting, thanks a bunch! I think, I will go for a plugin on the side. I will also create my internal document so I know what I would need to fix in case something goes wrong with an update!

    Thanks again

    Reply

  21. Hello,

    I am facing a scenario in which plugin developer is using mvc framework and there is no hook or filter modify the view without directly modifying the plugin which is not acceptable at all. Can you suggest anything in this case?

    Reply

  22. Adsense Auto Ads Complete Tutorial [including AMP Ads]

  23. How to Add OneSignal AMP Push on WordPress AMP by Automattic

    • Hey Chada. I haven’t used it, but it seems like it’s basically a graphical interface for editing an mu-plugin; analogous to the CSS editor built into Core. That’s not the kind of workflow that I personally prefer, but I think it’s a valid choice, and is probably a good approach for a lot of people.

      Reply

  26. 40+ WordPress Tutorials For Beginners To Learn Basic & Advanced Techniques – Create WP Themes

  27. 40+ WordPress Tutorial For Developers & Beginners To Learn Basic & Advanced Techniques – Create WP Themes

  28. [WordPress] 開發外掛時初始化（Initial）與進入點（Entry Point）的幾個做法 | 一介資男

  29. I have a case where client wants me to make changes in plugin through child theme funcations.php file, I’m confused how I can go about this? He wants to change and modify the text in plugin setting page through child’s fn.

    Reply

Leave a Reply to Hinnerk Altenburg Cancel reply

Your email address will not be published. Required fields are marked *