# after_switch_theme jamais déclenché après un déploiement par copie

> Un thème copié directement sur le serveur de production, sans passer par l'écran d'activation de WordPress, prive silencieusement le projet de toute son initialisation prévue au premier lancement.

- Auteur : WordPress Développement
- Publié le : 2023-12-06
- Mis à jour le : 2023-12-06
- Catégorie : Thèmes
- URL : https://www.wpmoderne.fr/themes/after-switch-theme-jamais-declenche-deploiement-copie/

## L’essentiel

- after_switch_theme ne se déclenche qu'au moment d'un changement de thème actif via WordPress
- Une copie de fichiers par FTP ou SSH ne déclenche jamais ce hook
- Une vérification manuelle permet de rattraper une initialisation manquée

Un thème fonctionne parfaitement sur l'environnement de développement, où il a été activé normalement depuis l'écran **Apparence > Thèmes**. Une fois déployé en production par copie directe des fichiers via SSH, en remplaçant un dossier de thème déjà actif par sa nouvelle version, certains réglages attendus au premier lancement n'apparaissent jamais : pas de page d'accueil statique créée automatiquement, pas de menu par défaut assigné, pas de widgets préconfigurés dans la barre latérale.

Ce comportement n'est pas un bug de WordPress, ni un problème propre au thème : il découle directement de la façon dont le hook `after_switch_theme` est déclenché, et des conditions précises qui doivent être réunies pour qu'il s'exécute.

## Ce que fait réellement after_switch_theme

Le hook d'action `after_switch_theme` s'exécute uniquement lorsque WordPress détecte un changement du thème actif, opération qui se produit normalement via la fonction `switch_theme()`, elle-même appelée par l'écran d'activation des thèmes dans l'administration. De nombreux thèmes utilisent ce hook pour créer une page d'accueil par défaut, assigner un menu, ou définir des réglages initiaux propres au premier lancement :

```
add_action( 'after_switch_theme', function () {
    if ( ! get_option( 'mon_theme_page_accueil_creee' ) ) {
        $page_id = wp_insert_post( [
            'post_title'  => 'Accueil',
            'post_status' => 'publish',
            'post_type'   => 'page',
        ] );
        update_option( 'show_on_front', 'page' );
        update_option( 'page_on_front', $page_id );
        update_option( 'mon_theme_page_accueil_creee', true );
    }
} );
```

## Pourquoi une copie de fichiers ne déclenche jamais ce hook

WordPress détermine le thème actif via l'option `template` et `stylesheet`, stockées en base de données. Remplacer les fichiers d'un thème par une nouvelle version, sans jamais modifier ces options en base, ne constitue pas un changement de thème actif du point de vue de WordPress : le thème « actif » reste, à ses yeux, exactement le même qu'avant la copie, puisque son identifiant de dossier n'a pas changé. Le hook `after_switch_theme` ne s'exécute que lorsque `switch_theme()` est appelée, ce qui n'arrive jamais dans ce scénario de déploiement.

> L'essentiel à retenir : after_switch_theme ne se déclenche qu'au moment d'un changement de thème actif via WordPress ; Une copie de fichiers par FTP ou SSH ne déclenche jamais ce hook ; Une vérification manuelle permet de rattraper une initialisation manquée

## Reproduire le comportement attendu sans passer par l'écran d'activation

Pour les projets déployés systématiquement par copie de fichiers plutôt que par activation manuelle, la solution consiste à ne pas dépendre uniquement de `after_switch_theme` pour l'initialisation critique, mais à prévoir une vérification indépendante, déclenchée à chaque chargement de l'administration :

```
add_action( 'admin_init', function () {
    if ( ! get_option( 'mon_theme_page_accueil_creee' ) ) {
        // Même logique d'initialisation que dans after_switch_theme.
    }
} );
```

Cette vérification, bien que légèrement moins élégante qu'un hook dédié, garantit que l'initialisation s'exécute quel que soit le mode de déploiement utilisé, tant que l'option de contrôle n'a pas encore été enregistrée.

## Une commande WP-CLI pour forcer le déclenchement

Sur un environnement où le thème a déjà été copié sans jamais passer par une activation en bonne et due forme, il est possible de forcer artificiellement le déclenchement du hook en réactivant le thème via WP-CLI, ce qui appelle bien `switch_theme()` en interne :

```
wp theme activate mon-theme
```

Cette commande produit exactement le même effet qu'un clic sur le bouton d'activation dans l'administration, y compris le déclenchement de `after_switch_theme`, même si le thème était déjà considéré comme actif juste avant.

> Un hook qui dépend d'un changement d'état plutôt que d'un simple chargement de fichier ne se déclenche jamais par accident ; encore faut-il connaître précisément la condition qui le déclenche pour ne pas compter dessus à tort.

## En résumé

Un déploiement par copie directe de fichiers, courant sur les hébergements sans pipeline automatisé, ne déclenche jamais `after_switch_theme`, puisque ce hook dépend d'un véritable changement d'option en base de données via `switch_theme()`. Prévoir une vérification de repli via `admin_init`, ou réactiver explicitement le thème avec WP-CLI après un déploiement, évite qu'une initialisation critique passe silencieusement à la trappe.