Guide du module Échange de devises pour LaraClassifier

Cet add-on ajoute dans l'en-tête de la partie publique une liste déroulante des devises définies depuis le Panneau d'administration.

Fonctionnalités

• Cet add-on ajoute dans l'en-tête de la partie publique une liste déroulante des devises définies depuis le Panneau d'administration.
• Et, permet aux utilisateurs d'obtenir une estimation du prix des annonces dans d'autres devises.

Voici la liste des services actuellement implémentés :
Pour certains services de taux de change, vous devez obtenir des identifiants API.

• currencylayer.com - Obtenez une clé d'accès (Access Key) ici.
• exchangerate-api.com - Obtenez une clé API ici.
• exchangeratesapi.io - Obtenez une clé d'accès (Access Key) ici.
• openexchangerates.org - Obtenez un App ID ici.
• fixer.io - Obtenez une clé d'accès (Access Key) ici.
• Banque centrale européenne - Consultez les données ici.
• Banque centrale de Russie - Consultez les données ici.
• Banque centrale de Turquie - Consultez les données ici.
• Banque nationale d'Ukraine - Consultez les données ici.
• Banque centrale de la République tchèque - Consultez les données ici.
• Banque nationale de Roumanie - Consultez les données ici.

Compatibilité

• v5.0.2 => LaraClassifier v19.1.3+
• v5.0.1 => LaraClassifier v19.1.0+
• v5.0.0 => LaraClassifier (v19.0.0 à v19.0.1)
• v4.3.7 => LaraClassifier v18.3.0+
• v4.3.6 => LaraClassifier v18.2.0
• v4.3.5 => LaraClassifier v18.1.0 à v18.1.1
• v4.3.4 => LaraClassifier v18.0.3
• v4.3.3 => LaraClassifier v18.0.2
• v4.3.2 => LaraClassifier v18.0.1
• v4.3.1 => LaraClassifier v18.0.0
• v4.3.0 => LaraClassifier (v17.0.0 à v17.1.1)
• v4.2.9 => LaraClassifier v16.0.1 à v16.0.2
• v4.2.8 => LaraClassifier v16.0.0
• v4.2.7 => LaraClassifier v15.4.0 à v15.4.1
• v4.2.6 => LaraClassifier v15.3.4 à v15.3.5
• v4.2.5 => LaraClassifier v15.3.4
• v4.2.4 => LaraClassifier v15.1.6 à v15.3.3
• v4.2.3 => LaraClassifier v15.1.5
• v4.2.2 => LaraClassifier v15.1.4
• v4.2.1 => LaraClassifier v15.1.3
• v4.2.0 => LaraClassifier v15.1.0 à v15.1.2
• v4.1.0 => LaraClassifier v15.0.0
• v4.0.0 => LaraClassifier v14.0.0 à v14.2.0
• v3.1 => LaraClassifier v12.0.0 à v13.0.0
• v3.0 => LaraClassifier v11.0.0 à v11.0.4
• v2.3 => LaraClassifier v10.2.0 à v10.2.6
• v2.2 => LaraClassifier v10.0.2 à v10.1.4
• v2.1 => LaraClassifier v10.0.0 à v10.0.1
• v2.0 => LaraClassifier v7.3.0 à v9.0.1
• v1.9 => LaraClassifier v7.3.0
• v1.8 => LaraClassifier v7.2.0 à v7.2.4
• v1.7 => LaraClassifier v7.1.0 à v7.1.1
• v1.6 => LaraClassifier v7.0.0 à v7.0.4
• v1.4 à v1.5 => LaraClassifier v6.8 à v6.9
• v1.3 => LaraClassifier v6.6 à v6.7
• v1.2 => LaraClassifier v6.0 à v6.5
• v1.1 => LaraClassifier v5.2 à v5.9
• v1.0 => LaraClassifier v5.1

Installation

Étape 1 : Téléverser l'add-on

