Skip to content

Commit 8bc4e02

Browse files
committed
Clarify precautions around hooks which dispatch on install/upgrade
1 parent 3152cdf commit 8bc4e02

File tree

1 file changed

+4
-3
lines changed

1 file changed

+4
-3
lines changed

docs/apis/core/hooks/index.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -296,9 +296,10 @@ Any guidelines for callback priority should be described in hook descriptions if
296296

297297
:::caution
298298

299-
Callbacks _are executed during system installation and all upgrades_, the callback
300-
methods must verify the plugin is in correct state. Often the easiest way is to
301-
use function during_initial_install() or version string from the plugin configuration.
299+
Unlike lib.php based plugin callbacks, certain hooks _are dispatched during system installation and upgrade_ (for example `before_http_headers`). Callback
300+
methods for such hooks must take extra care to ensure the plugin is properly initialised, as (among other things) on install _the site's database is not initialised_.
301+
The function during_initial_install() or version string from the plugin configuration may be used to conditionally make DB queries or use API functions in such cases.
302+
Failure to do so may render the web install/upgrade page unusable.
302303

303304
:::
304305

0 commit comments

Comments
 (0)