README

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

🎁 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.1+ type declarations with strict type checking

🚀 Quick Start

Installation

composer require mbsoft31/loyalty-rewards

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

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
│   │   ├── Cache/            # Caching layer
│   │   └── Audit/            # Audit logging
│   ├── Application/          # Use cases and DTOs
│   └── Rules/                # Business rules library
└── tests/                    # Comprehensive test suite

💡 Real-World Examples

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

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

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

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

The package includes comprehensive tests with 100% coverage:

Run all tests

composer test

Run specific test suites

composer test:unit
composer test:feature

Run with coverage report

composer test:coverage

Performance benchmarks

./vendor/bin/pest tests/Integration/Performance/

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

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

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

Audit & Compliance

Complete transaction audit trails
Regulatory compliance reporting
Data retention policies
Encrypted sensitive data storage

Multi-Currency Support

7+ supported currencies (USD, EUR, GBP, NGN, etc.)
Automatic currency conversion
Regional formatting
Exchange rate integration ready

Event-Driven Architecture

Domain events for all state changes
Easy integration with external systems
Webhook support ready
Real-time notifications

📚 Documentation

API Reference (API.md) — Complete method documentation
Architecture Guide (ARCHITECTURE.md) — Technical design decisions
Examples (EXAMPLES.md) — 10+ real-world implementations
Configuration (CONFIGURATION.md) — Setup and customization options

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

git clone https://github.com/mbsoft31/loyalty-rewards.git
cd loyalty-rewards
composer install
composer test

📝 License

This project is licensed under the MIT License — see the LICENSE file for details.

🔗 Links

GitHub Repository: https://github.com/mbsoft31/loyalty-rewards
Issues: https://github.com/mbsoft31/loyalty-rewards/issues
Discussions: https://github.com/mbsoft31/loyalty-rewards/discussions
Releases: https://github.com/mbsoft31/loyalty-rewards/releases

Built with ❤️ by mbsoft31 — Empowering businesses with flexible, scalable loyalty solutions.

mbsoft31 / loyalty-rewards

Maintainers

Details