# elementor/widgets/register : migrer vos widgets avant la dépréciation

> Elementor 3.5 dépréciera widgets_registered au profit d'un nouveau hook plus explicite. Voici comment migrer vos widgets maison sans casser la compatibilité.

- Auteur : Clément Hadrot
- Publié le : 2021-12-13
- Mis à jour le : 2021-12-13
- Catégorie : Elementor
- URL : https://wpmoderne.dev.wordpress-developpement.fr/elementor/elementor-widgets-register-migrer-depreciation/

## L’essentiel

- L'ancien hook reste fonctionnel mais génère désormais un avertissement de dépréciation
- Le nouveau hook reçoit directement le Widgets_Manager en argument
- Une compatibilité ascendante simple permet de supporter les deux versions le temps de la transition

Elementor 3.5, sortie début décembre, introduit un changement discret mais qui mérite l'attention de quiconque maintient des widgets personnalisés : le hook historique `elementor/widgets/widgets_registered` est officiellement déprécié au profit d'un nouveau hook, `elementor/widgets/register`. L'ancien continue de fonctionner pour l'instant, mais génère un message de dépréciation visible en mode debug, et sa suppression complète est annoncée pour une version ultérieure.

Sur nos projets maintenus, nous avons profité de cette sortie pour migrer l'ensemble des widgets maison encore attachés à l'ancien hook. L'opération est simple, mais mérite d'être bien comprise avant d'être appliquée en masse.

## Ce qui change concrètement

L'ancien hook `elementor/widgets/widgets_registered` recevait le `Widgets_Manager` en argument, sur lequel on appelait `register_widget_type()` avec une instance de widget :

```
// Ancienne méthode, dépréciée depuis Elementor 3.5
add_action( 'elementor/widgets/widgets_registered', function( $widgets_manager ) {
    require_once __DIR__ . '/widgets/class-widget-temoignage.php';
    $widgets_manager->register_widget_type( new Widget_Temoignage() );
} );
```

Le nouveau hook `elementor/widgets/register` conserve une logique très proche, avec deux différences : le nom de la méthode d'enregistrement passe de `register_widget_type()` à `register()`, et le hook lui-même est renommé.

```
// Nouvelle méthode, recommandée à partir d'Elementor 3.5
add_action( 'elementor/widgets/register', function( $widgets_manager ) {
    require_once __DIR__ . '/widgets/class-widget-temoignage.php';
    $widgets_manager->register( new Widget_Temoignage() );
} );
```

> L'essentiel à retenir : L'ancien hook reste fonctionnel mais génère désormais un avertissement de dépréciation ; Le nouveau hook reçoit directement le Widgets_Manager en argument ; Une compatibilité ascendante simple permet de supporter les deux versions le temps de la transition

## Pourquoi Elementor fait ce changement

Le nom `widgets_registered`, au participe passé, laissait entendre que l'enregistrement était déjà terminé au moment du hook, ce qui prêtait à confusion. Le nouveau nom, à l'impératif, correspond davantage à la réalité : c'est le moment où l'on doit effectuer l'enregistrement, pas une notification après coup. Ce genre de clarification s'inscrit dans un effort plus large d'Elementor pour uniformiser le nommage de ses hooks internes.

## Assurer une compatibilité ascendante simple

Pour un plugin distribué à plusieurs clients dont certains sont encore sur une version antérieure à 3.5, il est possible de détecter la disponibilité du nouveau hook et de basculer automatiquement :

```
if ( did_action( 'elementor/loaded' ) && version_compare( ELEMENTOR_VERSION, '3.5.0', '>=' ) ) {
    add_action( 'elementor/widgets/register', function( $widgets_manager ) {
        $widgets_manager->register( new Widget_Temoignage() );
    } );
} else {
    add_action( 'elementor/widgets/widgets_registered', function( $widgets_manager ) {
        $widgets_manager->register_widget_type( new Widget_Temoignage() );
    } );
}
```

Cette approche évite un avertissement de dépréciation sur les installations à jour, tout en gardant le fonctionnement intact sur les installations plus anciennes qui n'ont pas encore migré vers 3.5.

## Liste de vérification pour la migration

- Rechercher, dans le code du thème et des plugins maison, toute occurrence de `widgets_registered` et `register_widget_type`.
- Remplacer par `elementor/widgets/register` et `register()`, en testant sur un environnement de staging à jour.
- Activer `WP_DEBUG` pour vérifier qu'aucun message de dépréciation ne subsiste dans les logs après migration.
- Documenter la version minimale d'Elementor désormais requise si la compatibilité ascendante n'est pas conservée.

| Élément | Avant 3.5 | À partir de 3.5 |
| --- | --- | --- |
| Hook | `elementor/widgets/widgets_registered` | `elementor/widgets/register` |
| Méthode d'enregistrement | `register_widget_type()` | `register()` |
| Statut | Déprécié, encore fonctionnel | Recommandé |

> Une dépréciation annoncée n'est jamais urgente le jour de sa sortie, mais elle le devient toujours plus tard, au pire moment. Nous traitons systématiquement ces migrations dans les deux semaines suivant l'annonce, pendant que le contexte est encore frais.

## En résumé

La migration de `widgets_registered` vers `register` reste mineure en volume de code, mais elle mérite d'être traitée rapidement plutôt que reportée : les hooks dépréciés d'Elementor finissent toujours par disparaître après quelques versions majeures. Un simple test de version PHP permet, en attendant, de maintenir la compatibilité avec les installations plus anciennes sans dupliquer la logique métier des widgets eux-mêmes.