Guide du module Petites Annonces pour Larapen

Une place de marché de petites annonces complète pour votre site Larapen. Les utilisateurs peuvent créer, parcourir, rechercher et gérer des annonces avec des champs personnalisés, un filtrage par localisation, des galeries d’images et une messagerie intégrée : le tout avec modération par l’administrateur et permissions granulaires.

Cas d’utilisation

Place de marché générale

Gérez un tableau de petites annonces de type Leboncoin où les utilisateurs publient des articles à vendre, des services ou des locations. Les catégories et les champs personnalisés vous permettent de structurer tout type d’annonce.

• Activez l’inscription des utilisateurs et la création d’annonces.
• Définissez des catégories (Véhicules, Électronique, Immobilier, Emploi, etc.) avec des champs personnalisés spécifiques à chaque catégorie.
• Activez la modération pour examiner les soumissions avant leur mise en ligne.
• Les acheteurs contactent directement les vendeurs via le formulaire de contact intégré.

Annuaire d’entreprises

Créez un annuaire d’entreprises locales avec des champs personnalisés pour les horaires d’ouverture, les services proposés et les coordonnées.

• Désactivez le champ prix ou rendez-le optionnel.
• Ajoutez des champs personnalisés comme “Horaires d’ouverture”, “URL du site web” et “Services proposés”.
• Utilisez les champs de localisation (ville, région, adresse) pour le filtrage géographique.

Tableau d’actifs interne

Un tableau privé permettant à une organisation de lister et d’échanger des actifs, équipements ou ressources internes.

• Désactivez la navigation pour les visiteurs : exigez la connexion pour voir les annonces.
• Désactivez la publication publique : seuls les administrateurs créent les annonces.
• Utilisez le champ “état” (neuf, occasion, reconditionné) pour le suivi des actifs.

Prérequis

Installation

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

Dans le panneau d’administration, allez dans Admin → Extensions → Add-ons et cliquez sur le bouton Télécharger un add-on. Sélectionnez le fichier ZIP de l’add-on : le système le décompresse automatiquement et l’add-on apparaît dans la liste des add-ons installés.

Étape 2 : Activer l’add-on

Repérez Petites annonces dans la liste et cliquez sur Activer. Ses migrations, ses seeders (le cas échéant) et ses permissions sont mis en place automatiquement.

Étape 3 : Configurer

Naviguez vers Admin → Petites annonces → Paramètres pour configurer les catégories, les formules tarifaires, les règles de modération et les notifications. Voir Configuration.

Code d’achat (clé de licence)

Petites annonces 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 Petites annonces dans Panneau d’administration → Add-ons.

Nos produits sont vendus sur trois plateformes. La façon 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 devient 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 : acheter 3 unités donne 3 clés distinctes).
• Elle est envoyée par e-mail à l’adresse utilisée pour 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 afficher 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 sur Gumroad produit deux e-mails distincts : 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. Ici aussi, vérifiez votre boîte de réception et votre dossier spam / courrier indésirable.
• Lorsque le produit Gumroad utilise la fonctionnalité de clés 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 fournis par Envato Market, jamais envoyés par e-mail par nous, il n’y a donc rien à chercher dans votre dossier de 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?

Configuration

Les valeurs par défaut de configuration sont définies dans config/classified.php et peuvent être remplacées via les paramètres d’administration (stockés en base de données avec le préfixe classified_).

Paramètres de notification

Chaque notification peut être activée ou désactivée individuellement depuis le panneau des paramètres d’administration :

Admin : Paramètres

Accès via Admin → Petites annonces → Paramètres. La page des paramètres est organisée en sections logiques :

• Publication : Activez ou désactivez la création d’annonces par les utilisateurs, la navigation pour les visiteurs et le contact par les visiteurs.
• Modération : Activez ou désactivez l’approbation par un administrateur pour les nouvelles annonces.
• Durée des annonces : Définissez le nombre de jours pendant lesquels les annonces restent actives (0 pour une durée illimitée).
• Images : Nombre maximum d’images par annonce.
• Coordonnées : Si le numéro de téléphone est requis.
• Fonctionnalités : Activez ou désactivez les signalements et les favoris.
• Traductions : Autorisez les auteurs à fournir du contenu multilingue.
• Notifications : Activez ou désactivez chacun des 7 types de notification.

Admin : Annonces

La page de gestion des annonces fournit un tableau paginé de toutes les annonces avec filtrage par statut et par catégorie. Chaque ligne affiche le titre de l’annonce, l’auteur, la catégorie, le badge de statut, le prix, le nombre de vues, le nombre de messages, le nombre de signalements et la date de création.

Création & modification

Le formulaire d’annonce comprend des champs pour :

