WP Dev Nest All articles
Development

Refactor the Junk Drawer: A Safer functions.php Plan for WordPress Themes

WP Dev Nest
Refactor the Junk Drawer: A Safer functions.php Plan for WordPress Themes

Photo: WordPress theme developer refactoring PHP code on laptop, via macraes.com

Every WordPress theme developer has seen it: a functions.php file that starts with an enqueue call and ends with a custom post type, three shortcodes, an admin dashboard widget, a Google Analytics snippet, and a comment that says 'do not delete.' It works, technically. It is also the place where bugs hide, hooks collide, and the next developer loses an afternoon.

The junk drawer is not a moral failure. It is what happens when a theme ships fast and every new request gets appended to the same file. The fix is not to rewrite everything at once. The fix is a controlled refactor with clear ownership rules and a test plan.

Decide what belongs in the theme

The theme owns presentation. Templates, template parts, styles, editor styles, theme supports, navigation locations, and front-end assets that are tied to the design belong in the theme. If removing the code would make the site look different, it is probably theme territory.

The plugin owns behavior and data. Custom post types, taxonomies, shortcodes, blocks, REST endpoints, integrations, admin settings, and business logic belong in a plugin or a must-use plugin. If the code should survive a theme switch, it does not belong in the theme. That rule alone will clean up most of the mess.

There is a gray area for site-specific code. A client's custom post type might be small, but it is still data. Put it in a site-specific plugin or mu-plugin. A theme-specific block style is presentation and can stay with the theme. A tracking script is neither; it belongs in a small integration plugin or a tag manager, not scattered across template files.

Map the drawer before you empty it

Before moving anything, create an inventory. Search functions.php for add_action, add_filter, add_shortcode, register_post_type, register_taxonomy, enqueue calls, and direct database queries. Group the findings into categories: assets, hooks, custom post types, shortcodes, admin changes, integrations, and dead code. Note which functions are called from templates and which are hooked to WordPress.

Check for collisions. Two functions with similar names, multiple enqueue callbacks, or hooks added inside other hooks are red flags. Also look for code that assumes a specific theme or plugin is active. That assumption will break during the refactor if you are not careful.

Use a must-use plugin loader

For site-specific behavior, a must-use plugin is a good home because it loads automatically and cannot be deactivated by accident. Create a small mu-plugin with a loader file that includes modules from a subdirectory. Keep each module focused: one for post types, one for shortcodes, one for admin tweaks, one for integrations. The loader should document what it loads and why.

For reusable behavior that ships with the theme, use a plugin instead. If the client might switch themes later, the custom post type should not vanish. That is not a theoretical concern; it is a support ticket waiting to happen.

Refactor in a safe order

Start with version control and a staging copy. Never refactor directly on production. Freeze new feature work for the duration of the refactor so you are not chasing a moving target.

  1. Move pure utility functions into an includes directory with clear file names. Keep the same function names at first so templates do not break.
  2. Move enqueue logic into one file and verify the asset load order. Check the front end and the block editor separately.
  3. Move custom post types and taxonomies into a plugin or mu-plugin. Flush permalinks only after confirming the registrations run on init.
  4. Move shortcodes and blocks. Test each shortcode in existing content, including old posts that may use attributes you forgot about.
  5. Move admin customizations last. Admin code often depends on screen IDs, user roles, and plugin order, so it needs the most careful testing.
  6. Delete dead code only after a full backup and a search across templates, plugins, and the database for references.

Keep a changelog. If a hook name changes, document it. If a function is deprecated, add a wrapper that calls the new implementation and logs a notice during development.

Document the hooks you expose

A refactor is a good time to make the theme's extension points intentional. Add docblocks for custom actions and filters. State what arguments are passed, when the hook fires, and whether it is safe to call before or after setup. This is especially useful for client sites where another developer will eventually add features. Undocumented hooks are just rumors.

Tests to run before deployment

Run the site with WP_DEBUG and WP_DEBUG_LOG enabled on staging. Fix every notice and warning your refactor introduces. Run PHP_CodeSniffer against the theme and plugin code if that is part of your workflow. Then do a smoke test: homepage, a single post, an archive, a search results page, the 404 page, the contact form, and any custom post type archive.

Test the block editor. Open and save a post with reusable blocks, shortcodes, and custom fields. Check the REST API for the post types you moved. Verify cron events still run, especially if you moved code that schedules events. Test with a non-admin user and with plugins that interact with your custom post types.

Finally, compare the database and file permissions before and after. A refactor should not change either. If it does, stop and find out why.

The goal is not a perfect architecture. The goal is a theme that another developer can open without needing a machete. Split the drawer into labeled boxes, document the hooks, and test the paths users actually take. That is how a functions.php refactor earns its keep.

All Articles

Related Articles

Staging Is a Dress Rehearsal, Not the Show: Five WordPress Deploy Gaps

Staging Is a Dress Rehearsal, Not the Show: Five WordPress Deploy Gaps

Overlays Don't Fix Bad Markup: A 2026 WordPress Accessibility Reality Check

We Tracked Every Dollar Across 12 Client Builds — Premium Themes Aren't the Bargain You Think

We Tracked Every Dollar Across 12 Client Builds — Premium Themes Aren't the Bargain You Think