Allez dans Panneau d'administration → Extensions → Add-ons, cliquez sur Téléverser un add-on et déposez le fichier .zip de l'add-on dans la zone de téléversement (50 Mo maximum). L'archive est extraite dans extensions/addons/currencyexchange/ et Currency Exchange apparaît dans la liste, désactivé.

Étape 2 : Activer l'add-on

Cliquez sur Activer sur la carte Currency Exchange. C'est un add-on payant : une fenêtre demande son code d'achat, qui est vérifié avant toute autre opération. Un code invalide est refusé dans la fenêtre et rien n'est modifié.

Une fois le code accepté, l'activation se fait en une seule passe : elle crée les tables de base de données de l'add-on (ses migrations), enregistre ses permissions, exécute ses seeders et publie ses assets publics. Rechargez la page pour voir sa nouvelle entrée dans la section Add-ons de la barre latérale d'administration.

Étape 3 : Configurer

Ouvrez Panneau d'administration → Currency Exchange depuis la section Add-ons de la barre latérale et configurez l'add-on : voir Utilisation.

Code d'achat (clé de licence)

Currency Exchange est vendu comme un produit séparé, il possède donc son propre code d'achat (clé de licence), distinct du code d'achat de l'application principale et de celui de chaque autre add-on. Il vous est demandé lorsque vous activez Currency Exchange dans Panneau d'administration → Extensions → Add-ons.

Nos produits sont vendus sur trois plateformes. La manière dont vous recevez un code d'achat dépend de l'endroit où vous avez acheté le produit.

1. Boutique bedigit.com (achat sur le site)

• Dès que le statut de paiement de la commande passe à Payée, une clé de licence est générée automatiquement pour chaque article sous licence de la commande (une clé par unité achetée : l'achat de 3 unités donne 3 clés distinctes).
• Elle est envoyée par e-mail à l'adresse utilisée sur la commande, soit dans un e-mail de licence dédié, soit dans l'e-mail de confirmation de commande. Vérifiez votre boîte de réception et votre dossier spam / courrier indésirable.
• La clé reste disponible dans votre compte sous Mon compte → Mes licences. Les clés sont masquées dans la liste ; ouvrez la page de détail de la licence pour révéler et copier la clé complète, voir les domaines sur lesquels elle est activée, et désactiver un domaine pour libérer un emplacement d'activation.
• La facture correspondante se trouve sous Mon compte → Mes commandes.

2. Gumroad

• Un achat Gumroad produit deux e-mails séparés : le reçu Gumroad (envoyé par Gumroad, donnant accès aux fichiers) et un e-mail de clé de licence (envoyé par bedigit.com) qui contient votre code d'achat.
• L'e-mail de clé de licence est généré dès que Gumroad nous notifie la vente, il arrive donc normalement quelques secondes après le paiement. Là aussi, vérifiez votre boîte de réception et votre dossier spam / courrier indésirable.
• Lorsque le produit Gumroad utilise la fonction de clé de licence propre à Gumroad, la même clé apparaît aussi dans votre reçu Gumroad et sous Bibliothèque → votre achat sur gumroad.com.
• Utilisez la même adresse e-mail sur bedigit.com que sur Gumroad : vos clés sont alors liées automatiquement à votre compte et listées sous Mon compte → Mes licences, même si vous vous inscrivez après l'achat. Vous pouvez aussi ajouter une clé Gumroad manuellement depuis Mon compte → Mes licences Gumroad.

3. Envato Market (CodeCanyon)

• Les codes d'achat Envato sont délivrés et distribués par Envato Market, jamais envoyés par e-mail par nous, il n'y a donc rien à chercher dans votre dossier spam : vous récupérez le code depuis votre compte Envato.
• Connectez-vous à votre compte Envato / CodeCanyon, ouvrez la page Downloads, trouvez l'article, et choisissez License certificate & purchase code dans le menu déroulant Download. Le code est inscrit dans ce certificat.
• Un code d'achat Envato ressemble à 12345678-90ab-cdef-1234-567890abcdef (8-4-4-4-12 caractères). Il ne change jamais, et le renouvellement du support de l'article n'en délivre pas de nouveau.
• Article officiel Envato : Where Is My Purchase Code?

Mise à jour

Une mise à jour ne remplace que les fichiers de l'add-on. Ses tables et ses données, ses paramètres, son état d'activation et son code d'achat enregistré sont tous conservés : ne désactivez et ne supprimez pas l'add-on avant de le mettre à jour. Sauvegardez tout de même votre base de données au préalable.

Méthode 1 : Téléverser la nouvelle version (recommandé)

1. Téléchargez le dernier fichier .zip de l'add-on.
2. Allez dans Panneau d'administration → Extensions → Add-ons et cliquez sur Téléverser un add-on.
3. Déposez le fichier .zip dans la zone de téléversement.
4. Comme Currency Exchange est déjà installé, une demande de confirmation affiche la version installée et la nouvelle. Cliquez sur Remplacer : le dossier extensions/addons/currencyexchange/ est remplacé par les nouveaux fichiers. Annuler la demande abandonne le téléversement.

Méthode 2 : Remplacer les fichiers à la main

1. Par FTP ou SSH, supprimez le dossier extensions/addons/currencyexchange/ et envoyez le nouveau à sa place. Remplacez le dossier entier plutôt que de copier par-dessus, afin que les fichiers retirés par la nouvelle version ne subsistent pas.
2. Ouvrez Panneau d'administration → Extensions → Add-ons : la page relit addon.json et la carte affiche le nouveau numéro de version.

Une fois les fichiers remplacés

Nouvelles tables ou colonnes. Lorsqu'une nouvelle version en ajoute, créez-les en exécutant php artisan migrate --force en SSH, ou sans SSH en cliquant sur Désactiver puis Activer sur la carte de l'add-on : l'activation exécute toutes les migrations en attente (et redemande le code d'achat). Vos données ne sont pas touchées dans les deux cas.

