Guide du module Banque de médias pour Larapen

Une marketplace complète de photos et de vidéos libres de droits pour Larapen : vendez vos propres médias avec des aperçus filigranés, l’intégration de vidéos YouTube non répertoriées, un traitement en arrière-plan via file d’attente, l’import en masse par FTP/SFTP, et des téléchargements sécurisés par URL signée, accompagnés d’un PDF de licence par projet.

Cas d’utilisation

Boutique portfolio de photographe

Vous êtes photographe et vous souhaitez vendre des téléchargements sous licence de vos œuvres.

• Téléversez des sources en haute résolution : les acheteurs ne voient que des aperçus filigranés tant qu’ils n’ont pas payé.
• Proposez des licences Personnelle, Commerciale et Étendue à des prix différents sur le même élément.
• Laissez les clients acheter sans compte : une adresse e-mail d’invité suffit pour recevoir le lien de téléchargement.
• Chaque téléchargement inclut un PDF de licence indiquant le nom de l’acheteur et le projet unique qu’elle couvre.

Marketplace de séquences vidéo

Vous vendez des clips vidéo et vous voulez des aperçus sûrs sans exposer le fichier complet.

• L’add-on génère un court extrait d’aperçu filigrané et l’envoie sur YouTube en mode non répertorié.
• Le lecteur YouTube non répertorié est intégré à la page de détail ; le MP4 source reste privé.
• Nécessite ffmpeg/ffprobe sur le serveur pour le traitement vidéo.

Catalogue en masse depuis un dépôt SFTP

Vous avez des milliers de fichiers à publier et vous ne voulez pas les téléverser un par un.

• Organisez les fichiers dans des dossiers par catégorie sur un serveur SFTP.
• Ajoutez un fichier annexe .meta.json facultatif pour définir le titre, le prix, la licence et le statut de chaque fichier.
• Le planificateur analyse le dossier toutes les quelques minutes, met en file une tâche d’import par nouveau fichier et les traite en arrière-plan.
• Les fichiers importés sont déplacés dans un dossier _processed ; les échecs définitifs sont déplacés dans _failed et les administrateurs sont notifiés.

Prérequis

• Larapen CMS v1.0.0 ou ultérieur
• PHP 8.3+
• MySQL 8.0+
• L’extension PHP ZIP (les téléchargements sont transmis sous forme d’archives ZIP)
• Un worker de file d’attente en fonctionnement, qui consomme les files media, video, import et default
• ffmpeg et ffprobe sur le serveur : requis uniquement pour les éléments vidéo (les photos fonctionnent sans eux)

Installation

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

Dans le panneau d’administration, allez dans Admin → Add-ons et cliquez sur Téléverser 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 Stock Media dans la liste et cliquez sur Activer. Ses migrations et ses permissions sont mises en place automatiquement. L’activation crée sept tables stockmedia_ et enregistre 14 permissions.

Étape 3 : Démarrer les workers de file d’attente

Les traitements lourds de médias s’exécutent sur des files dédiées. Démarrez un worker qui les consomme toutes :

php artisan queue:work --queue=video,media,import,default --tries=3

Étape 4 : Configurer

Allez dans Admin → Stock Media → Paramètres pour définir le disque de stockage, la tarification par défaut, le filigrane, l’import FTP/SFTP et YouTube. Voir Configuration.

Étape 5 : Créer des catégories & des éléments

Créez au moins une catégorie dans Stock Media → Catégories, puis ajoutez votre premier élément dans Stock Media → Éléments → Ajouter un élément.

Code d’achat (clé de licence)

Stock Media 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 Stock Media 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 paramètres sont gérés sur une page unique à onglets, Admin → Stock Media → Paramètres (stockés dans la table settings avec le préfixe stockmedia_). Les valeurs par défaut du fichier de configuration se trouvent dans config/stockmedia.php. La page comporte quatre onglets (Général, Filigrane, FTP/SFTP et YouTube), plus un onglet En-tête de page pour personnaliser l’en-tête côté front-end.

Paramètres généraux

Paramètres du filigrane

Le filigrane se configure séparément pour les photos et pour les vidéos. Téléversez d’abord votre PNG de filigrane (avec transparence) dans la Médiathèque du noyau, puis collez son identifiant de média dans le champ correspondant.