• Contenu : Titre (traduisible), contenu/description (traduisible), méta titre, méta description
• Classification : Sélection de la catégorie, état de l’article (neuf, occasion, reconditionné)
• Tarification : Prix, devise, indicateur négociable
• Localisation : Ville, région, pays, adresse, latitude/longitude
• Contact : Nom du contact, e-mail, téléphone
• Média : Image principale + images de la galerie (jusqu’au maximum configuré)
• Champs personnalisés : Champs dynamiques chargés en fonction de la catégorie sélectionnée (via AJAX)
• Statut : Brouillon, en attente de validation, publié (l’administrateur peut contourner la modération)
• Options : Mise en avant, date d’expiration, position

Modération

Lorsque la modération est activée, les nouvelles annonces sont placées au statut pending_review. Les administrateurs peuvent les approuver ou les rejeter :

Admin : Catégories

Les catégories de petites annonces utilisent la table unifiée categories du noyau avec categorizable_type = 'listing'. Les catégories prennent en charge l’imbrication (hiérarchie parent/enfant via ensemble imbriqué) et sont traduisibles.

Admin : Champs personnalisés

Les champs personnalisés vous permettent d’étendre les annonces avec des attributs globaux ou spécifiques à une catégorie. Les champs peuvent être marqués comme filtrables (affichés dans les filtres de recherche) et recherchables (inclus dans la recherche plein texte).

Types de champs pris en charge

Admin : Messages

Consultez tous les messages envoyés via les formulaires de contact des annonces. Les messages peuvent être filtrés par statut lu/non lu.

Admin : Signalements

Consultez et gérez les signalements d’annonces soumis par les utilisateurs. Les signalements comportent un motif (spam, contenu inapproprié, fraude, mauvaise catégorie, annonce en double ou autre) et une description optionnelle.

Motifs de signalement

Front-end : Navigation & recherche

La page publique des petites annonces affiche les annonces publiées et non expirées, triées par mise en avant, date de publication et position. Les visiteurs peuvent filtrer et rechercher des annonces selon plusieurs critères.

Options de recherche & de filtrage

Navigation par catégorie

Accès via /classifieds/category/{slug}. Affiche les annonces filtrées par la catégorie indiquée, avec la recherche et le filtrage complets disponibles au sein de cette catégorie.

Front-end : Détail de l’annonce

Accès via /classifieds/{slug}. La page de détail de l’annonce comprend :

• Titre complet, description et valeurs des champs personnalisés
• Galerie d’images (image principale + images supplémentaires de la galerie)
• Prix avec formatage de la devise et indicateur négociable
• Badge de l’état de l’article
• Informations de localisation (ville, région, pays, adresse)
• Coordonnées du vendeur
• Formulaire de contact (pour envoyer un message au vendeur)
• Bouton sauvegarder/retirer des favoris (pour les utilisateurs authentifiés)
• Bouton de signalement (pour les utilisateurs authentifiés)
• Annonces similaires (même catégorie ou même ville)
• Nombre de vues (incrémenté à chaque visite)

Front-end : Créer & modifier des annonces

Les utilisateurs authentifiés peuvent créer et modifier leurs propres annonces depuis le front-end. Cette fonctionnalité peut être désactivée pour tout le site en définissant allow_publishing à false.

Front-end : Mes annonces

Accès via /classifieds/my/listings. Les utilisateurs authentifiés peuvent consulter toutes leurs annonces avec des onglets par statut : toutes, actives, en attente, expirées, vendues et brouillons.

Depuis cette page, les utilisateurs peuvent :

• Voir le statut de l’annonce et le nombre de messages
• Modifier leurs annonces
• Supprimer leurs annonces

Front-end : Annonces sauvegardées

Accès via /classifieds/my/saved. Les utilisateurs peuvent mettre des annonces en favoris et les consulter plus tard depuis une page dédiée aux annonces sauvegardées.

Front-end : Contacter le vendeur

Chaque page de détail d’annonce inclut un formulaire de contact qui envoie un message au propriétaire de l’annonce.

Le contact par les visiteurs se contrôle via le paramètre guest_contact. Lorsqu’il est désactivé, seuls les utilisateurs authentifiés peuvent envoyer des messages.

Front-end : Signalement

Les utilisateurs authentifiés peuvent signaler les annonces qui violent les règles de la communauté.

Notifications

L’add-on inclut 7 classes de notification par e-mail, toutes étendant BaseNotification et utilisant le canal mail. Chaque notification peut être activée ou désactivée individuellement via les paramètres d’administration.

Mise à jour

Il existe deux façons de mettre cet add-on à jour : via le panneau d’administration (recommandé) ou en remplaçant manuellement les fichiers.

Méthode 1 : Téléversement via le panneau d’administration (recommandé)

1. Téléchargez le dernier fichier .zip de cet add-on.
2. Allez dans Panneau d’administration → Add-ons et cliquez sur le bouton Téléverser.
3. Sélectionnez ou faites glisser le fichier .zip dans la zone de téléversement.
4. Une invite de confirmation affichera les numéros de version actuelle et nouvelle. Cliquez sur Remplacer pour continuer.
5. Allez dans Panneau d’administration → Mise à jour du système (/admin/update) pour appliquer les migrations de base de données en attente.

