Les hooks PHP d’Elementor : le guide des actions et filtres essentiels

Étendre Elementor en PHP demande de connaître son système de hooks, qui suit globalement les conventions WordPress mais avec ses propres points d’entrée. Beaucoup de développeurs découvrent ces hooks au hasard d’un tutoriel trouvé en ligne, sans vue d’ensemble de leur ordre d’exécution — ce qui mène à des bugs difficiles à diagnostiquer, comme un widget enregistré trop tôt qui provoque une erreur fatale silencieuse.

Voici les familles de hooks que nous utilisons le plus souvent sur nos projets, avec leur rôle précis et l’ordre dans lequel Elementor les déclenche au chargement d’une page.

Le point d’entrée : elementor/init

Avant toute extension, Elementor doit être chargé et initialisé. Le hook elementor/init se déclenche une fois qu’Elementor a terminé sa propre initialisation, et c’est le point d’entrée recommandé pour enregistrer vos propres hooks secondaires plutôt que de les attacher directement sur plugins_loaded ou init de WordPress.

add_action( 'elementor/init', function() {
    add_action( 'elementor/widgets/register', 'wpm_register_widgets' );
    add_action( 'elementor/elements/categories_registered', 'wpm_register_category' );
} );

Enregistrement des widgets et catégories

Pour ajouter un widget personnalisé, deux hooks travaillent ensemble : elementor/elements/categories_registered pour créer une catégorie dans le panneau, et elementor/widgets/register pour déclarer le widget lui-même (ce hook a remplacé l’ancien elementor/widgets/widgets_registered, déprécié depuis Elementor 3.5).

• elementor/elements/categories_registered : reçoit l’instance Elements_Manager, sur laquelle appeler add_category().
• elementor/widgets/register : reçoit l’instance Widgets_Manager, sur laquelle appeler register() avec une nouvelle instance de widget.

add_action( 'elementor/elements/categories_registered', function( $elements_manager ) {
    $elements_manager->add_category( 'wpm-widgets', [
        'title' => __( 'WP Moderne', 'wpm' ),
        'icon'  => 'fa fa-plug',
    ] );
} );

Enregistrement des scripts et styles

Un widget qui a besoin de son propre JavaScript (un carrousel, une carte interactive) doit enregistrer ses assets via elementor/frontend/before_register_scripts côté public, et non via le hook générique wp_enqueue_scripts seul, afin de bénéficier du système de dépendances d’Elementor (notamment la dépendance sur elementor-frontend).

add_action( 'elementor/frontend/before_register_scripts', function() {
    wp_register_script(
        'wpm-carousel',
        plugins_url( 'assets/js/carousel.js', __FILE__ ),
        [ 'elementor-frontend' ],
        '1.0.0',
        true
    );
} );

Les hooks de rendu : avant, pendant, après

Pour injecter du contenu autour d’un widget sans le modifier, Elementor expose une famille de hooks liés au rendu, dont les plus utilisés sont elementor/frontend/before_render et elementor/frontend/after_render, tous deux déclenchés avec l’instance de l’élément en cours de rendu.

Hook	Moment	Usage typique
elementor/frontend/before_render	Juste avant le HTML du widget	Ajouter un wrapper, une balise structurée
elementor/frontend/after_render	Juste après le HTML du widget	Fermer un wrapper, injecter un badge
elementor/element/before_section_end	Fin d’une section de contrôles	Ajouter un contrôle à un widget existant

Ordre d’exécution à connaître

Un piège classique : tenter d’enregistrer un widget directement sur plugins_loaded, avant qu’Elementor n’ait chargé ses propres classes de base. Le résultat est une erreur fatale Class 'Elementor\Widget_Base' not found. L’ordre correct est toujours le même :

1. WordPress charge les plugins (plugins_loaded).
2. Elementor s’initialise et déclenche elementor/init.
3. Vos hooks personnels, attachés dans elementor/init, s’exécutent à leur tour.
4. Au moment du rendu d’une page, les hooks de la famille elementor/frontend/* se déclenchent widget par widget.

Notre règle systématique : jamais de class extends \Elementor\Widget_Base chargée en dehors d’un callback attaché à elementor/widgets/register. Cela évite toute dépendance à l’ordre de chargement des plugins.

En résumé

Le système de hooks d’Elementor reste fidèle à la philosophie WordPress, mais impose son propre point d’entrée via elementor/init et une famille de hooks dédiés au rendu et à l’enregistrement des éléments. Retenez surtout l’ordre : initialisation d’Elementor, puis enregistrement des widgets et catégories, puis, à chaque affichage de page, les hooks de rendu. Respecter cet ordre évite la quasi-totalité des erreurs fatales rencontrées lors du développement d’extensions maison.