Paramètres d’import FTP / SFTP

Paramètres YouTube

Après avoir enregistré vos identifiants client, cliquez sur Se connecter à YouTube et accordez la portée demandée. Le jeton d’actualisation est stocké chiffré dans la table des paramètres.

Admin : Éléments

Les éléments sont les photos et les vidéos que vous vendez. Ils se gèrent dans Stock Media → Éléments.

Créer un élément

Le formulaire d’élément (Éléments → Ajouter un élément) recueille :

• Type : photo ou vidéo.
• Titre, description, texte alternatif, mots-clés (traduisibles).
• Catégorie : rattache l’élément à une catégorie du noyau.
• Fichier source : le fichier original en haute résolution, stocké sur le disque de stockage configuré.
• Prix par licence : un prix pour chaque niveau proposé (Personnelle, Commerciale, Étendue). Un niveau sans prix n’est tout simplement pas proposé. Un niveau à 0 est proposé gratuitement.
• Devise et titre/description SEO (traduisibles).
• Statut : draft, published ou archived.

Traitement & statut

Lorsqu’un élément est créé ou que sa source change, l’add-on lance une tâche en arrière-plan (ProcessPhotoJob ou ProcessVideoJob) qui génère l’aperçu filigrané, les miniatures (miniature / moyenne / grande) et, pour une vidéo, un extrait d’aperçu filigrané envoyé sur YouTube. L’élément affiche un badge de statut de traitement :

• pending → en file d’attente, pas encore traité
• processing → un worker génère les aperçus
• ready → aperçus générés ; l’élément peut être publié et acheté
• failed → erreur de traitement (affichée dans les notifications d’administration ; l’élément porte un message processing_error)

Retraitement

Si le traitement échoue (par exemple parce que ffmpeg était absent), utilisez l’action Retraiter sur l’élément pour relancer ses tâches. La permission stockmedia.items.reprocess contrôle cette action.

Admin : Catégories

Les catégories organisent votre catalogue et alimentent les pages de catégorie du front-end. Elles se gèrent dans Stock Media → Catégories. Elles réutilisent la table categories du noyau avec le type catégorisable stockmedia_item.

• CRUD standard : créer, modifier, supprimer.
• Réorganiser : un écran dédié de réorganisation par glisser-déposer détermine l’ordre d’affichage des catégories.
• Les catégories servent aussi de noms de dossiers pour l’import FTP/SFTP (voir Import FTP).

Admin : Paramètres

Toutes les options de l’add-on se trouvent sur la page Paramètres unique à onglets. Voir la section Configuration pour la référence complète de chaque onglet et de chaque paramètre : Général, Filigrane, FTP/SFTP et YouTube.

Admin : Import FTP / SFTP

Le processus d’import vous permet de publier des fichiers en masse depuis un serveur SFTP (ou FTP), organisés par slug de catégorie. Il se gère dans Stock Media → Import.

Organisation des dossiers

Créez un dossier par slug de catégorie sous la racine configurée. Chaque fichier peut avoir un fichier annexe .meta.json facultatif qui remplace le titre, le prix, la licence et d’autres champs :

/<root>/
  /sunsets/
    photo-001.jpg
    photo-001.jpg.meta.json   # optional
  /city-life/
    skyline.mp4
    skyline.mp4.meta.json

{
  "title":        { "en": "Sunset over Paris" },
  "keywords":     ["sunset", "paris"],
  "is_free":      false,
  "price":        9.99,
  "currency":     "USD",
  "license_type": "commercial",
  "status":       "published"
}

Déroulement de l’import

• Le planificateur exécute stockmedia:import toutes les 5 minutes par défaut (configurable dans config/stockmedia.php).
• Chaque nouveau fichier devient une ligne de stockmedia_import_jobs et est traité en arrière-plan.
• Types d’images acceptés : jpg, jpeg, png, webp, avif. Types de vidéos acceptés : mp4, mov, mkv, webm.
• Les fichiers importés avec succès sont déplacés dans <root>/_processed/… ; les échecs définitifs sont déplacés dans <root>/_failed/… et les administrateurs reçoivent une notification.
• Vous pouvez aussi lancer une exécution manuellement depuis l’écran Import, ou via la ligne de commande :

