A legacy WordPress codebase is one where nobody can predict what a change will break. Age is not the problem. The absence of a measurement is. This guide is about producing those measurements first, then replacing code in an order where every step is reversible.
The sites in question are recognisable: built somewhere between 2015 and 2020, one classic theme with a functions.php that grew past two thousand lines, a handful of custom plugins with no upstream repository, and a wp_options table nobody has looked at since launch. They usually still work. What has stopped working is the ability to change them safely.
WordPress 7.1.1 shipped on 17 September 2026. The gap between that and a 2018 stack is rarely about core. It is about the PHP version underneath, the scripts the theme enqueues, and a database that has been accumulating rows from plugins that were removed years ago.
1. Defining the legacy debt
Start with the numbers you can read off a running site, not with an opinion about the code.
The PHP floor and the PHP recommendation are different things. WordPress trunk still sets $required_php_version = '7.4' in src/wp-includes/version.php. The requirements page recommends PHP 8.3 or greater and MariaDB 10.11 or MySQL 8.0. So core will run on 7.4, and running on 7.4 means running unpatched: php.net’s end of life list puts 7.4 at 28 November 2022, 8.0 at 26 November 2023 and 8.1 at 31 December 2025. As of today the branches still receiving fixes are 8.2, 8.3, 8.4 and 8.5, and 8.2 drops out of security support on 31 December 2026. Measured against this update on 20 September 2026, a migration plan that targets 8.2 has about three months of runway. Target 8.3 or 8.4.
Collect deprecations from production, without WP_DEBUG. This is the part most audits get wrong. Core fires do_action( 'deprecated_function_run', ... ) in _deprecated_function() before it checks WP_DEBUG, and only the trigger_error() call is gated. The same holds for deprecated_hook_run, deprecated_argument_run, deprecated_file_included, deprecated_class_run and deprecated_constructor_run. So a small mu-plugin gives you a real inventory from live traffic with nothing on screen:
<?php
// mu-plugins/deprecation-log.php
$hooks = array(
'deprecated_function_run',
'deprecated_hook_run',
'deprecated_argument_run',
'deprecated_file_included',
'deprecated_class_run',
'deprecated_constructor_run',
);
foreach ( $hooks as $hook ) {
add_action(
$hook,
static function () use ( $hook ) {
error_log( $hook . ' ' . wp_json_encode( func_get_args() ) );
},
10,
4
);
}Leave it running for a full business cycle. A weekly import job and a quarterly report page will hit deprecated code paths that no crawl of the front end touches.
Check whether the files are the files. wp core verify-checksums and wp plugin verify-checksums compare the installed files against the WordPress.org hashes. On a site with a decade of history this routinely finds a plugin that was patched in place by a developer who has since left. Those files are the ones that silently revert on the next update, and they belong in version control before anything else moves.
Compatibility scan with a target, not in the abstract. PHPCompatibilityWP exists so the sniffs do not flag polyfills that WordPress core already provides:
vendor/bin/phpcs -p wp-content/themes wp-content/plugins \
--standard=PHPCompatibilityWP \
--extensions=php \
--runtime-set testVersion 8.3-Without testVersion the run tells you very little. With it, you get a file list ordered by how much stands between you and the version you want.
The inventory you want at the end of week one is four columns: current PHP version, deprecation hits per endpoint, files failing checksums, and PHPCS errors per plugin. Everything after this is prioritised from that table.
2. Refactoring strategy: the strangler fig pattern
Martin Fowler’s strangler fig, first written up in 2004 and revised in August 2024, is the only rewrite strategy that keeps a revenue site online: put the new system next to the old one, route one slice of traffic to it, and let the old system shrink until there is nothing left to cut over.
WordPress gives you two natural seams for this, and both are in core.
The first is template_include. It is a filter, so a single route can be handed to new code while every other route keeps hitting the old templates. That is enough to move the contact page, the careers section or one post type onto a rewritten template with its own assets, and to move it back in one line if conversion drops.
The second is hybrid block template support. locate_block_template() in src/wp-includes/block-template.php returns early unless current_theme_supports( 'block-templates' ), and when that support is declared it only considers block templates with equal or higher specificity than the PHP template the hierarchy already found. In practice:
add_action(
'after_setup_theme',
static function () {
add_theme_support( 'block-templates' );
}
);Now a templates/page-contact.html file in the classic theme takes over exactly that route. single.php, archive.php and the rest carry on unchanged. This is the mechanism that makes “migrate to blocks” a sequence of small releases rather than one weekend with a rollback plan nobody has tested. If you have not decided between staying classic and going full block theme yet, that decision is its own piece of work, covered in classic vs block themes.
Order the slices by risk, not by enthusiasm. A good first slice is a template with real traffic, a measurable outcome, and no checkout in it. A bad first slice is the homepage, because it gives you the largest possible blast radius on the day you are least familiar with the new code.
Two rules make this survivable. Every slice keeps its own assets, so the new template does not inherit the old global stylesheet by accident. And the old code is deleted in the same release that retires it, because a dead template left in the repository will be edited by someone within six months.
3. Database modernization: the clean slate
Almost every “the database is slow” report on an old WordPress site comes down to three things, and only one of them is about size.
Autoload is the one that hits every request. Since WordPress 6.6, the autoload column no longer holds only yes and no. The Options API dev note introduced on, off, auto-on, auto-off and auto, and wp_filter_default_autoload_value_via_option_size() in src/wp-includes/option.php refuses to autoload anything whose serialized value exceeds the wp_max_autoloaded_option_size filter, which defaults to 150000 bytes. That protection applies when an option is written. It does nothing about the 40 kilobyte blob a removed plugin left behind in 2019.
Read the real list with SQL rather than a plugin dashboard:
SELECT option_name, LENGTH(option_value) AS bytes, autoload
FROM wp_options
WHERE autoload IN ('yes', 'on', 'auto-on', 'auto')
ORDER BY bytes DESC
LIMIT 25;Those four values are the ones wp_load_alloptions() treats as autoloaded. This matters, because wp option list --autoload=on --format=total_bytes in WP-CLI matches only autoload='on' OR autoload='yes'. On a site running 6.6 or later, where new options land as auto, that command reports a smaller autoload footprint than the one you are actually paying for on every page load. Use the query, or read the WP-CLI number knowing what it excludes.
Orphaned postmeta is a row count, not a mystery. Count it before you decide it matters:
SELECT COUNT(*)
FROM wp_postmeta pm
LEFT JOIN wp_posts p ON p.ID = pm.post_id
WHERE p.ID IS NULL;Rows with no surviving post are safe to delete, and you take a database dump first anyway. Meta belonging to a plugin you removed is a separate, more careful pass: group by meta_key, match the prefixes against the plugins you still run, and delete by key.
The indexes are the part nobody reads. src/wp-admin/includes/schema.php gives wp_postmeta a primary key on meta_id, a post_id key and a meta_key key prefixed to 191 characters, because utf8mb4 uses four bytes per character and the historical index limit was 767 bytes. There is no composite index on (post_id, meta_key). A query that filters on both, which is what a meta-heavy archive template does on every row, cannot use one index for both columns. On a large site the fix is a composite index added by migration, not more caching layers on top. The broader query side of this is covered in the WP_Query and the loop guide.
Two more checks belong in the same pass. Confirm every table is InnoDB, because a MyISAM table left over from a MySQL 5.1 era import locks on write and ignores transactions. And confirm the charset is utf8mb4: core picks utf8mb4_unicode_520_ci in determine_charset() when the server supports it, but a database created before WordPress 4.2 and migrated by mysqldump will still be utf8 and will still silently drop characters outside the basic plane. More detail on that pass lives in the database optimization guide.
4. Moving to modern CSS and JS
The frontend of a legacy WordPress site is usually not slow because of the framework it uses. It is slow because nothing in the theme knows what anything else enqueues.
Count your jQuery copies before you blame jQuery. Core registers exactly one: script-loader.php declares jquery-core at 3.7.1 and jquery-migrate at 3.4.1, with jquery as an alias depending on both. Multiple versions on a page come from plugins and themes that enqueue their own copy under a different handle, or that write a raw <script src> tag into the footer. wp_scripts()->queue tells you which is which in about a minute. Deregistering core jQuery and forcing a CDN copy is the change that breaks the admin; leave the core handle alone and remove the duplicates instead.
jquery-migrate is worth a separate decision. Dequeuing it is a one-liner, and if the site then throws console errors, those errors are the actual list of jQuery 1.x patterns still in your theme. That list is the scope of a migration, which is the subject of the jQuery to vanilla JS guide.
Use the loading strategy core already ships. Since WordPress 6.3, wp_enqueue_script() accepts an array in the last parameter:
wp_enqueue_script(
'site-main',
get_theme_file_uri( 'build/main.js' ),
array(),
filemtime( get_theme_file_path( 'build/main.js' ) ),
array(
'strategy' => 'defer',
'in_footer' => true,
)
);The gotcha is documented in the 6.3 dev note and implemented in WP_Scripts::filter_eligible_strategies(): core walks the dependency tree, and if any enqueued script that depends on yours is not itself delayed, your script is emitted as blocking. You can set defer on a handle, see no defer attribute in the HTML, and have nothing in the log. Core writes data-wp-strategy on the tag whenever a delayed strategy was registered, downgraded or not, so grepping for the attribute alone returns every deferred script. The downgrade signal is a tag that carries data-wp-strategy and no matching defer or async attribute. One legacy plugin enqueueing a blocking script that depends on your bundle is enough to undo the whole change.
The same file also refuses a strategy on an alias handle, which is why wp_script_add_data( 'jquery', 'strategy', 'defer' ) does nothing useful: jquery has no src.
Give the theme a build step before you argue about CSS. A legacy theme with one hand-edited style.css and no bundler has no way to ship a scoped change. Whether the output is Tailwind, CSS modules or plain CSS custom properties matters far less than being able to answer “which selectors does this template need”. Once a build exists, per-template asset loading becomes possible, and per-template asset loading is what actually moves the render path, not the choice of framework.
5. Security hardening for older sites
Legacy code is not insecure by virtue of its age. It is insecure because the surfaces it exposes were configured when the defaults were different.
The REST API cannot be turned off, and the usual snippets that claim to do it are worse than nothing. Core uses it for the block editor, Site Health and application passwords. What you can do is require authentication for everything not explicitly public:
add_filter(
'rest_authentication_errors',
static function ( $result ) {
if ( ! empty( $result ) || is_user_logged_in() ) {
return $result;
}
return new WP_Error(
'rest_not_logged_in',
__( 'REST API access requires authentication.' ),
array( 'status' => 401 )
);
}
);Then go and test the parts of the site that use it anonymously: comment forms, search blocks, contact forms built on REST endpoints and any headless consumer. On a corporate marketing site this filter is usually fine. On a site with a logged out interactive feature it will break that feature, and it is better to find out on staging.
Know what is already restricted before you add rules. The users endpoint is a common panic item, but WP_REST_Users_Controller sets has_published_posts on a collection request whenever the caller fails current_user_can( 'list_users' ), which covers logged out visitors and low privilege accounts alike. The post types it accepts are get_post_types( array( 'show_in_rest' => true ) ), not public post types, and the two sets are not the same list. So the endpoint returns authors who have published in a REST exposed post type rather than every account. Author enumeration on a corporate site is usually leaking through /?author=1 redirects and author archives, not through REST.
Application passwords are HTTPS only. wp_is_application_passwords_supported() returns is_ssl() || 'local' === wp_get_environment_type(). A legacy site still serving a mixed content admin over plain HTTP does not offer them at all, which is why integrations on those sites end up sharing a real administrator password. Fixing the certificate is the security fix; the application password is the consequence.
Replace the monitoring you cannot read. Checksum verification on a schedule, a log of deprecation hits, and file integrity alerts are worth more on a legacy codebase than a scanner that reports a severity score. The deeper hardening pass, including headers, file permissions and login surface, is in advanced WordPress security hardening. Do the plugin inventory at the same time, because every plugin you remove is a surface you stop maintaining, and the plugin sprawl teardown is the method for deciding which ones go.
6. Conclusion: don’t let the past hold you back
A legacy WordPress site is not automatically a liability. Unmanaged technical debt is, and the difference between the two is whether anyone can say what a change will cost before making it.
The sequence in this guide is deliberate. Measure the PHP gap against the php.net dates, collect deprecations from live traffic with the hooks core already fires, verify the files against checksums, then strangle templates one route at a time behind template_include or block-templates. Fix autoload and the postmeta indexes because they are on every request. Fix script loading because core gives you the mechanism and legacy plugins quietly take it away. Everything else is a preference until those are done.
If the site still runs a 2018 stack, the first deliverable is not code. It is a written inventory: PHP version, deprecation log, checksum failures, plugin list with owners, and the templates that carry the traffic. Everything in this guide is prioritised off that document.
We do this work as part of WordPress development engagements, starting with the audit rather than the rewrite. If you want the inventory before committing to anything, that is a reasonable place to begin.
