6.1 Vue d’ensemble de la référence des crochets
Les crochets permettent aux extensions de modifier les charges utiles de découverte, le comportement de téléchargement, les étapes d’installation, les décisions automatiques et les notifications. Cette partie les regroupe par phase. Les signatures exactes figurent sur developer.wordpress.org.
Fonctionnement
La découverte utilise pre_set_site_transient_* et les filtres associés. Le téléchargement et l’installation utilisent upgrader_pre_download et les filtres d’install_package(). Les mises à jour automatiques utilisent auto_update_{$type}, pre_auto_update et automatic_updates_complete. Les crochets d’e-mail et de système de fichiers affinent le comportement. Reportez-vous aux tableaux de §6.2 à §6.8.
Déroulement
- WordPress atteint un point de crochet.
- Les fonctions de rappel enregistrées s’exécutent dans l’ordre de priorité.
- Les filtres renvoient des valeurs ; les actions produisent des effets de bord.
- Les valeurs renvoyées peuvent interrompre des étapes avec une
WP_Error.
Référence
| Catégorie | Section |
|---|---|
| Découverte | §6.2 |
| Téléchargement et installation | §6.3 |
Formes de $hook_extra | §6.4 |
| Programme de mise à jour automatique | §6.5 |
| Politique du cœur | §6.6 |
| Notifications | §6.7 |
| Cache et système de fichiers | §6.8 |
Ressources pour les développeurs
- Présentation des crochets : actions et filtres : introduction au système de crochets.
6.2 Les crochets de découverte
Ces crochets modifient ou observent les charges utiles des transients avant leur enregistrement.
Fonctionnement
pre_set_site_transient_update_plugins, pre_set_site_transient_update_themes et pre_set_site_transient_update_core laissent votre code changer la valeur sur le point d’être enregistrée. Les filtres associés site_transient_update_* s’appliquent quand WordPress lit les transients. Les hébergeurs tiers utilisent update_plugins_{$hostname} et update_themes_{$hostname} (§1.8).
Déroulement
- Une fonction de vérification construit une charge utile.
- Les filtres
pre_set_*s’exécutent. - WordPress enregistre le transient.
- Les lecteurs appliquent les filtres
site_transient_*au chargement du transient.
Référence
| Crochet | Type | Paramètres | Remarques |
|---|---|---|---|
pre_set_site_transient_update_plugins | filtre | objet | Modifie le transient des mises à jour d’extensions avant enregistrement |
pre_set_site_transient_update_themes | filtre | objet | Modifie le transient des mises à jour de thèmes avant enregistrement |
pre_set_site_transient_update_core | filtre | objet | Modifie le transient des mises à jour du cœur avant enregistrement |
site_transient_update_plugins | filtre | objet | Filtre la valeur lue |
site_transient_update_themes | filtre | objet | Filtre la valeur lue |
site_transient_update_core | filtre | objet | Filtre la valeur lue |
update_plugins_{$hostname} | filtre | variables | Métadonnées d’extensions tierces |
update_themes_{$hostname} | filtre | variables | Métadonnées de thèmes tiers |
Ressources pour les développeurs
- Référence du filtre
pre_set_site_transient_{$transient}: famille de crochets dynamiques.
6.3 Les crochets de téléchargement et d’installation (upgrader_pre_download et les crochets d’install_package())
upgrader_pre_download s’exécute avant le téléchargement HTTP. Quatre filtres s’exécutent dans install_package(), autour des opérations sur les fichiers.
Fonctionnement
upgrader_pre_download se déclenche dans WP_Upgrader::download_package(), avant download_url(). Renvoyez une chaîne de chemin local pour remplacer entièrement le téléchargement distant, false pour continuer normalement, ou une WP_Error pour interrompre. Si le filtre renvoie une WP_Error, les crochets d’install_package() ne s’exécutent pas.
Dans install_package(), upgrader_pre_install s’exécute avant les opérations sur les fichiers ; upgrader_source_selection ajuste le chemin décompressé ; upgrader_clear_destination conditionne le nettoyage ; upgrader_post_install s’exécute une fois les fichiers en place (la réactivation d’une extension se produit dans le chemin du moteur de mise à niveau des extensions). Renvoyer une WP_Error depuis un filtre concerné interrompt l’étape.
Déroulement
- L’étape de téléchargement évalue
upgrader_pre_download. - La décompression s’exécute.
upgrader_pre_installs’exécute.upgrader_source_selectionajuste le chemin source.upgrader_clear_destinationconditionne le nettoyage de la destination.upgrader_post_installs’exécute.- L’action
upgrader_process_completese déclenche après le traitement (voir §6.4 pour la forme de la charge utile).
Référence
| Crochet | Type | Paramètres | Remarques |
|---|---|---|---|
upgrader_pre_download | filtre | bool ou chaîne ou WP_Error, chaîne, WP_Upgrader, tableau | Avant download_url() dans download_package() ; un chemin local saute le téléchargement ; une WP_Error interrompt |
upgrader_pre_install | filtre | bool ou WP_Error, tableau | Avant les opérations sur les fichiers dans install_package() ; une WP_Error interrompt |
upgrader_source_selection | filtre | chaîne, chaîne, WP_Upgrader, tableau | Après la décompression, avant le déplacement ; ajuste le chemin source décompressé |
upgrader_clear_destination | filtre | bool ou WP_Error, tableau | Avant le nettoyage de la destination ; une WP_Error interrompt le nettoyage |
upgrader_post_install | filtre | bool ou WP_Error, tableau, tableau | Après la mise en place des fichiers ; peut faire échouer l’installation ; déclenche les chemins de retour en arrière manuel en cas d’erreur |
Ressources pour les développeurs
- Référence du filtre
upgrader_pre_download: court-circuit du téléchargement. - Référence de l’action
upgrader_process_complete: se déclenche après le traitement d’un paquet.
6.4 Référence de la structure de $hook_extra
$hook_extra porte le contexte des crochets du moteur de mise à niveau. Sa forme diffère entre les filtres d’install_package() et l’action upgrader_process_complete.
Fonctionnement
Le tableau n’est pas identique sur chaque crochet. Vérifiez la structure sur votre version de WordPress.
upgrader_pre_download reçoit, en quatrième paramètre, le même $hook_extra que dans download_package(). Pour les filtres d’install_package() (upgrader_pre_install, upgrader_source_selection, upgrader_clear_destination, upgrader_post_install), les clés incluent action (install ou update), type (plugin, theme, core ou translation), le nom de base de l’extension dans plugin ou l’identifiant du thème dans theme le cas échéant, et bulk à vrai dans bulk_upgrade().
L’action upgrader_process_complete reçoit un $hook_extra avec action, type et — pour les exécutions groupées d’extensions ou de thèmes — les clés plurielles plugins ou themes, sous forme de tableaux listant les noms de base ou les identifiants traités, plus bulk le cas échéant. Les clés singulières plugin et theme concernent l’élément courant dans install_package() ; les clés plurielles concernent le contexte du lot sur upgrader_process_complete.
Sur l’instance $upgrader transmise à upgrader_process_complete, $upgrader->result contient la valeur renvoyée par le dernier appel à install_package() (true ou une WP_Error).
Déroulement
- L’appelant construit
$hook_extra. - Chaque crochet reçoit le tableau.
- Les consommateurs lisent les clés adaptées au contexte d’un élément seul ou d’un lot.
Référence
Dans les filtres d’install_package() :
| Clé | Présente pour | Valeur |
|---|---|---|
action | Tous | install ou update |
type | Tous | plugin, theme, core ou translation |
plugin | Mises à jour et installations d’extensions | Nom de base de l’extension |
theme | Mises à jour et installations de thèmes | Identifiant du thème |
bulk | Opérations groupées | true dans bulk_upgrade() |
Action upgrader_process_complete :
| Clé | Présente pour | Valeur |
|---|---|---|
action | Tous | update ou install |
type | Tous | plugin, theme, core ou translation |
plugins | Mises à jour groupées d’extensions | Tableau de noms de base |
themes | Mises à jour groupées de thèmes | Tableau d’identifiants |
bulk | Opérations groupées | true dans bulk_upgrade() |
Ressources pour les développeurs
- Référence de l’action
upgrader_process_complete: signature et paramètres de l’action.
6.5 Les crochets du programme de mise à jour automatique
Ces crochets encadrent les décisions et la fin d’exécution de WP_Automatic_Updater.
Fonctionnement
pre_auto_update est une action qui s’exécute une fois par élément dans WP_Automatic_Updater::update(), et non une fois par lot. Ses arguments sont la chaîne de type (core, plugin, theme ou translation), l’objet d’offre et le chemin du système de fichiers utilisé pour les contrôles de capacité. Elle ne peut pas annuler une mise à jour ; utilisez les filtres auto_update_{$type} pour écarter des éléments.
automatic_updates_complete transmet $update_results (§4.7).
Pour les offres du cœur, le filtre par offre est auto_update_core (le crochet auto_update_{$type} avec le type core). Il s’exécute dans should_update(), après la décision initiale de Core_Upgrader::should_update_to_version() (politique de branche, WP_AUTO_UPDATE_CORE, options de site auto_update_core_* et allow_*_auto_core_updates).
Le cœur implémente la politique de branche dans Core_Upgrader::should_update_to_version() ; il ne s’appuie pas sur un filtre nommé wp_auto_update_core (cette chaîne n’est pas un crochet du cœur). L’option de site auto_update_core_major (interface des mises à jour majeures de WordPress 5.6 et suivantes) est une préférence stockée : ne la confondez pas avec le filtre auto_update_core ni avec la constante WP_AUTO_UPDATE_CORE (§5.5, §5.10, §3.7).
Déroulement
- Avant chaque élément automatique,
pre_auto_updatese déclenche. should_update()évalueauto_update_{$type}.- La mise à jour s’exécute ou est écartée.
- Après le lot,
automatic_updates_completese déclenche si des résultats existent.
Référence
| Crochet | Type | Paramètres | Remarques |
|---|---|---|---|
pre_auto_update | action | chaîne, objet, chaîne | Par élément ; aucune valeur de retour |
auto_update_{$type} | filtre | bool, objet | Autorise ou refuse par offre ; inclut auto_update_core pour le cœur |
automatic_updates_complete | action | tableau | Charge utile des résultats (§4.7) |
Ressources pour les développeurs
- Référence de l’action
pre_auto_update: action par élément.
6.6 Les crochets de politique de mise à jour automatique du cœur
La politique de branche utilise les filtres allow_*, distincts du filtre auto_update_core propre à chaque offre, de l’option de site auto_update_core_major (interface des versions majeures) et des autres options auto_update_core_*.
Fonctionnement
Dans Core_Upgrader::should_update_to_version(), allow_dev_auto_core_updates, allow_minor_auto_core_updates et allow_major_auto_core_updates reçoivent chacun le booléen issu de WP_AUTO_UPDATE_CORE ou des options auto_update_core_* avant de le renvoyer. Ils s’exécutent avant auto_update_core dans should_update(), pour les offres du cœur. Voir §3.7 pour l’ordre complet.
Déroulement
- Le cœur détermine la branche (développement, mineure ou majeure).
- Le filtre
allow_*correspondant s’exécute. - Le résultat alimente
should_update()avecauto_update_core.
Référence
| Crochet | Type | Paramètres | Remarques |
|---|---|---|---|
allow_dev_auto_core_updates | filtre | bool | Versions de développement uniquement |
allow_minor_auto_core_updates | filtre | bool | Même branche x.y |
allow_major_auto_core_updates | filtre | bool | Sauts de branche majeure |
Ressources pour les développeurs
- Référence du filtre
allow_major_auto_core_updates: filtre de branche majeure.
6.7 Les crochets de notification et d’e-mail
Les crochets d’e-mail décident si les messages partent et ce qu’ils contiennent. Les filtres d’interface personnalisent la présentation des réglages de mise à jour automatique.
Fonctionnement
Crochets d’e-mail du cœur : send_core_update_notification_email, auto_core_update_send_email et auto_core_update_email. Crochets des e-mails de lots d’extensions et de thèmes : auto_plugin_update_send_email, auto_theme_update_send_email et auto_plugin_theme_update_email. Crochets de débogage : automatic_updates_send_debug_email et automatic_updates_debug_email. Crochets d’interface : plugin_auto_update_setting_html, theme_auto_update_setting_html, core_auto_updates_settings_fields et after_core_auto_updates_settings_fields (voir §5.4 et §5.5).
Déroulement
- Le programme de mise à jour décide d’envoyer un e-mail.
- Les filtres de barrière s’exécutent.
- Les filtres de contenu ajustent les tableaux avant l’envoi par
wp_mail().
Référence
| Crochet | Type | Paramètres | Remarques |
|---|---|---|---|
send_core_update_notification_email | filtre | bool | Notification de mise à jour manuelle du cœur |
auto_core_update_send_email | filtre | bool, chaîne | Après une mise à jour du cœur en arrière-plan |
auto_core_update_email | filtre | tableau | Modifie les champs de l’e-mail du cœur |
auto_plugin_update_send_email | filtre | bool, tableau | Barrière des e-mails de lot d’extensions |
auto_theme_update_send_email | filtre | bool, tableau | Barrière des e-mails de lot de thèmes |
auto_plugin_theme_update_email | filtre | tableau | Modifie l’e-mail de lot d’extensions et de thèmes |
automatic_updates_send_debug_email | filtre | bool | Activation de l’e-mail de débogage |
automatic_updates_debug_email | filtre | tableau | Charge utile de l’e-mail de débogage |
Ressources pour les développeurs
- Référence du filtre
auto_core_update_email: filtre des e-mails du cœur.
6.8 Les crochets de cache et de système de fichiers
Les barrières du système de fichiers et des modifications de fichiers interagissent avec WP_Filesystem et les contrôles de possibilité de mise à jour.
Fonctionnement
file_mod_allowed filtre l’autorisation de modifier des fichiers pour un contexte donné. automatic_updater_disabled désactive le programme de mise à jour automatique. Les constantes DISALLOW_FILE_MODS et AUTOMATIC_UPDATER_DISABLED interviennent avant ou à côté de ces crochets, selon le point d’appel. Les filtres filesystem_method et request_filesystem_credentials ajustent la façon dont les identifiants sont obtenus pour les flux interactifs.
Déroulement
- Le moteur de mise à niveau demande si les modifications sont autorisées.
- Filtres et constantes se combinent pour produire la réponse.
- L’API du système de fichiers choisit le transport.
- Les chemins d’arrière-plan exigent une réussite sans interaction.
Référence
| Crochet | Type | Paramètres | Remarques |
|---|---|---|---|
file_mod_allowed | filtre | bool, chaîne | Conditionne les changements de fichiers selon le contexte |
automatic_updater_disabled | filtre | bool | Désactive le programme de mise à jour automatique |
filesystem_method | filtre | chaîne, tableau | Choisit la méthode d’accès au système de fichiers |
request_filesystem_credentials | filtre | mixte | Formulaire d’identifiants et valeurs de retour |
Ressources pour les développeurs
- Référence du filtre
file_mod_allowed: filtre l’autorisation de modifier des fichiers.
