If you’ve created a plugin in the WordPress repository, you’ve likely been at a point where you need to modify or remove a publicly accessible function.
By publicly accessible I mean:
Any function or hook that could be used by other developers modifying your plugin’s functionality.
If developers rely on these functions, how do you make that change without taking down users’ sites?
Unfortunately, WordPress doesn’t provide much information around the deprecation process (declaring that certain code is no longer supported by you, the developer).
Deprecating a function or hook is inevitable
You need to be very cautious when making a breaking change to your plugin.
When making a breaking change, be sure to:
- Utilize a phased approach
- Notify your users of the change
- Provide a migration or upgrade path
- Give users time to migrate or remove the functionality
I’ve spent the last few months working out the best approach for deprecating functions and hooks in a plugin.
Here’s my process in 4 steps:
Step 1: Plan Approach and Inform Users
When you have decided that it’s impossible to avoid making this breaking change, be very intentional in how you go about it.
Be forward and upfront with your users in versions before you make the change.
You’ll want to give them time to notice the deprecation and time to make the necessary changes to either remove their modifications or migrate functionality to a new function.
Select a version (at least two releases out) that you want to remove something and don’t make the proposed changes until that release. The function or hook should be marked as deprecated until the change is released.
Breaking changes should not be made swiftly or recklessly and this waiting period will ensure that you’re not moving too quickly.
Step 2: Document the Planned Removal
It’s important to make sure that you document future deprecated functions.
As developers work on extending your code, they’ll see these notices and won’t start using functions and hooks that are planned to be deprecated.
To do this consistently, you should add a @deprecated note to the function or hook’s docblock with an accompanying @todo describing when it will be officially removed:
Step 3: Add _deprecated_function() calls to Functions & Hooks
You can utilize the _deprecated_function() method to bring attention to functions that are going to be changed or removed soon.
The function runs an action that gathers some information around the function currently being used, and outputs an error in the logs.
For example, when deprecating a function, add it as early as possible within the function:
Now, whenever someone (another developer) uses that function, WordPress will automatically trigger an error in the log that will read:
Function removed_function is deprecated since version 1.2.3! Use new_function instead.
The same can be done with any hooks that you are removing or modifying the name of:
Step 4: Create a Deprecated Functions File
Create an alternate deprecated.php If you want to remove the functionality from the primary codebase and organize it better so functions are easier to remove during release prep.
This gives another indication to developers that the function is likely to be removed in a future release and gives you an easy location to look for functions to remove.
In Summary
Now that you have deprecated the function or hook, you can remove it in the future because you have given other developers & site owners notice beforehand.
Breaking changes should not be handled lightly, but can be done thoughtfully and methodically.
In short:
- Notify your users of an upcoming breaking change
- Document the changes in your codebase
- Deprecate functions or hooks
- Keep the deprecated functions around
Here are some additional resources if you want to dig deeper:
I hope this helps clear up the process for you as you keep iterating on your plugin. It’s taken me a while to come up with a process that I’m comfortable with that keeps users informed.
The true key is just being upfront with your users. Communicate early and often.
