PHPackages mbsoft31/loyalty-rewards - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. mbsoft31/loyalty-rewards ActiveLibrary[Utility & Helpers](/categories/utility) mbsoft31/loyalty-rewards ======================== A flexible loyalty rewards system for PHP applications v1.1.0(7mo ago)025MITPHPPHP ^8.2CI passing Since Sep 26Pushed 7mo agoCompare [ Source](https://github.com/mbsoft31/loyalty-rewards)[ Packagist](https://packagist.org/packages/mbsoft31/loyalty-rewards)[ RSS](/packages/mbsoft31-loyalty-rewards/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (2)Dependencies (7)Versions (3)Used By (0) ๐ŸŽฏ Loyalty Rewards System ======================== [](#-loyalty-rewards-system) [![Tests](https://github.com/mbsoft31/loyalty-rewards/actions/workflows/tests.yml/badge.svg)](https://github.com/mbsoft31/loyalty-rewards/actions/workflows/tests.yml)[![PHP Version](https://camo.githubusercontent.com/c9f64f714c636ba27a3bba6dfd52f98426832db1262747efa54b212d16943651/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e322d626c7565)](https://php.net)[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](LICENSE)[![Latest Version](https://camo.githubusercontent.com/0e2d3e3ef0556b566cedce6525923a512d39eed70d460275f8e67bdb98785eda/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f6d62736f667433312f6c6f79616c74792d72657761726473)](https://github.com/mbsoft31/loyalty-rewards/releases)[![Laravel Adapter](https://camo.githubusercontent.com/09f7b5fa439dd2df0dab46ec8582632a9677ab061abbe60c4008cdf2a0126a1f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d416461707465722d626c756576696f6c6574)](packages/loyalty-rewards-laravel) A comprehensive, enterprise-grade loyalty rewards system for PHP applications. Built with Domain-Driven Design principles, this package provides flexible point earning/redemption, fraud detection, audit logging, and multi-tier reward programs. โœจ Features ---------- [](#-features) - ๐ŸŽ Flexible Rewards Engine โ€” Category multipliers, tier bonuses, time-based promotions - ๐Ÿ›ก๏ธ Built-in Fraud Detection โ€” Velocity checks, amount validation, suspicious activity alerts - ๐Ÿ“Š Complete Audit Trail โ€” Full transaction logging with compliance support - โšก High Performance โ€” Handles 1000+ transactions/second with optimized database queries - ๐Ÿงช 100% Test Coverage โ€” Comprehensive test suite with unit, integration, and performance tests - ๐Ÿ”ง Framework Agnostic โ€” Works with Laravel, Symfony, or standalone PHP applications - ๐Ÿ’Ž Type Safe โ€” Full PHP 8.2+ type declarations with strict type checking ๐Ÿš€ Quick Start ------------- [](#-quick-start) ### Installation [](#installation) composer require mbsoft31/loyalty-rewards ### Basic Usage [](#basic-usage) ``` use LoyaltyRewards\Core\Services\LoyaltyService; use LoyaltyRewards\Domain\ValueObjects\{CustomerId, Money, Currency, TransactionContext}; use LoyaltyRewards\Rules\Earning\CategoryMultiplierRule; // Setup $loyaltyService = new LoyaltyService(/* dependencies */); // Create customer account $customerId = CustomerId::fromString('customer_12345'); $account = $loyaltyService->createAccount($customerId); // Configure earning rules $rulesEngine->addEarningRule( new CategoryMultiplierRule('electronics', 2.0, ConversionRate::standard()) ); // Earn points from purchase $result = $loyaltyService->earnPoints( $customerId, Money::fromDollars(99.99, Currency::USD()), TransactionContext::earning('electronics', 'online_store') ); echo "Earned: {$result->pointsEarned->value()} points"; echo "Balance: {$result->newAvailableBalance->value()} points"; // Redeem points $redemption = $loyaltyService->redeemPoints( $customerId, Points::fromInt(1000) ); echo "Redeemed: {$redemption->redemptionValue} value"; ``` ๐Ÿ—๏ธ Architecture Overview ------------------------ [](#๏ธ-architecture-overview) ``` loyalty-rewards/ โ”œโ”€โ”€ src/ โ”‚ โ”œโ”€โ”€ Core/ # Business logic core โ”‚ โ”‚ โ”œโ”€โ”€ Engine/ # Rules processing engine โ”‚ โ”‚ โ”œโ”€โ”€ Services/ # Domain services โ”‚ โ”‚ โ””โ”€โ”€ Exceptions/ # Custom exceptions โ”‚ โ”œโ”€โ”€ Domain/ # Domain models and contracts โ”‚ โ”‚ โ”œโ”€โ”€ Models/ # Core business entities โ”‚ โ”‚ โ”œโ”€โ”€ ValueObjects/ # Immutable value types โ”‚ โ”‚ โ”œโ”€โ”€ Events/ # Domain events โ”‚ โ”‚ โ””โ”€โ”€ Repositories/ # Data access contracts โ”‚ โ”œโ”€โ”€ Infrastructure/ # External concerns โ”‚ โ”‚ โ”œโ”€โ”€ Database/ # Database implementations โ”‚ โ”‚ โ””โ”€โ”€ Audit/ # Audit logging โ”‚ โ”œโ”€โ”€ Application/ # Use cases and DTOs โ”‚ โ””โ”€โ”€ Rules/ # Business rules library โ””โ”€โ”€ tests/ # Comprehensive test suite ``` ๐Ÿ’ก Real-World Examples --------------------- [](#-real-world-examples) ### E-commerce Rewards Program [](#e-commerce-rewards-program) ``` // Setup category-based earning $rulesEngine->addEarningRule(new CategoryMultiplierRule('electronics', 3.0)); $rulesEngine->addEarningRule(new CategoryMultiplierRule('books', 2.0)); $rulesEngine->addEarningRule(new CategoryMultiplierRule('groceries', 1.5)); // Tier-based bonuses $rulesEngine->addEarningRule(new TierBonusRule('gold', 1.25)); $rulesEngine->addEarningRule(new TierBonusRule('platinum', 1.5)); // Customer purchases $200 laptop (electronics + gold tier) $result = $loyaltyService->earnPoints( $goldCustomerId, Money::fromDollars(200.00, Currency::USD()), TransactionContext::earning('electronics') ); // Earns: 200 * 100 * 3.0 * 1.25 = 75,000 points ### Restaurant Chain Program // Happy hour promotions $happyHourRule = new TimeBasedRule( new DateTimeImmutable('2025-01-01 14:00:00'), new DateTimeImmutable('2025-12-31 17:00:00'), 2.0, // Double points ConversionRate::standard(), ['monday', 'tuesday', 'wednesday'] ); $rulesEngine->addEarningRule($happyHourRule); // Customer orders during happy hour $result = $loyaltyService->earnPoints( $customerId, Money::fromDollars(12.50, Currency::USD()), TransactionContext::earning('food', 'mobile_app') ); // Earns: 12.50 * 100 * 2.0 = 2,500 points ### SaaS Referral Program // Referral bonus $result = $loyaltyService->earnPoints( $referrerId, Money::zero(Currency::USD()), // No monetary transaction TransactionContext::create([ 'type' => 'referral_conversion', 'referred_customer' => 'new_customer_789', 'subscription_tier' => 'pro' ]) ); ``` ๐Ÿ”ง Configuration --------------- [](#-configuration) ### Database Setup [](#database-setup) ``` use LoyaltyRewards\Infrastructure\Database\DatabaseConnectionFactory; $pdo = DatabaseConnectionFactory::create([ 'driver' => 'pgsql', 'host' => 'localhost', 'database' => 'loyalty_rewards', 'username' => 'your_user', 'password' => 'your_password', ]); ``` ### Dependency Injection [](#dependency-injection) ``` use LoyaltyRewards\Core\Services\LoyaltyService; use LoyaltyRewards\Infrastructure\Repositories\{AccountRepository, TransactionRepository}; use LoyaltyRewards\Infrastructure\Audit\AuditLogger; $accountRepo = new AccountRepository($pdo); $transactionRepo = new TransactionRepository($pdo); $auditLogger = new AuditLogger($pdo); $loyaltyService = new LoyaltyService($accountRepo, $transactionRepo, $auditLogger, $rulesEngine); ``` ### Rules Configuration [](#rules-configuration) ``` use LoyaltyRewards\Core\Engine\RulesEngine; use LoyaltyRewards\Rules\Earning\{CategoryMultiplierRule, TierBonusRule}; $rulesEngine = new RulesEngine(); // Base earning: 1 point per cent spent $rulesEngine->addEarningRule( new CategoryMultiplierRule('default', 1.0, ConversionRate::standard()) ); // Category bonuses $rulesEngine->addEarningRule( new CategoryMultiplierRule('premium', 5.0, ConversionRate::standard()) ); // Tier bonuses stack with category multipliers $rulesEngine->addEarningRule( new TierBonusRule('vip', 2.0, ConversionRate::standard()) ); ``` ๐Ÿงช Testing --------- [](#-testing) The package includes comprehensive tests with 100% coverage: Run all tests ============= [](#run-all-tests) ``` composer test ``` Run specific test suites ======================== [](#run-specific-test-suites) ``` composer test:unit composer test:feature ``` Run with coverage report ======================== [](#run-with-coverage-report) ``` composer test:coverage ``` Performance benchmarks ====================== [](#performance-benchmarks) ``` ./vendor/bin/pest tests/Integration/Performance/ ``` ### Test Results [](#test-results) - 71 tests passing - 209 assertions - Unit tests: Value objects, domain models, rules engine - Integration tests: Database operations, service workflows - Performance tests: High-volume transactions, memory efficiency ๐Ÿ”’ Security & Fraud Detection -------------------------------- [](#-security--fraud-detection) Built-in fraud detection with configurable rules: ``` use LoyaltyRewards\Core\Services\FraudDetectionService; $fraudDetection = new FraudDetectionService(); // Automatic fraud checking on all transactions $fraudResult = $fraudDetection->analyze($account, $amount, $context); if ($fraudResult->shouldBlock()) { throw new FraudDetectedException('Transaction blocked'); } ``` Detection Methods: - Velocity checking (transaction frequency) - Amount anomaly detection - Pattern recognition - Account behavior analysis ๐Ÿ“ˆ Performance ------------- [](#-performance) Benchmarked Performance: - Single Transaction: < 100ms average - Bulk Operations: 1000 transactions in < 10 seconds - Memory Usage: < 50MB for 1000 transactions - Database Queries: Optimized with proper indexing Scalability Features: - Connection pooling support - Caching layer integration - Async queue processing - Horizontal scaling ready ๐Ÿข Enterprise Features --------------------- [](#-enterprise-features) ### Audit & Compliance [](#audit--compliance) - Complete transaction audit trails - Regulatory compliance reporting - Data retention policies - Encrypted sensitive data storage ### Multi-Currency Support [](#multi-currency-support) - 7+ supported currencies (USD, EUR, GBP, NGN, etc.) - Automatic currency conversion - Regional formatting - Exchange rate integration ready ### Event-Driven Architecture [](#event-driven-architecture) - Domain events for all state changes - Easy integration with external systems - Webhook support ready - Real-time notifications ๐Ÿ“š Documentation --------------- [](#-documentation) - [API Reference (API.md)](API.md) โ€” Complete method documentation - [Architecture Guide (ARCHITECTURE.md)](ARCHITECTURE.md) โ€” Technical design decisions - [Examples (EXAMPLES.md)](EXAMPLES.md) โ€” 10+ real-world implementations - [Configuration (CONFIGURATION.md)](CONFIGURATION.md) โ€” Setup and customization options - [Laravel Adapter](packages/loyalty-rewards-laravel) โ€” Service provider, config, and migrations ๐Ÿšข Release Guide --------------- [](#-release-guide) To cut a release: ``` # bump version via git tag (Composer reads tags) git tag -a v0.1.0 -m "v0.1.0" git push origin v0.1.0 # (optional) update Packagist after pushing tags # core: https://packagist.org/packages/mbsoft31/loyalty-rewards # adapter: https://packagist.org/packages/mbsoft31/loyalty-rewards-laravel ``` CI runs unit + integration tests and a DB matrix (Postgres 16, MySQL 8). Coverage gate enforces โ‰ฅ80% on PHP 8.2. ๐Ÿค Contributing -------------- [](#-contributing) We welcome contributions! Please see CONTRIBUTING.md for guidelines. ### Development Setup [](#development-setup) ``` git clone https://github.com/mbsoft31/loyalty-rewards.git cd loyalty-rewards composer install composer test ``` ๐Ÿ“ License --------- [](#-license) This project is licensed under the MIT License โ€” see the LICENSE file for details. ๐Ÿ”— Links ------- [](#-links) - GitHub Repository: - Issues: - Discussions: - Releases: Built with โค๏ธ by mbsoft31 โ€” Empowering businesses with flexible, scalable loyalty solutions. ### Health Score 34 โ€” LowBetter than 77% of packages Maintenance65 Regular maintenance activity Popularity6 Limited adoption so far Community6 Small or concentrated contributor base Maturity49 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits โ€” single point of failure How is this calculated?**Maintenance (25%)** โ€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** โ€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** โ€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** โ€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~12 days Total 2 Last Release 214d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/288f14daea877ea6b5b49d25bf1647f75eab2870b3e143e2a35b17a0666f1bd8?d=identicon)[mbsoft](/maintainers/mbsoft) --- Top Contributors [![mbsoft31](https://avatars.githubusercontent.com/u/14237661?v=4)](https://github.com/mbsoft31 "mbsoft31 (18 commits)") ### Code Quality TestsPest ### Embed Badge ![Health badge](/badges/mbsoft31-loyalty-rewards/health.svg) ``` [![Health](https://phpackages.com/badges/mbsoft31-loyalty-rewards/health.svg)](https://phpackages.com/packages/mbsoft31-loyalty-rewards) ``` ### Alternatives [grumpydictator/firefly-iii Firefly III: a personal finances manager. 22.8k69.3k](/packages/grumpydictator-firefly-iii)[phpro/soap-client A general purpose SoapClient library 8885.6M46](/packages/phpro-soap-client)[shopware/platform The Shopware e-commerce core 3.3k1.5M3](/packages/shopware-platform)[ecotone/ecotone Supporting you in building DDD, CQRS, Event Sourcing applications with ease. 558549.8k17](/packages/ecotone-ecotone)[cognesy/instructor-php The complete AI toolkit for PHP: unified LLM API, structured outputs, agents, and coding agent control 310107.9k1](/packages/cognesy-instructor-php)[shopware/core Shopware platform is the core for all Shopware ecommerce products. 595.2M386](/packages/shopware-core) PHPackages ยฉ 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)