Download the PHP package hamadou/fundry without Composer

Fundry

Fundry est un package Laravel complet et robuste pour la gestion de portefeuilles virtuels, de transactions financières et de devises multiples. Conçu pour les applications e-commerce, plateformes de paiement, systèmes de gestion financière et applications nécessitant une gestion monétaire fiable.

📋 Table des matières

1. À propos du projet
2. Fonctionnalités
3. Architecture
4. Prérequis
5. Installation
6. Configuration
7. Concepts clés
8. Guide d'utilisation
9. Commandes Artisan
10. API Reference
11. Sécurité
12. Performance et Cache
13. Gestion des erreurs
14. Exemples complets
15. Tests
16. Dépannage
17. Contribution
18. Licence

🎯 À propos du projet

Fundry résout le problème complexe de la gestion financière dans les applications Laravel en fournissant un système de portefeuille simple, élégant et sécurisé. Que vous construisiez une plateforme e-commerce, une passerelle de paiement, ou une application de suivi financier, Fundry offre les outils nécessaires pour une gestion monétaire robuste.

Capacités principales

• ✅ Gestion multi-devises - Support complet des devises fiat et cryptomonnaies
• ✅ Transactions sécurisées - Verrous de base de données pour éviter les race conditions
• ✅ Système de commissions - Gestion flexible des frais de transaction
• ✅ Validation ISO 4217 - Codes de devise standardisés et validés
• ✅ Liaison Pays-Devises - Association automatique des devises aux pays
• ✅ Historique complet - Traçabilité totale des transactions
• ✅ Export de rapports - Génération PDF et Excel
• ✅ Limites configurables - Contrôles de sécurité personnalisables
• ✅ Cache intégré - Optimisation des performances
• ✅ Commandes CLI - Outils de gestion puissants

✨ Fonctionnalités

💰 Gestion de portefeuilles

• Création et gestion de portefeuilles multiples par utilisateur
• Types de portefeuilles : Personnel, Business, Épargne, Investissement, Gouvernemental
• Limites configurables (solde max/min, limite de transaction)
• Portefeuilles par défaut
• Statut actif/inactif
• Règles de sécurité personnalisables

💱 Support multi-devises

• Devises fiat (EUR, USD, XOF, etc.)
• Cryptomonnaies (BTC, ETH, USDT, etc.)
• Devises gouvernementales (device)
• Taux de change configurables
• Conversion automatique entre devises
• Validation ISO 4217 pour les devises fiat
• Liaison avec les pays (ISO 3166-1)

📊 Gestion des transactions

• Types de transactions : Dépôt, Retrait, Transfert, Échange, Frais, Remboursement
• Statuts : En attente, Complétée, Échouée
• Références uniques pour chaque transaction
• Métadonnées personnalisables
• Historique complet avec filtres
• Calcul de volumes quotidiens

🔐 Sécurité

• Vérification d'autorisation (wallet appartient à l'utilisateur)
• Verrous de base de données (lockForUpdate) pour la concurrence
• Validation stricte des montants
• Protection contre les montants négatifs
• Validation de précision décimale
• Exceptions explicites et sécurisées

📄 Exports et rapports

• Génération de rapports PDF
• Export Excel
• Filtres avancés (date, utilisateur, devise, type)
• Rapports sur transactions, portefeuilles, devises, limites

🏗️ Architecture

Structure du package

Flux de données

📦 Prérequis

• PHP : 8.1 ou supérieur
• Laravel : 10.x, 11.x, ou 12.x
• Extensions PHP :
  • bcmath (calculs monétaires précis)
  • json (métadonnées)
• Base de données : MySQL, PostgreSQL, SQLite, SQL Server
• Table users : Le package utilise la table users standard de Laravel. Aucune modification de structure n'est nécessaire. Il suffit d'ajouter le trait HasWallets au modèle User.

🚀 Installation

Étape 1 : Installation via Composer

Étape 2 : Publier les migrations et la configuration

Étape 3 : Configurer le modèle User

Le package utilise la table users existante de votre projet Laravel. Aucune modification de la structure de la table n'est nécessaire. Il suffit d'ajouter le trait HasWallets à votre modèle User :

Note importante : Le package utilise uniquement la colonne id de la table users. Aucun champ supplémentaire n'est requis dans la migration users. La table users standard de Laravel est suffisante.

Étape 4 : Exécuter les migrations

Cela créera les tables suivantes :

• countries - Pays et leurs devises
• currencies - Devises (fiat, crypto, device)
• wallets - Portefeuilles utilisateurs (avec foreign key vers users.id)
• transactions - Historique des transactions (avec foreign key vers users.id)

Important : Assurez-vous que votre table users existe avant d'exécuter les migrations, car les tables wallets et transactions ont des contraintes de clé étrangère vers users.id.

Étape 5 : Synchroniser les données de base

⚙️ Configuration

Fichier de configuration

Le fichier config/fundry.php contient toutes les options de configuration :

Variables d'environnement (.env)

🧠 Concepts clés

Portefeuille (Wallet)

Un portefeuille est un compte virtuel associé à un utilisateur et une devise. Chaque utilisateur peut avoir plusieurs portefeuilles.

Propriétés principales :

• balance : Solde actuel
• max_balance : Solde maximum autorisé
• min_balance : Solde minimum à maintenir
• transaction_limit : Limite par transaction
• type : Type de portefeuille (personnel, business, etc.)
• is_active : Statut actif/inactif
• is_default : Portefeuille par défaut

Transaction

Une transaction représente une opération financière (dépôt, retrait, transfert).

Types de transactions :

• DEPOSIT : Dépôt de fonds
• WITHDRAWAL : Retrait de fonds
• TRANSFER : Transfert entre portefeuilles
• EXCHANGE : Échange de devises
• FEE : Frais de transaction
• REFUND : Remboursement

Statuts :

• PENDING : En attente
• COMPLETED : Complétée
• FAILED : Échouée

Devise (Currency)

Une devise représente une unité monétaire (fiat, crypto, ou device).

Types de devises :

• FIAT : Monnaie fiduciaire (USD, EUR, XOF, etc.)
• CRYPTO : Cryptomonnaie (BTC, ETH, etc.)
• DEVICE : Devise gouvernementale

Propriétés :

• iso_code : Code ISO 4217 (3 lettres)
• exchange_rate : Taux de change par rapport à la devise de base
• decimals : Nombre de décimales
• country_id : Pays associé (pour fiat)

Pays (Country)

Un pays contient les informations géographiques et sa devise officielle.

Propriétés :

• iso_code : Code ISO 3166-1 alpha-2 (2 lettres)
• currency_code : Code devise ISO 4217
• continent : Continent
• capital : Capitale

DTO (Data Transfer Object)

Les DTOs encapsulent les données des transactions avec validation intégrée.

Avantages :

• Validation automatique
• Calcul des commissions
• Type-safe
• Réutilisable

📖 Guide d'utilisation

Utilisation de la Facade

Création d'un portefeuille

Dépôt de fonds

Méthode simple

Méthode avec DTO (recommandée)

Créer un DTO depuis un tableau

Retrait de fonds

Méthode simple

Méthode avec DTO

Transfert entre portefeuilles

Méthode simple

Méthode avec DTO

Consultation du solde

Conversion de devises

Utilisation du trait HasWallets

Le trait HasWallets ajoute des méthodes pratiques au modèle User :

Gestion des pays et devises

Créer un pays

Créer une devise liée à un pays

Rechercher une devise

🛠️ Commandes Artisan

Fundry fournit plusieurs commandes Artisan pour faciliter la gestion du système.

fundry:install

Installe et configure Fundry dans votre application.

Actions effectuées :

• Publie la configuration
• Publie les migrations
• Affiche les instructions de configuration

fundry:sync-countries

Synchronise les pays et leurs devises depuis le seeder.

Options :

• --force : Force la mise à jour même si les pays existent déjà

Exemple :

Ce que fait la commande :

• Charge les pays depuis CountrySeeder
• Crée ou met à jour les pays dans la base de données
• Affiche le nombre total de pays synchronisés

fundry:validate-currencies

Valide toutes les devises et détecte les problèmes potentiels.

Options :

• --fix : Corrige automatiquement les erreurs détectées

Exemple :

Vérifications effectuées :

• ✅ Codes ISO 4217 valides pour les devises fiat
• ✅ Taux de change valides (> 0)
• ✅ Relations avec les pays
• ✅ Codes normalisés en majuscules
• ✅ Cohérence des données

Sortie exemple :

fundry:update-rates

Met à jour les taux de change des devises.

Options :

• --provider=manual : Provider à utiliser (manual, exchangerate-api)
• --api-key= : Clé API pour le provider externe
• --base=USD : Devise de base pour les taux

Exemples :

Ce que fait la commande :

