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

> Panorama des hooks PHP les plus utiles d'Elementor : enregistrement de scripts, de widgets, de catégories et de rendu, avec leur ordre d'exécution réel.

- Auteur : Clément Hadrot
- Publié le : 2020-10-05
- Mis à jour le : 2020-10-05
- Catégorie : Elementor
- URL : https://wpmoderne.dev.wordpress-developpement.fr/elementor/hooks-php-elementor-actions-filtres-essentiels/

## L’essentiel

- elementor/init est le point d'entrée commun à toute extension
- L'ordre des hooks de rendu conditionne l'insertion de contenu personnalisé
- Un widget doit être enregistré après elementor/widgets/register, jamais avant

É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
    );
} );
```

> L'essentiel à retenir : elementor/init est le point d'entrée commun à toute extension ; L'ordre des hooks de rendu conditionne l'insertion de contenu personnalisé ; Un widget doit être enregistré après elementor/widgets/register, jamais avant

## 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.