php artisan stockmedia:import --limit=50
php artisan stockmedia:import --category=sunsets

Tableau des tâches d’import

L’écran Import liste les tâches d’import récentes avec leur catégorie, le type détecté, un badge de statut (queued, processing, imported, failed, skipped) et l’éventuel message d’erreur.

Admin : Achats

Chaque paiement (payant ou gratuit) crée un enregistrement d’achat. Les achats se gèrent dans Stock Media → Achats.

• Liste : numéro d’achat, e-mail/nom de l’acheteur, total, devise, badge de statut et date.
• Détail : le ou les éléments achetés, le niveau de licence, le moyen et la référence de paiement, les transactions et les compteurs de téléchargement.
• Remboursement : un administrateur disposant de la permission stockmedia.orders.refund peut rembourser un achat payé, ce qui passe son statut à refunded et révoque l’accès au téléchargement.

Les valeurs de statut d’achat sont pending, paid, failed, refunded et expired. Les numéros d’achat suivent le modèle SM-YYYY-000001.

Admin : Rapports

Le rapport des ventes (Stock Media → Rapports) résume le chiffre d’affaires et le volume des ventes dans le temps. Il nécessite la permission stockmedia.reports.view.

Widgets du tableau de bord

L’add-on ajoute également trois widgets au tableau de bord d’administration du noyau :

• Ventes récentes : les derniers achats finalisés.
• Meilleurs éléments : les éléments les plus vendus selon le nombre d’achats.
• File de traitement : les éléments actuellement en attente ou en cours de traitement.

Front-end : Parcourir & détail

Parcourir

Le catalogue public se trouve à l’adresse /stock (et /{locale}/stock). Les visiteurs peuvent parcourir tous les éléments publiés et filtrer par catégorie à l’adresse /stock/category/{slug}. Chaque carte affiche l’aperçu filigrané, le titre et le prix.

Détail d’un élément

La page de détail, à l’adresse /stock/{slug}, affiche :

• L’aperçu filigrané (photo) ou le lecteur YouTube non répertorié intégré (vidéo).
• Le titre, la description, les dimensions, le format d’image et, pour une vidéo, la durée et la fréquence d’images.
• Les niveaux de licence proposés et leurs prix, avec le détail de la couverture de chaque niveau (monde entier, perpétuelle, projet unique, usage commercial, revente, etc.).
• Un appel à l’action Acheter maintenant (ou Obtenir gratuitement).

Front-end : Achat & paiement

Éléments payants

1. L’acheteur choisit un niveau de licence et clique sur Acheter maintenant, ce qui l’amène sur /stock/checkout/{slug}.
2. Il indique une adresse e-mail, un nom facultatif et un nom de projet (les licences sont accordées par projet), puis choisit un moyen de paiement.
3. L’add-on crée un achat en attente et passe la main à la passerelle sélectionnée (Stripe, PayPal, Paddle ou MoMo).
4. Lorsque la passerelle confirme le paiement, l’achat est marqué comme payé et l’acheteur reçoit un lien de téléchargement signé par e-mail.

Éléments gratuits

Les éléments dont le niveau sélectionné est à 0 utilisent le parcours gratuit à l’adresse /stock/free/{slug}. L’acheteur indique tout de même un nom de projet (et une adresse e-mail si stockmedia_free_require_email est activé). L’achat est créé et immédiatement marqué comme payé avec total = 0, aucune passerelle n’intervient, et le lien de téléchargement est envoyé.

Front-end : Téléchargement & licences

Les téléchargements sont servis par une route signée unique : /stock/download/{purchase}/{item}.

• Le lien contenu dans l’e-mail de l’acheteur est une URL signée temporaire qui expire au bout de stockmedia_download_expiry_days jours (0 = en pratique jamais).
• Les propriétaires connectés peuvent aussi télécharger directement depuis leur compte sans lien signé (la propriété est vérifiée).
• Chaque élément peut être téléchargé jusqu’à stockmedia_max_downloads fois (0 = illimité). Le dépassement de la limite, un achat expiré ou un achat non payé renvoie une erreur.
• Chaque téléchargement est consigné dans une table d’audit (IP, agent utilisateur, octets servis).

