Choosing and Managing Plugins and Themes

A plugin is PHP code (often with JavaScript, CSS and blocks) that adds behaviour through hooks: a post type, a settings screen, a REST route, a block, a spam filter. Any number of plugins can be active at once, and each one runs on every request that loads WordPress. A theme controls presentation: templates, styles, patterns and, for block themes, theme.json. Exactly one theme is active per site, optionally a child theme on top of a parent.

The split matters when choosing: content and features that must survive a redesign (book records, shortcodes, custom roles, blocks the editors rely on) belong in plugins. The theme review rules call this "plugin territory" and do not allow directory themes to register post types, blocks, shortcodes or roles. A theme that does so locks the content to that theme. See Themes Overview and Page Builders and Commercial Themes for the theme side of that decision.

Code reaches a site from four kinds of source:

Source: WordPress.org Documentation: Manage Plugins

Every plugin page in the directory shows the same set of facts in its sidebar, and themes show a similar set. None of them proves quality alone; together they show whether a plugin is maintained and used.

Source: Plugin Handbook: How Your Plugin’s readme.txt Works

Before adding a plugin to Lumen Press, an administrator also checks three things that the listing does not show:

Older books separate free plugins from "premium" ones. The distinction that matters today is how the directory guidelines treat each model:

Source: Plugin Handbook: Detailed Plugin Guidelines

All WordPress plugins and themes that run on the site are derivative works of GPL-licensed software. Commercial vendors usually license their PHP under the GPL and sell access to downloads, updates and support rather than the code itself.

There are three routes, and all three end with the files in wp-content/plugins/<slug>/ or wp-content/themes/<slug>/:

DISALLOW_FILE_MODS removes all three dashboard routes, the update buttons and automatic updates of plugins, themes and core (internally, wp_is_file_mod_allowed() returns false). DISALLOW_FILE_EDIT only removes the theme and plugin file editors. One older book describes DISALLOW_FILE_MODS as only disabling updates, which understates it.

The same tasks with WP-CLI, against the Compose stack of Local Development Environments (prefix each command with docker compose run --rm cli there):

Source: WP-CLI Commands: wp plugin install

wp plugin verify-checksums compares every file with the checksums WordPress.org publishes for that version and prints Success: Verified 2 of 2 plugins. when nothing was modified. It is the quickest way to find tampered directory plugins after an incident; it cannot check commercial or private plugins. Themes are installed the same way with wp theme install <slug> --activate.

Since WordPress 6.5, a plugin can declare that it needs other plugins with the Requires Plugins header: a comma-separated list of WordPress.org-style slugs (lumen-catalog, not lumen-catalog/lumen-catalog.php). One older book says plugins cannot depend on each other; that was true of core until 6.5, when this header was added.

lumen-reviews adds reader reviews to the catalogue, so it cannot work without lumen-catalog:

Source: Plugin Handbook: Header Requirements

The dependency is a plain slug: lumen-catalog is the canonical main plugin of Lumen Press (header Version: 0.1.0, Requires at least: 6.9, Requires PHP: 7.4, Text Domain: lumen-catalog). With lumen-catalog inactive, activation of lumen-reviews fails, in the dashboard and in WP-CLI alike, because both go through activate_plugin():

Source: Code Reference: activate_plugin()

On the Plugins screen, WP_Plugin_Dependencies adds a "Requires:" line to the dependent and a "Required by:" line to the dependency, disables Activate on the dependent until its dependencies are active, and hides Deactivate and Delete on a dependency while dependents are active (and Delete while any dependent is installed). On Add New Plugin, Install Now is disabled for a plugin whose dependencies are missing, and the card links to each dependency. Nothing is installed automatically: the administrator installs each dependency.

Order matters for WP-CLI, which processes the arguments left to right:

Source: WP-CLI Commands: wp plugin activate

Listing the dependency first (wp plugin activate lumen-catalog lumen-reviews) activates both. The same applies to wp plugin activate --all, which may need to run twice when a dependent sorts before its dependency.

The guard only protects activation and the Plugins screen. wp plugin deactivate lumen-catalog succeeded on the test site while lumen-reviews stayed active, leaving the dependent running without its dependency. A dependent must therefore still check at runtime (function_exists(), class_exists(), a version constant) before calling into the dependency.

Limits of the feature, as documented in the 6.5 announcement:

A must-use plugin is a PHP file in wp-content/mu-plugins/ (WPMU_PLUGIN_DIR, with WPMU_PLUGIN_URL for its URL). WordPress loads every .php file directly in that directory, in alphabetical order, on every request and before regular plugins, then fires muplugins_loaded. Must-use plugins cannot be deactivated from the dashboard, appear only under Plugins > Must-Use, get no update notices or auto-updates, and never run activation, deactivation or uninstall hooks. Removing the file is the only way to turn one off.

That makes them the right place for site policy that must not be switched off by accident, such as the update rules of Lumen Press. The update filters also belong here rather than in wp-config.php, where they run before plugins and conflict with WP-CLI:

Source: Advanced Administration Handbook: Must Use Plugins

Files in subdirectories are not loaded. A must-use plugin kept in its own folder needs a loader file at the top level:

Source: Advanced Administration Handbook: Must Use Plugins (Caveats)

The test site had mu-plugins/lumen-observability/lumen-observability.php, which adds an X-Lumen-Env response header from send_headers. Before the loader existed, has_action( 'send_headers' ) was false and the header was missing. With the loader in place:

Source: WP-CLI Commands: wp plugin list

Must-use plugins run on every site of a Multisite network. Because they always run and are not listed with the other plugins, a broken one takes the whole site down and a malicious one is easy to miss; keep them few, short and under version control.

Drop-ins are different: single files directly in wp-content/ with reserved names that replace a part of core. advanced-cache.php (loaded when WP_CACHE is true), object-cache.php, db.php, db-error.php, maintenance.php, php-error.php, fatal-error-handler.php and, on Multisite, sunrise.php (with SUNRISE) and the blog-*.php messages. They appear under Plugins > Drop-ins (wp plugin list --status=dropin), are installed by caching or database plugins, and are covered in Performance and Caching.

Since WordPress 5.5, each plugin row on Plugins > Installed Plugins has an Enable auto-updates link in the Automatic Updates column, and bulk actions toggle several plugins at once. For themes, the link is in the theme details modal under Appearance > Themes. The choices are stored in two options, auto_update_plugins (plugin files such as two-factor/two-factor.php) and auto_update_themes (theme slugs).

The checks run from WP-Cron: wp_version_check, wp_update_plugins and wp_update_themes are scheduled twice daily, and wp_maybe_auto_update performs the updates. A site with broken WP-Cron (see WP-Cron and Scheduled Tasks) never auto-updates. After each run, the site’s admin email receives a summary of successful and failed updates; auto_plugin_update_send_email and auto_theme_update_send_email turn those emails off.

Source: WP-CLI Commands: wp plugin auto-updates enable

update is available because two-factor was installed at 0.16.0 while 0.17.0 is current. lumen-catalog and lumen-reviews show none even though they are not in the directory: WordPress simply received no update for them.

The filters always win over the toggles:

Source: Code Reference: auto_update_{$type}

When a filter forces the result, the Plugins screen shows "Auto-updates enabled" or "Auto-updates disabled" without a link (core calls wp_is_auto_update_forced_for_item()). WP-CLI does not: its auto_update column reports the stored option. On the test site, with the policy plugin above active, akismet was listed as off although wp_is_auto_update_forced_for_item( 'plugin', null, $item ) returned true, and twentytwentyfour was listed as on although the theme filter returns false. Audit a site’s real update behaviour with the filters, not the column.

WordPress.org can also push a security release to every site that runs a vulnerable plugin, independent of the toggle; this is rare and decided by the Plugins Team. The full update model (core majors and minors, translations, WP_AUTO_UPDATE_CORE, version-control checkouts) is in Updates and Auto-Updates.

Two releases made updates safer:

The limits follow from how it works: inactive plugins are not checked, themes are not checked, errors that are not fatal (a broken layout, a JavaScript error, a failing checkout) are not detected, and a blocked loopback request (see Site Health) makes the check unreliable. Database changes made by the new version’s upgrade routine are not undone. Backups and a staging copy are still needed; see Backups and Disaster Recovery.

The WordPress 7.1.3 package ships two plugins and three themes, all inactive except the default theme:

Source: WP-CLI Commands: wp theme list

Core updates do not put them back once deleted: update-core.php copies a bundled plugin only when the site is upgraded from a version older than the one that first bundled it (WordPress 2.0 for Akismet). Deleting them on an existing site is safe and recommended when they are not used. The older default themes (Twenty Twenty-Four, Twenty Twenty-Three) can also go, keeping one default theme as a fallback.

Source: Plugin Handbook: Uninstall Methods

lumen-reviews ships an uninstall.php:

Source: Plugin Handbook: Uninstall Methods (uninstall.php)

The difference between the two WP-CLI commands, on the test site:

Source: WP-CLI Commands: wp plugin uninstall

wp plugin delete left the option behind; wp plugin uninstall removed it. Many plugins deliberately keep their data on delete (or ask in their settings), so that a reinstall does not lose content; check the plugin’s documentation before relying on either.

An inactive plugin is not harmless. Its files are still on the server, and a vulnerable file that can be requested directly by URL remains exploitable. The hardening guide’s advice is to delete plugins that are not in use, not just deactivate them.

Themes follow the same rules with two differences: the active theme cannot be deleted, and a parent theme must stay installed while a child theme that uses it is active.

Source: WP-CLI Commands: wp theme delete

Switching themes leaves content in place but can lose presentation: Customizer settings (theme mods) are stored per theme, widgets of a classic theme move to Inactive widgets, and templates edited in the Site Editor (wp_template posts) belong to the theme they were made for. Child themes are covered in Child Themes.

The rules the Lumen Press team applies, which work for most sites: