6 Hook and filter reference

6.1 Hook reference overview

Hooks let plugins alter discovery payloads, download behavior, installation steps, automatic decisions, and notifications. This part groups them by phase. Exact signatures appear on developer.wordpress.org.

How it works

Discovery uses pre_set_site_transient_* and related filters. Download and install use upgrader_pre_download and the install_package() filters. Automatic updates use auto_update_{$type}, pre_auto_update, and automatic_updates_complete. Email and filesystem hooks refine behavior. Cross-reference §6.2 through §6.8 for tables.

Process flow

1. WordPress reaches a hook point.
2. Registered callbacks run in priority order.
3. Filters return values; actions perform side effects.
4. Return values may abort steps with WP_Error.

Reference

Category	Section
Discovery	§6.2
Download and install	§6.3
$hook_extra shapes	§6.4
Automatic updater	§6.5
Core policy	§6.6
Notifications	§6.7
Cache and filesystem	§6.8

Developer resources

• Hooks overview: actions and filters — introduction to the hook system.

---

6.2 Discovery hooks

These hooks alter or observe transient payloads before they persist.

How it works

pre_set_site_transient_update_plugins, pre_set_site_transient_update_themes, and pre_set_site_transient_update_core let your code change the value about to be saved. Related site_transient_update_* filters apply when WordPress reads transients. Third-party hosts use update_plugins_{$hostname} and update_themes_{$hostname} (§1.8).

Process flow

1. A check function builds a payload.
2. pre_set_* filters run.
3. WordPress saves the transient.
4. Readers apply site_transient_* filters when loading the transient.

Reference

Hook	Type	Parameters	Notes
pre_set_site_transient_update_plugins	filter	object	Alters plugin update transient before save
pre_set_site_transient_update_themes	filter	object	Alters theme update transient before save
pre_set_site_transient_update_core	filter	object	Alters core update transient before save
site_transient_update_plugins	filter	object	Filters the read value
site_transient_update_themes	filter	object	Filters the read value
site_transient_update_core	filter	object	Filters the read value
update_plugins_{$hostname}	filter	varies	Third-party plugin metadata
update_themes_{$hostname}	filter	varies	Third-party theme metadata

Developer resources

• pre_set_site_transient_{$transient} filter reference — dynamic hook family.

---

6.3 Download and installation hooks (upgrader_pre_download and install_package() hooks)

upgrader_pre_download runs before HTTP download. Four filters run inside install_package() around file operations.

How it works

upgrader_pre_download fires in WP_Upgrader::download_package() before download_url(). Return a local filesystem path string to substitute the remote download entirely, false to proceed normally, or WP_Error to abort. If the filter returns WP_Error, install_package() hooks do not run.

Inside install_package(), upgrader_pre_install runs before file operations; upgrader_source_selection adjusts the unpacked path; upgrader_clear_destination gates clearing; upgrader_post_install runs after files are in place (plugin reactivation happens in the plugin upgrader path). Returning WP_Error from applicable filters aborts the step.

Process flow

1. The download step evaluates upgrader_pre_download.
2. Unpack runs.
3. upgrader_pre_install executes.
4. upgrader_source_selection adjusts the source path.
5. upgrader_clear_destination gates the destination clear.
6. upgrader_post_install executes.
7. The upgrader_process_complete action fires after processing (see §6.4 for the payload shape).

Reference

Hook	Type	Parameters	Notes
upgrader_pre_download	filter	bool or string or WP_Error, string, WP_Upgrader, array	Before download_url() in download_package(); local path skips download; WP_Error aborts
upgrader_pre_install	filter	bool or WP_Error, array	Before file operations in install_package(); WP_Error aborts
upgrader_source_selection	filter	string, string, WP_Upgrader, array	After unzip, before move; adjust unpacked source path
upgrader_clear_destination	filter	bool or WP_Error, array	Before destination cleared; WP_Error aborts clear
upgrader_post_install	filter	bool or WP_Error, array, array	After files in place; may fail install; triggers manual rollback paths on error

Developer resources

• upgrader_pre_download filter reference — download short-circuit.
• upgrader_process_complete action reference — fires after package processing.

---

6.4 $hook_extra structure reference

$hook_extra carries context for upgrader hooks. Its shape differs between install_package() filters and upgrader_process_complete.

How it works

The array is not identical on every hook. Verify the structure on your WordPress version.

upgrader_pre_download receives the same $hook_extra fourth parameter as in download_package(). For install_package() filters (upgrader_pre_install, upgrader_source_selection, upgrader_clear_destination, upgrader_post_install), keys include action (install or update), type (plugin, theme, core, or translation), plugin basename or theme slug when applicable, and bulk set to true when inside bulk_upgrade().

The upgrader_process_complete action receives $hook_extra with action, type, and — for bulk plugin or theme runs — plural keys plugins or themes as arrays listing basenames or slugs processed, plus bulk when applicable. Singular plugin and theme keys apply to the current item inside install_package(); plural keys apply to batch context on upgrader_process_complete.

On the $upgrader instance passed to upgrader_process_complete, $upgrader->result holds the return value of the last install_package() call (true or WP_Error).

Process flow

1. The caller builds $hook_extra.
2. Each hook receives the array.
3. Consumers read keys appropriate to single versus batch context.

Reference

Inside install_package() filters:

Key	Present for	Value
action	All	install or update
type	All	plugin, theme, core, or translation
plugin	Plugin updates and installs	Plugin basename
theme	Theme updates and installs	Theme slug
bulk	Bulk operations	true inside bulk_upgrade()