Méthode 2 : Remplacement manuel des fichiers

Étape 1 : Remplacer les fichiers

Remplacez le répertoire de l’add-on par la nouvelle version.

Étape 2 : Exécuter les migrations

php artisan migrate

Les migrations en attente ne s’exécutent qu’une seule fois : la commande peut être relancée sans risque.

Étape 3 : Vider les caches

php artisan config:clear
php artisan route:clear
php artisan view:clear

Étape 4 : Vérifier

Rendez-vous sur Admin → Petites annonces → Paramètres et confirmez que tous les paramètres sont intacts. Parcourez la page des petites annonces pour vérifier que les annonces s’affichent correctement.

Désinstallation

Éteindre un add-on sans rien perdre, c’est le désactiver : allez dans Panneau d’administration → Add-ons, trouvez Classified Ads et cliquez sur Désactiver.

• Ses routes, ses vues, ses entrées de menu d’administration et ses permissions cessent d’être enregistrées, 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/classified/. Rien n’est supprimé.
• Le code d’achat enregistré lors de l’activation est conservé lui aussi : réactiver l’add-on ne le redemande pas.
• 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. Les migrations en attente sont rejoué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 Classified Ads (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/classified/, public/vendor/classified/ et storage/app/public/addons/classified/ ;
• supprime le dossier de l’add-on extensions/addons/classified/ ;
• 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/classified/. 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 : les tables de l’add-on, ses entrées dans la table migrations et sa ligne addons restent en place, et sa carte reste dans la liste. Utilisez plutôt Supprimer dans le panneau d’administration.

Dépannage

Les annonces ne sont pas visibles en front-end

Vérifiez que :

• Le statut de l’annonce est published (et non draft, pending, expired, rejected ou sold).
• La date published_at est dans le passé.
• La date expires_at est soit null, soit dans le futur.
• La navigation pour les visiteurs est activée si vous n’êtes pas connecté (vérifiez le paramètre guest_browse).

Les utilisateurs ne peuvent pas créer d’annonces

• Assurez-vous que allow_publishing est défini à true dans les paramètres d’administration.
• Vérifiez que l’utilisateur est authentifié (la création d’annonces nécessite une connexion).
• Vérifiez que le middleware CheckPublishingEnabled ne bloque pas l’accès.

Les champs personnalisés n’apparaissent pas dans le formulaire d’annonce

• Assurez-vous que le champ personnalisé est actif (is_active = true).
• Vérifiez que le champ est soit global (category_id = null), soit assigné à la catégorie sélectionnée.
• Consultez la console du navigateur pour repérer les erreurs AJAX sur l’endpoint /api/classified/custom-fields/.
• Assurez-vous que JavaScript est activé et que l’élément de sélection de catégorie déclenche l’appel AJAX.

Les annonces restent bloquées en “En attente de validation”

• La modération est activée par défaut. Allez dans Admin → Petites annonces → Annonces et approuvez les annonces en attente.
• Pour désactiver la modération, définissez moderation_enabled à false dans les paramètres d’administration. Les nouvelles annonces seront publiées immédiatement.

Les notifications ne sont pas envoyées

• Vérifiez que le paramètre de notification correspondant est activé (ex. notify_admin_on_new_listing).
• Assurez-vous que votre configuration de messagerie est correcte dans .env (SMTP, Mailgun, etc.).
• Consultez le journal Laravel (storage/logs/laravel.log) pour repérer les erreurs de messagerie.
• Si l’annonce n’a pas d’utilisateur associé, assurez-vous que le contact_email est défini sur l’annonce pour la livraison de secours.

Les annonces expirées s’affichent toujours

• La méthode expireOldListings() de ClassifiedService doit être appelée pour mettre le statut à jour. Cela doit être planifié comme tâche cron ou commande artisan.
• Les annonces dont expires_at est dans le passé sont automatiquement exclues du scope active(), mais leur champ de statut n’est mis à jour que lorsque le processus d’expiration s’exécute.

Les images ne se téléversent pas

• Vérifiez les paramètres PHP upload_max_filesize et post_max_size.
• Vérifiez que le répertoire storage est accessible en écriture.
• Assurez-vous de ne pas avoir dépassé la limite max_images configurée dans les paramètres d’administration.

Les compteurs d’annonces par catégorie sont incorrects

• Les compteurs d’annonces sont calculés dynamiquement via withCount. Si les compteurs semblent obsolètes, videz le cache de l’application : php artisan cache:clear.

Le basculement sauvegarder/favoris ne fonctionne pas

• Assurez-vous que l’utilisateur est authentifié (la sauvegarde nécessite une connexion).
• Vérifiez que enable_favorites est défini à true dans les paramètres d’administration.
• Consultez la console du navigateur pour repérer les erreurs AJAX sur l’endpoint de basculement.
• Assurez-vous que le jeton CSRF est inclus dans les en-têtes de la requête.