SW Shopware 6 Shopware Débutant

DfAddressAutocomplete — Auto-complétion d’adresse pour Shopware 6

Installer, configurer et étendre l'auto-complétion d'adresse multi-provider (BAN, Google Places) sur Shopware 6.6/6.7.

Mis à jour Version du module 1.0.0

Présentation

DfAddressAutocomplete ajoute une recherche d’adresse instantanée aux formulaires d’adresse de Shopware 6 : checkout, carnet d’adresses du compte client et inscription. Le client tape le début de son adresse, sélectionne une suggestion et tous les champs se remplissent automatiquement — rue, complément, code postal, ville et pays.

Deux providers sont inclus : BAN (Base Adresse Nationale, gratuit, France) et Google Places (New) (payant, mondial). L’architecture est extensible : n’importe quelle API d’adresse peut être branchée via une interface PHP.

Prérequis

  • Shopware 6.6 ou 6.7
  • PHP 8.2 minimum
  • Pour Google Places : une clé API Google Cloud avec la Places API (New) activée (pas l’ancienne Places API)

Installation

  1. Uploadez le ZIP dans custom/plugins/ ou via l’admin Shopware (Extensions → Mes extensions → Uploader une extension).
  2. Exécutez les commandes suivantes :
bin/console plugin:refresh
bin/console plugin:install --activate DfAddressAutocomplete
bin/console cache:clear
  1. Compilez le storefront pour que le JavaScript et le CSS soient intégrés :
./bin/build-storefront.sh

Sur les environnements sans script de build, utilisez bin/console theme:compile après avoir compilé les assets une première fois.

Configuration

Rendez-vous dans Extensions → Mes extensions → DfAddressAutocomplete → Configurer. Tous les réglages sont scopables par sales channel.

Fournisseur

  • Fournisseur d’auto-complétion : BAN (par défaut) ou Google Places.
  • Clé API Google Places : requise uniquement si Google est sélectionné. La clé reste côté serveur et n’est jamais envoyée au navigateur.
  • Restriction pays : codes ISO 3166-1 alpha-2 séparés par des virgules (ex. FR,BE,LU,CH). Vide = aucune restriction. La restriction ne s’applique qu’à Google (BAN est France uniquement par nature).

Pages d’activation

Trois interrupteurs indépendants : checkout, compte client (carnet d’adresses) et inscription. Chacun s’active ou se désactive séparément.

Comportement

  • Caractères minimum (défaut 3) : aucune recherche en dessous de ce seuil.
  • Délai anti-rebond (défaut 250 ms) : temps d’attente après la dernière frappe avant d’interroger l’API.
  • Suggestions maximum (défaut 5).
  • Cache serveur (activé par défaut) : 5 minutes sur les recherches, 15 minutes sur les détails. Réduit la facturation Google et la latence.

Configurer Google Places

  1. Dans la Google Cloud Console, créez ou sélectionnez un projet.
  2. Activez la Places API (New) — attention, pas l’ancienne « Places API ».
  3. Créez une clé API et restreignez-la par adresse IP de serveur (celle de votre hébergement Shopware). Ne la restreignez pas par référent HTTP : le trafic est server-to-server.
  4. Collez la clé dans la configuration du plugin.

L’API Places (New) est facturée à l’usage. Le cache serveur du plugin et l’anti-rebond limitent le nombre d’appels, mais surveillez votre consommation dans la console Google.

Fonctionnement côté client

Un champ de recherche apparaît au-dessus du formulaire d’adresse standard. La navigation clavier est complète : flèches haut/bas pour parcourir les suggestions, Entrée pour sélectionner, Échap pour fermer. À la sélection, les champs Shopware standards sont remplis et le pays est sélectionné automatiquement dans le menu déroulant.

Ajouter un provider personnalisé

Implémentez l’interface AutocompleteProviderInterface (namespace DataFirefly\DfAddressAutocomplete\Provider) dans votre propre plugin :

final class MapboxProvider implements AutocompleteProviderInterface
{
    public function getKey(): string { return 'mapbox'; }

    public function search(string $query, int $limit, string $salesChannelId, array $countryCodes = []): array
    {
        // Interrogez votre API et retournez un tableau d'AddressSuggestion
    }

    public function details(string $id, string $salesChannelId): ?AddressDetails
    {
        // Résolvez l'id en AddressDetails complet
    }
}

Puis taguez le service dans votre services.xml (id du service = classe complète de votre provider) :

<service id="My\Plugin\MapboxProvider">
    <tag name="df_address_autocomplete.provider"/>
</service>

Chaque suggestion embarque le préfixe de son provider dans son id (ex. mapbox:abc123) : le routage des appels de détail est automatique.

Thèmes personnalisés

Le plugin étend le composant standard component_address_form et détecte les champs par leur nom (*AddressStreet, *AddressZipcode, *AddressCity, *AddressCountry). Si votre thème renomme ces champs, surchargez la méthode _cacheTargetFields du plugin JavaScript pour lui indiquer les nouveaux noms.

Dépannage

  • Le champ de recherche n’apparaît pas : vérifiez que le storefront a bien été recompilé après l’activation, et que la page concernée est activée dans la configuration.
  • Aucune suggestion avec Google : vérifiez que la Places API (New) est activée sur le projet, que la clé est valide et que sa restriction IP correspond à l’IP de votre serveur.
  • Le pays ne se sélectionne pas : le plugin compare le code ISO avec l’attribut data-country-iso des options du menu déroulant, puis avec leur texte visible. Si votre thème n’expose ni l’un ni l’autre, le pays courant est conservé.

Confidentialité (RGPD)

Le plugin ne stocke aucune donnée personnelle. Les saisies de l’utilisateur transitent par votre serveur Shopware vers le provider choisi. Avec BAN, les données sont traitées par un service public français (DINUM). Avec Google, elles sont soumises aux conditions de Google Cloud — mentionnez-le dans votre politique de confidentialité si nécessaire.

Cette page vous a-t-elle été utile ?

Toujours bloqué ? Contactez le support