Si votre installation met en cache sa configuration ou ses routes (php artisan config:cache, route:cache), exécutez php artisan optimize:clear après la mise à jour.

Utilisation

Allez dans Panneau d'administration → Currency Exchange (dans la section Add-ons de la barre latérale). La page des paramètres comporte trois onglets ; cliquez sur Enregistrer pour appliquer vos modifications.

General (général)

Devises par pays. Pour proposer une liste différente dans un pays donné, allez dans Panneau d'administration → International → Pays, modifiez ce pays et remplissez son champ Currencies (affiché uniquement tant que l'add-on est actif) avec des codes ISO 4217 séparés par des virgules, par exemple USD,EUR,CHF. Les codes sont enregistrés en majuscules et les doublons sont supprimés. Pour les visiteurs qui consultent ce pays, cette liste remplace le paramètre Currencies ci-dessus ; laissez le champ vide pour utiliser le paramètre.

Service

Currency Base est la devise source des taux. Les formules gratuites des services payants ne fonctionnent qu'avec leur devise de base par défaut : ne la modifiez pas, sauf si vous utilisez une formule pro.

Options

Taux de change

Les taux récupérés sont enregistrés sur les devises. Tant que l'add-on est actif, le formulaire des devises dans Panneau d'administration → International → Devises affiche un champ Exchange Rate modifiable à la main, par exemple pour une devise que le service sélectionné ne fournit pas. Un taux saisi à la main est écrasé lors de la prochaine récupération des taux : augmentez donc le Cache TTL si vous gérez des taux manuellement. Si aucun taux n'est disponible pour la devise choisie, les prix restent dans la devise du pays et un avertissement s'affiche.

Variables d'environnement

Les clés .env facultatives suivantes ont priorité sur les valeurs enregistrées dans le panneau d'administration :