upgrader_process_complete action:

Key	Present for	Value
action	All	update or install
type	All	plugin, theme, core, or translation
plugins	Bulk plugin updates	Array of basenames
themes	Bulk theme updates	Array of slugs
bulk	Bulk operations	true inside bulk_upgrade()

Developer resources

• upgrader_process_complete action reference — action signature and parameters.

---

6.5 Automatic updater hooks

These hooks surround WP_Automatic_Updater decisions and completion.

How it works

pre_auto_update is an action that runs once per item inside WP_Automatic_Updater::update(), not once per batch. Arguments are the type string (core, plugin, theme, or translation), the offer object, and the filesystem path used for capability checks. It cannot cancel an update; use auto_update_{$type} filters to skip items.

automatic_updates_complete passes $update_results (§4.7).

For core offers, the per-offer filter is auto_update_core (the auto_update_{$type} hook with type core). It runs inside should_update() after the initial decision from Core_Upgrader::should_update_to_version() (branch policy, WP_AUTO_UPDATE_CORE, site options auto_update_core_*, and allow_*_auto_core_updates).

Core implements branch policy in Core_Upgrader::should_update_to_version(); it does not rely on a filter named wp_auto_update_core (that string is not a core hook). The site option auto_update_core_major (WordPress 5.6+ interface for major updates) is a stored preference — do not confuse it with the auto_update_core filter or the WP_AUTO_UPDATE_CORE constant (§5.5, §5.10, §3.7).

Process flow

1. Before each automatic item, pre_auto_update fires.
2. should_update() evaluates auto_update_{$type}.
3. The update runs or is skipped.
4. After the batch, automatic_updates_complete fires if results exist.

Reference

Hook	Type	Parameters	Notes
pre_auto_update	action	string, object, string	Per item; no return value
auto_update_{$type}	filter	bool, object	Per-offer allow or deny; includes auto_update_core for core
automatic_updates_complete	action	array	Results payload (§4.7)

Developer resources

• pre_auto_update action reference — per-item action.

---

6.6 Core auto-update policy hooks

Branch policy uses allow_* filters, distinct from the per-offer auto_update_core filter, the auto_update_core_major site option (major interface), and other auto_update_core_* options.

How it works

Inside Core_Upgrader::should_update_to_version(), allow_dev_auto_core_updates, allow_minor_auto_core_updates, and allow_major_auto_core_updates each receive the boolean derived from WP_AUTO_UPDATE_CORE or the auto_update_core_* options before returning. They run before auto_update_core inside should_update() for core offers. See §3.7 for the full order.

Process flow

1. Core determines the branch (development, minor, or major).
2. The matching allow_* filter runs.
3. The result feeds should_update() together with auto_update_core.

Reference

Hook	Type	Parameters	Notes
allow_dev_auto_core_updates	filter	bool	Development builds only
allow_minor_auto_core_updates	filter	bool	Same x.y branch
allow_major_auto_core_updates	filter	bool	Major branch jumps

Developer resources

• allow_major_auto_core_updates filter reference — major branch filter.

---

6.7 Notification and email hooks

Email hooks adjust whether messages send and what they contain. Interface filters customize auto-update settings presentation.

How it works

Core email hooks: send_core_update_notification_email, auto_core_update_send_email, and auto_core_update_email. Plugin and theme batch email hooks: auto_plugin_update_send_email, auto_theme_update_send_email, and auto_plugin_theme_update_email. Debug hooks: automatic_updates_send_debug_email and automatic_updates_debug_email. Interface hooks: plugin_auto_update_setting_html, theme_auto_update_setting_html, core_auto_updates_settings_fields, and after_core_auto_updates_settings_fields (see §5.4 and §5.5).

Process flow

1. The updater decides to send email.
2. Gate filters run.
3. Content filters adjust arrays before wp_mail() sends.

Reference

Hook	Type	Parameters	Notes
send_core_update_notification_email	filter	bool	Manual core update notification
auto_core_update_send_email	filter	bool, string	After background core update
auto_core_update_email	filter	array	Alters core email fields
auto_plugin_update_send_email	filter	bool, array	Plugin batch email gate
auto_theme_update_send_email	filter	bool, array	Theme batch email gate
auto_plugin_theme_update_email	filter	array	Alters plugin and theme batch email
automatic_updates_send_debug_email	filter	bool	Debug email enable
automatic_updates_debug_email	filter	array	Debug email payload

Developer resources

• auto_core_update_email filter reference — core email filter.

---

6.8 Cache and filesystem hooks

Filesystem and modification gates interact with WP_Filesystem and updateability checks.

How it works

file_mod_allowed filters whether file modifications are permitted for a context. automatic_updater_disabled disables the automatic updater. The constants DISALLOW_FILE_MODS and AUTOMATIC_UPDATER_DISABLED participate before or alongside these hooks depending on the call site. filesystem_method and request_filesystem_credentials filters adjust how credentials are obtained for interactive flows.

Process flow

1. The upgrader asks whether modifications are allowed.
2. Filters and constants combine to produce the answer.
3. The Filesystem API selects the transport.
4. Background paths require non-interactive success.

Reference

Hook	Type	Parameters	Notes
file_mod_allowed	filter	bool, string	Gates file changes by context
automatic_updater_disabled	filter	bool	Disables the automatic updater
filesystem_method	filter	string, array	Chooses the filesystem method
request_filesystem_credentials	filter	mixed	Credential form and return values

Developer resources

• file_mod_allowed filter reference — filter file modification permission.