Update-Safe WordPress: Hooks Instead of Edited Core Files
Editing a theme or plugin file works until the next update silently reverts it. Here is how we find those edits and rebuild them as hooks that survive.
"It used to do this and now it doesn't." That sentence opens a lot of WordPress rescue work. Somebody needed a small change, opened the plugin's PHP file, made the change, and it worked - for four months, until the plugin auto-updated at 3am and overwrote the file. Nothing in the logs. Nothing in the change history. The feature simply stopped existing.
Why this fails the way it does
A WordPress update does not merge. It replaces the plugin or theme directory wholesale with the distributed version, so anything you typed into those files is gone, with no conflict and no record that there was ever anything to lose. That is what makes an edited file worse than a merely bad customisation: the damage is invisible and delayed, whoever made the change is usually long gone, and the person who notices is a customer.
Finding the edits before they bite
When we take over a site with unexplained behaviour, we compare the installed code against what the vendor ships. For a plugin from the WordPress.org directory the exact version is downloadable, so this is easy:
# What version is installed?
wp plugin get some-plugin --field=version
# Pull the same version from the official archive into a temp dir and diff it.
mkdir -p /tmp/pristine && cd /tmp/pristine
wget "https://downloads.wordpress.org/plugin/some-plugin.4.2.1.zip"
unzip -q "some-plugin.4.2.1.zip"
diff -ru /tmp/pristine/some-plugin /var/www/example.com/wp-content/plugins/some-plugin
# Files changed after the release date are the suspects.
find /var/www/example.com/wp-content -name '*.php' -newermt '2026-03-18' | sort
The diff is definitive when you can get the matching version. The mtime sweep is the fallback for premium plugins with no public archive: every file in a freshly unpacked release carries roughly the release timestamp, so a single PHP file dated eight months later is an edit, not a shipment. A deploy process that rewrites timestamps blunts it, but between the two they find the majority.
The other tell is an orphaned functions.php.bak or a parent-theme-old directory: fingerprints of somebody working on the server, and where you find one you find the edit.
The fix: one small plugin
Every site-specific change goes into a single-file plugin in wp-content/plugins/. Not the theme's functions.php.
People reach for functions.php because it is right there, and it is the wrong container. A theme update overwrites it like any other theme file unless you are on a child theme, and a theme switch takes it out of play entirely - the customisation is silently coupled to a design decision it has nothing to do with. A plugin survives both, and has an on/off switch, which is worth a lot when you are bisecting a white screen.
<?php
/**
* Plugin Name: Site Customisations
* Description: Every site-specific change lives here, so updates cannot revert it.
* Version: 1.0.0
* Author: example.com
* Requires at least: 6.4
* Requires PHP: 8.1
* License: GPL-2.0-or-later
*/
defined( 'ABSPATH' ) || exit;
// A filter MUST return a value -- see the harness further down.
add_filter( 'woocommerce_short_description', function ( $description ) {
if ( ! is_product() ) {
return $description;
}
return $description . '<p class="delivery-note">Dispatched within 24 hours.</p>';
}, 20, 1 );
The header block is not decoration: WordPress finds the plugin by parsing Plugin Name, and a file without it is invisible on the plugins screen. The ABSPATH line stops the file doing anything if someone requests it directly. Actions go in the same file and look the same, minus the return.
The hook vocabulary, and the two bugs it causes
add_action is "something happened, go and do a thing". add_filter is "here is a value, hand back the version you want used". Same registry underneath; the difference that matters is that a filter must return.
Both take a $priority (default 10, lower runs earlier) and $accepted_args (default 1). Those two parameters produce the two bugs we see most:
- Wrong
$accepted_args. You write a callback taking two parameters, register it with the default of 1, and the second argument never arrives. On PHP 8 that is anArgumentCountErrorrather than the silentnullolder PHP gave you - better, but it still reads as "the plugin broke the site" rather than "one number is wrong". - Wrong
$priority. Your callback runs before the thing it modifies exists - a filter registered at priority 5 that expects data another plugin adds at 10 sees nothing, every time, with no error at all.
Reasoning about hook order without a WordPress install
When hook order is in question we do not spin up a site. WordPress's filter system is small enough to reimplement, and running the real thing on the real question takes a minute:
<?php
/**
* A stand-in for WordPress's filter system: enough to reason about priority
* order and the classic callback bugs without a WordPress install.
*/
$GLOBALS['filters'] = array();
function add_filter( $hook, callable $callback, $priority = 10, $accepted_args = 1 ) {
$GLOBALS['filters'][ $hook ][ $priority ][] = array(
'cb' => $callback,
'args' => $accepted_args,
);
}
function apply_filters( $hook, $value ) {
if ( empty( $GLOBALS['filters'][ $hook ] ) ) {
return $value;
}
$extra = array_slice( func_get_args(), 2 );
$by_priority = $GLOBALS['filters'][ $hook ];
ksort( $by_priority, SORT_NUMERIC );
foreach ( $by_priority as $callbacks ) {
foreach ( $callbacks as $entry ) {
$args = array_slice( array_merge( array( $value ), $extra ), 0, $entry['args'] );
$value = call_user_func_array( $entry['cb'], $args );
}
}
return $value;
}
function show( $label, callable $run ) {
try {
printf( "%-28s %s\n", $label, var_export( $run(), true ) );
} catch ( Throwable $e ) {
$msg = preg_replace( '/\{closure:[^}]+\}/', '{closure}', $e->getMessage() );
printf( "%-28s %s: %s\n", $label, get_class( $e ), explode( ',', $msg )[0] );
}
}
/* 1. Priority decides order, not registration order. */
add_filter( 'the_price', function ( $price ) { return $price * 2; }, 20 );
add_filter( 'the_price', function ( $price ) { return $price + 5; }, 5 );
add_filter( 'the_price', function ( $price ) { return $price + 100; }, 99 );
show( 'priority 5, 20, 99:', function () { return apply_filters( 'the_price', 10 ); } );
/* 2. A filter that forgets to return wipes the value for everyone after it. */
add_filter( 'the_title', 'strtoupper', 10 );
add_filter( 'the_title', function ( $title ) { /* forgot to return */ }, 11 );
add_filter( 'the_title', function ( $title ) { return trim( $title . '!' ); }, 12 );
show( 'one callback forgot return:', function () { return apply_filters( 'the_title', 'hooks win' ); } );
/* 3. accepted_args too low: the extra argument never arrives. */
add_filter( 'the_excerpt', function ( $text, $post_id ) {
return $text . ' (post ' . $post_id . ')';
}, 10, 1 );
show( 'accepted_args = 1:', function () { return apply_filters( 'the_excerpt', 'Body', 42 ); } );
$ php hook_harness.php
priority 5, 20, 99: 130
one callback forgot return: '!'
accepted_args = 1: ArgumentCountError: Too few arguments to function {closure}()
Three lessons in three lines. The price is (10 + 5) * 2 + 100 = 130, so registration order is irrelevant and priority is everything. The title comes back as '!', not 'HOOKS WIN!': one callback returned nothing, the value became null, and everything after it worked on that nothing. And a low accepted_args is a fatal, not a shrug - change that 1 to a 2 and the same callback returns 'Body (post 42)'.
That second result is a common WordPress filter bug we get asked to fix. The symptom is "the title went blank on some pages"; the cause is one callback several plugins away with a missing return.
Removing somebody else's hook
remove_action() and remove_filter() need the identical callback and the identical priority, and both halves catch people. Removing at 10 a callback registered at 12 does nothing and reports nothing. And there is no reference to an anonymous function, so a closure registered by another plugin cannot be removed at all - that is not a trick you are missing, it is a property of the language.
<?php
// Not removable: the plugin registered an anonymous function, so there is no
// reference to pass to remove_filter().
//
// add_filter( 'the_content', function ( $c ) { return $c . $ad; } );
// Removable: a named function, removed with the identical priority.
remove_filter( 'the_content', 'vendor_append_promo', 12 );
// Removable: a class method, but only with the *same object instance*.
// Most plugins expose that instance somewhere -- find it, do not guess.
add_action( 'init', function () {
global $vendor_plugin;
if ( $vendor_plugin instanceof Vendor_Plugin ) {
remove_action( 'wp_footer', array( $vendor_plugin, 'render_badge' ), 30 );
}
}, 11 );
// Last resort for a closure: neutralise the output, not the callback.
add_filter( 'the_content', function ( $content ) {
return str_replace( '<div class="vendor-promo">', '<div class="vendor-promo" hidden>', $content );
}, 99 );
Two things to notice. The instance-method removal is wrapped in add_action( 'init', ... ) because the vendor's object usually does not exist yet when your plugin file loads - you have to wait until it is reachable. And when you register hooks from a class of your own, expose the instance through a static accessor, so the next person can build the same array( Site_Tweaks::instance(), 'method' ) reference and undo you cleanly.
Templates: child theme, never the plugin's own files
Markup changes have their own supported route. A child theme's files take precedence over the parent's, so child-theme/single-product.php overrides the parent's copy and a parent update leaves it alone. WooCommerce extends the same idea to plugin templates through woocommerce_locate_template: copy the file you want to change from the plugin's templates/ directory into child-theme/woocommerce/, keeping the path below that point identical, and WooCommerce loads yours. Editing the plugin's template file directly gets you the same result today and nothing at all after the next release.
Record the debt either way: an overridden template is a fork of that file, so when the plugin changes its own version you do not get the change. Note the version you copied from in a comment at the top, and re-diff on major upgrades.
Never let a missing dependency fatal
A customisations plugin usually leans on something else, and if that something is deactivated a bare call fatals and takes the site down - including the admin screen you would use to fix it:
<?php
add_action( 'plugins_loaded', function () {
if ( function_exists( 'WC' ) && class_exists( 'WooCommerce' ) ) {
require_once plugin_dir_path( __FILE__ ) . 'includes/shop-tweaks.php';
return;
}
add_action( 'admin_notices', function () {
if ( ! current_user_can( 'activate_plugins' ) ) {
return;
}
printf(
'<div class="notice notice-warning"><p>%s</p></div>',
esc_html__(
'Site Customisations: the shop tweaks are idle because WooCommerce is not active.',
'site-customisations'
)
);
} );
} );
That is the difference between a degraded site and a dead one: the tweaks are off, the site is up, and an administrator is told why.
When not to do this
Sometimes there is no hook at the point you need: an abandoned plugin with the behaviour you must change hard-coded mid-function and no filter anywhere near it. You can contort yourself with output buffering and string replacement, or you can fork it honestly.
If you fork, do it properly: rename the plugin so it can never be auto-updated over, pin and record the upstream version you branched from, keep the changes in version control so they can be replayed, and write down why the fork exists. That is real debt and it will need paying - but it is visible debt, a different category from an invisible edit inside a directory the update system considers disposable.
If a site you run has features that keep quietly vanishing after updates, that is exactly the WordPress plugin work we take on: auditing what was edited, rebuilding it as hooks, leaving something an update cannot touch. See how we work. Start a project, describe the symptom, and we reply within two business days.
We ship and run our own products. We build yours the same way.
Start a project