Contenu du ZIP

Le téléchargement est transmis sous forme d’archive ZIP contenant :

• Le fichier source original.
• Un certificat PDF de licence indiquant l’acheteur, le projet et les clauses du niveau de licence.
• Un court README.txt destiné aux acheteurs non techniques.

Niveaux de licence

Front-end : Mes téléchargements

Les acheteurs connectés disposent d’une entrée Mes téléchargements dans le menu de leur compte, qui mène à /account/stockmedia/purchases. Elle liste leurs achats et relie chacun à une page de détail (/account/stockmedia/purchases/{number}) où ils peuvent retélécharger les éléments achetés (dans la limite du nombre de téléchargements et de la date d’expiration).

Notifications

L’add-on enregistre cinq types de notifications auprès du système de notifications central (Admin → Paramètres → Notifications) :

Mise à jour

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

Méthode 1 : Téléversement depuis 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 Téléverser.
3. Sélectionnez ou glissez le fichier .zip dans la zone de téléversement.
4. Une demande de confirmation affiche les numéros de version actuel et nouveau. 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

1. Remplacez le dossier extensions/addons/stockmedia par la nouvelle version.
2. Exécutez php artisan migrate pour appliquer les nouvelles migrations.
3. Videz les caches : php artisan config:clear && php artisan view:clear && php artisan route:clear.
4. Redémarrez vos workers de file d’attente pour qu’ils prennent en compte le nouveau code des tâches.

Désinstallation

Éteindre un add-on sans rien perdre, c’est le désactiver : allez dans Panneau d’administration → Add-ons, trouvez Stock Media 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/stockmedia/. 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 Stock Media (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/stockmedia/, public/vendor/stockmedia/ et storage/app/public/addons/stockmedia/ ;
• supprime le dossier de l’add-on extensions/addons/stockmedia/ ;
• 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/stockmedia/. 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

Élément bloqué sur “pending” ou “processing”

• Vérifiez qu’un worker de file d’attente est en cours d’exécution et consomme les files media, video et import.
• Consultez la table failed_jobs et le fichier storage/logs/laravel.log pour repérer les erreurs de tâches.
• Utilisez l’action Retraiter (ou php artisan stockmedia:reprocess {id}) pour relancer le traitement.

Le traitement des vidéos échoue

• Le traitement vidéo nécessite ffmpeg et ffprobe. Installez-les sur le serveur.
• Utilisez le bouton Tester ffmpeg de l’onglet de paramètres Filigrane pour confirmer que Larapen peut appeler le binaire.
• Si l’envoi sur YouTube échoue, l’élément est tout de même traité, mais l’aperçu YouTube est marqué en échec et les administrateurs sont notifiés.

Élément invisible sur le front-end

• L’élément doit être publié et avoir le statut de traitement prêt.
• Si une date published_at est définie, elle doit être passée.
• Au moins un niveau de licence doit avoir un prix, sinon l’élément n’a rien à vendre.

L’import FTP / SFTP ne fait rien

• Vérifiez que stockmedia_ingest_enabled est activé et que l’hôte est défini, puis utilisez Tester la connexion.
• Les fichiers doivent se trouver dans un dossier portant le slug d’une catégorie existante.
• Exécutez php artisan stockmedia:import manuellement pour voir le nombre de fichiers mis en file ; vérifiez que le planificateur fonctionne.

L’acheteur n’a pas reçu le lien de téléchargement

• Vérifiez votre configuration de messagerie dans .env (SMTP, Mailgun, etc.).
• Assurez-vous qu’un worker consomme la file default (les notifications sont mises en file d’attente).
• Vérifiez que le webhook de la passerelle s’est bien déclenché et que l’achat est marqué paid.

Le lien de téléchargement renvoie une erreur

• 410 Gone : la limite de téléchargements de l’élément est atteinte, le lien a expiré, ou l’achat n’est plus payé.
• 403 : un lien non signé a été utilisé par une personne qui n’est pas propriétaire. Utilisez le lien signé de l’e-mail, ou connectez-vous en tant qu’acheteur.
• Assurez-vous que l’extension PHP ZIP est installée et que storage/app est accessible en écriture.