First, try to submit a support request to the plugin developer so they patch the plugin for you. In some instances, however, we may need to create a long-standing patch for a plugin. We should only do so in cases where our needs are extremely specific.

Then, try alternates. Is there another plugin that will work better for your purpose? Can you write custom code or similar to get what you need? Is there literally any alternative to manully hand-patching the plugin?

Then, try alternate ways of patching directly. If it’s a customization you need in a JS file, dequeue the original and enqueue the modified version. Try to override a PHP class method or function. Check out the plugin filters and whether those can be easily overridden.

Only as an absolute last resort should you attempt patching a WordPress plugin directly.

Workflow

Consider creating a repository for your patched plugin version. This will allow you to track changes separately and maintain a clean history of the plugin changes.

Add “Update URI: False” to the plugin main file. This prevents your plugin from being updated through the admin, thus potentially wiping your changes.

Document why you made the patch.

Add steps to test and verify the plugin change to your project’s README, QA instruction, and everywhere else possible. It’s never too much communication – anywhere that the plugin patch can be noted, please note it. It should be made very, very clear why and where exactly you modified things.

Create a Git Patch

Generate a

git patch⁠

of your plugin changes

Put the git patch into a directory /patches in your plugin folder

Add Self-Updating Script

The self-updating script is optional. It will get the latest version of your plugin from the repository, and then attempt to re-apply your changes on top of the latest.

Open Cacher to get the self-updating bash script - guid:34d76d2077e2357bed88

Put

update.sh⁠

into the root or the plugin folder (root is suggested as it is more visible)

Replace all instances of wp-security-audit-log with your plugin name (or update the cacher script so it is more generic)

Run bash

update.sh⁠

to automatically get the latest version of the plugin and re-apply your patched changes

Hope against all hope that there are no merge conflicts. You will still have to resolve those manually 🙃

Examples of Patches

These patch examples are a good way to evaluate your situation and whether you should be patching or not.

⁠

pen.org⁠

– ACF needed patched as it was causing 502 errors on Pantheon on an extremely large site. There was no workaround for patching the plugin directly as the filters were not exposed. There was also no alternate path to getting this to work either as the necessary filters were not exposed.

Example of the pen.org patch⁠

⁠

Indeed - WP Security Audit Log (no link, you’d need access to their Gitlab and that is a whole process). We created a semi-extension of the base plugin. The extensive nature of the extension required that any update to the base plugin be handled very carefully. So we created a separate repository to house the base plugin, with “Update URI: false” enabled so that no one ever accidentally updated the base plugin without testing. We also included the bash script as an easy way to remember to update things.

Miscellaneous WordPress Notes

Helpful Links

Training Sites

WordPress Community at Kanopi

Patching WordPress Plugins

Workflow

Create a Git Patch

Add Self-Updating Script

Examples of Patches

Want to print your doc?
This is not the way.

Try clicking the ⋯ next to your doc name or using a keyboard shortcut (

CtrlP

) instead.