• Récupère les taux de change depuis le provider
• Met à jour les devises dans la base de données
• Nettoie le cache automatiquement
• Affiche les taux mis à jour

Sortie exemple :

fundry:currencies

Gère les devises (à compléter selon besoins).

Actions possibles :

• list : Liste toutes les devises
• sync : Synchronise les devises
• seed : Seed les devises de base

fundry:cash

Opérations cash (à compléter selon besoins).

fundry:crypto

Opérations crypto (sync rates, import data).

fundry:report

Génère des rapports PDF ou Excel pour les données Fundry.

Types de rapports :

• transactions : Rapport des transactions
• wallets : Rapport des portefeuilles
• currencies : Rapport des devises
• limits : Rapport des limites configurées

Options :

• --format=pdf : Format de sortie (pdf|excel)
• --start-date= : Date de début (YYYY-MM-DD)
• --end-date= : Date de fin (YYYY-MM-DD)
• --user-id= : Filtrer par utilisateur
• --wallet-type= : Type de portefeuille
• --currency= : Devise spécifique
• --output= : Fichier de sortie

Exemples :

Emplacement des rapports : Les rapports sont sauvegardés dans storage/app/reports/ par défaut.

📚 API Reference

Facade Fundry

Méthodes de portefeuille

Méthodes de transaction

Méthodes de devise

Modèles

Wallet

Transaction

Currency

Country

DTOs

DepositDTO

WithdrawalDTO

TransferDTO

🔒 Sécurité

Vérification d'autorisation

Toutes les opérations vérifient automatiquement que le wallet appartient à l'utilisateur :

Verrous de concurrence

Les opérations critiques utilisent des verrous de base de données (lockForUpdate()) pour éviter les race conditions :

Validation des montants

• ✅ Montants doivent être > 0
• ✅ Précision limitée à 8 décimales
• ✅ Validation des limites (max_balance, min_balance, transaction_limit)

Gestion des exceptions

⚡ Performance et Cache

Configuration du cache

Le cache est activé par défaut pour améliorer les performances :

Ce qui est mis en cache

• ✅ Devises par type
• ✅ Liste des devises supportées
• ✅ Recherche de devises par code ISO
• ✅ Conversions de devises

Nettoyer le cache

Le cache est automatiquement nettoyé lors de :

• Mise à jour d'une devise
• Synchronisation des taux de change
• Création/modification de devises

Désactiver le cache

🚨 Gestion des erreurs

Exceptions personnalisées

Codes d'erreur HTTP

• 400 : Requête invalide (montant invalide, devise invalide)
• 403 : Non autorisé (wallet n'appartient pas à l'utilisateur)
• 409 : Conflit (erreur de concurrence)

💡 Exemples complets

Exemple 1 : Système de paiement e-commerce

Exemple 2 : Transfert entre utilisateurs

Exemple 3 : Conversion multi-devises

Exemple 4 : Système de commissions dynamiques

Exemple 5 : Vérification de limites quotidiennes

🧪 Tests

Exécuter les tests

Structure des tests

🔧 Dépannage

Problème : "Currency not found"

Solution :

Problème : "Insufficient funds" même avec un solde suffisant

Causes possibles :

• Limite min_balance configurée
• Limite transaction_limit dépassée
• Commission non prise en compte dans le calcul

Solution :

Problème : Cache non mis à jour

Solution :

Problème : "UnauthorizedWalletException"

Cause : Le wallet n'appartient pas à l'utilisateur spécifié dans le DTO.

Solution :

🤝 Contribution

Les contributions sont les bienvenues ! Pour contribuer :

1. Fork le projet
2. Créer une branche pour votre fonctionnalité (git checkout -b feature/AmazingFeature)
3. Commit vos changements (git commit -m 'Add some AmazingFeature')
4. Push vers la branche (git push origin feature/AmazingFeature)
5. Ouvrir une Pull Request

Standards de code

• Suivre les standards PSR-12
• Ajouter des tests pour les nouvelles fonctionnalités
• Documenter le code
• Mettre à jour le README si nécessaire

📄 Licence

Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.

👤 Auteur

Hamadou Tall

• Email: [email protected]
• GitHub: @hamadou

🙏 Remerciements

• Laravel Framework
• Orchestra Testbench pour les tests
• Maatwebsite Excel pour les exports
• DomPDF pour la génération PDF

📞 Support

Pour toute question ou problème :

• Ouvrir une issue
• Contacter l'auteur : [email protected]

Fait avec ❤️ pour la communauté Laravel