• CURRENCY_EXCHANGE_DRIVER (currencylayer, exchangerate_api, exchangeratesapi_io, openexchangerates, fixer_io, ecb, cbr, tcmb, nbu, cnb ou bnr) et CURRENCY_EXCHANGE_CACHE_TTL
• CURRENCYLAYER_ACCESS_KEY, CURRENCYLAYER_BASE, CURRENCYLAYER_PRO
• EXCHANGERATE_API_KEY, EXCHANGERATE_API_BASE
• EXCHANGERATESAPI_IO_ACCESS_KEY, EXCHANGERATESAPI_IO_BASE, EXCHANGERATESAPI_IO_PRO
• OPENEXCHANGERATES_APP_ID, OPENEXCHANGERATES_BASE
• FIXER_IO_ACCESS_KEY, FIXER_IO_BASE, FIXER_IO_PRO

Traduction

Pour traduire cet add-on dans votre langue :

• Allez dans le répertoire des langues de l'add-on, dans /extensions/addons/currencyexchange/resources/lang/ de l'application principale
• Dupliquez le dossier /extensions/addons/currencyexchange/resources/lang/en/ vers /extensions/addons/currencyexchange/resources/lang/<code>/
  NOTE : N'oubliez pas de remplacer <code> par le code de votre langue (par ex. "de" pour l'allemand).
• Ouvrez le fichier /extensions/addons/currencyexchange/resources/lang/<code>/messages.php et traduisez-le.
  NOTE : Pour traduire le fichier, vous devez modifier les valeurs et non les clés du tableau PHP.

Désinstallation

Éteindre un add-on sans rien perdre, c'est le désactiver : allez dans Panneau d'administration → Extensions → Add-ons, cliquez sur Désactiver sur la carte Currency Exchange et confirmez.

• L'add-on n'est plus chargé : ses routes, ses vues, son entrée dans la barre latérale d'administration et ses pages publiques ne répondent plus.
• Ses tables de base de données et toutes les données qu'elles contiennent sont conservées, et ses fichiers restent dans extensions/addons/currencyexchange/. Rien n'est supprimé.
• Ses permissions et son code d'achat enregistré restent en base de données. Seule la suppression les efface.
• La désactivation est refusée tant qu'un autre add-on actif dépend de celui-ci : désactivez d'abord cet add-on.

Cliquez sur Activer sur la même carte pour le rallumer. Comme lors de la première activation, le code d'achat est redemandé et vérifié ; ensuite les migrations en attente sont exécutées, les assets republiés, et l'add-on reprend exactement là où il s'était arrêté.

Suppression

La suppression est définitive et détruit les données de l'add-on. Le bouton Supprimer n'apparaît que sur un add-on désactivé : la suppression se fait donc toujours en deux temps :

1. Désactivez Currency Exchange (voir Désinstallation).
2. Cliquez sur Supprimer sur sa carte et confirmez la demande.

Le panneau d'administration, en une seule passe :

• exécute le hook de désinstallation de l'add-on, s'il en fournit un, tant que son code est encore sur le disque ;
• révoque les permissions déclarées dans son addon.json ;
• annule ses migrations, ce qui supprime ses tables de base de données et toutes les lignes qu'elles contiennent, et purge ses entrées de la table migrations, afin qu'une réinstallation ultérieure reparte de zéro ;
• supprime ses assets publiés : public/addons/currencyexchange/, public/vendor/currencyexchange/ et storage/app/public/addons/currencyexchange/ ;
• supprime le dossier de l'add-on extensions/addons/currencyexchange/ ;
• supprime sa ligne dans la table addons (le code d'achat enregistré disparaît avec elle) et vide le cache de l'application.

La suppression est refusée, avec un message explicatif et avant toute destruction, lorsque l'add-on est encore actif, lorsqu'un autre add-on actif en dépend, ou lorsque l'utilisateur du serveur web (PHP) ne peut pas supprimer extensions/addons/currencyexchange/. Dans ce dernier cas, donnez à cet utilisateur le droit d'écriture sur le dossier et sur son parent, puis réessayez.

Supprimer le dossier en FTP ou en SSH n'est pas équivalent : l'add-on est seulement éteint, et ses tables, ses entrées dans la table migrations et sa ligne addons restent en place. Utilisez plutôt Supprimer dans le panneau d'administration.