README

A flexible and extensible PHP promotion rule engine for shopping cart scenarios — supports discounts, tiered offers, member pricing, and more, implemented elegantly and maintainably.

📦 Installation

Install via Composer:

composer require mcjy/rule-engine

🚀 Usage

use Mcjy\RuleEngine\Models\Cart;
use Mcjy\RuleEngine\Models\User;
use Mcjy\RuleEngine\PromotionEngine;
use Mcjy\RuleEngine\Rules;

// Create user (VIP)
$user = new User(vip: true);

// Create a shopping cart
$cart = new Cart();
$cart->addItem('Product A', 50, 1, ['snacks']);
$cart->addItem('Product B', 60, 1, ['clothes']);
$cart->addItem('Product C', 40, 1, ['clothes']);
$cart->addItem('Product D', 100, 1, ['promo']);
$cart->addItem('Product E', 30, 3, ['snacks']);
$cart->addItem('Product F', 200, 1, ['electronics']);

// Initialize the promotion engine
$engine = new PromotionEngine();

// Calculation modes:
//
// independent:
//   Each rule calculates the discount separately based on the original product price.
//   Discounts are aggregated at the end; intermediate results do not affect other rules.
//
// sequential:
//   Each rule continues calculating based on the previously adjusted price (discount-on-discount).
//   When a rule involves multiple products, the discount is distributed proportionally.
//
// lock:
//   Each product can only be discounted by one rule. Subsequent rules skip already-locked items.
//   Suitable for scenarios where only one promotion can apply per item (flash sales, exclusive coupons, etc.).
$engine->setMode('independent');

// Register rules
$engine->addRule(new Rules\FullDiscountRule(200, 0.9));           // 10% off over ¥200
$engine->addRule(new Rules\FullQuantityReductionRule(3, 20));     // ¥20 off when buying 3+ items
$engine->addRule(new Rules\NthItemDiscountRule(3, 0.5));          // 3rd item 50% off
$engine->addRule(new Rules\VipDiscountRule(0.95));                // VIP 5% off
$engine->addRule(new Rules\FullQuantityDiscountRule(5, 0.9));     // 10% off when buying 5+ items
$engine->addRule(new Rules\FullReductionRule(100, 20));           // ¥20 off over ¥100
$engine->addRule(new Rules\VipReductionRule(5));                  // VIP ¥5 off

// Calculate
$result = $engine->calculate($cart, $user);

// Print result
echo "\n=== Result ===\n";
echo "Original: ¥{$result['original']}\n";
echo "Discount: -¥{$result['discount']}\n";
echo "Final:    ¥{$result['final']}\n";
echo "Details:\n";
foreach ($result['details'] as $detail) {
    echo "- {$detail}\n";
}

🛠️ Built-in Rule Types

🧩 Extending with Custom Rules

Implement PromotionRuleInterface to add your own rule:

use Mcjy\RuleEngine\Contracts\PromotionRuleInterface;
use Mcjy\RuleEngine\Models\Cart;
use Mcjy\RuleEngine\Models\User;
use Mcjy\RuleEngine\PromotionResult;

class MyCustomRule implements PromotionRuleInterface
{
    public function apply(Cart $cart, User $user, array $eligibleIndexes = []): PromotionResult
    {
        // Your discount logic here
    }

    public function getApplicableItems(Cart $cart): array { /* ... */ }
    public function getPriority(): int { return 1; }
    public function getApplicableTags(): array { return []; }
}

📄 License

MIT