🚀 Payment Gateway Package

یک پکیج حرفه‌ای و Production-Ready برای مدیریت درگاه‌های پرداخت با معماری Hexagonal

---

📋 فهرست مطالب

• ویژگی‌های برجسته
• نصب
• شروع سریع
• معماری
• استفاده
• مستندات
• تست
• مشارکت

---

✨ ویژگی‌های برجسته

🏗️ معماری و طراحی

• ✅ Hexagonal Architecture - معماری تمیز و قابل نگهداری
• ✅ SOLID Principles - تمام 5 اصل پیاده‌سازی شده
• ✅ Domain-Driven Design - طراحی مبتنی بر دامنه
• ✅ Clean Code - کد تمیز و خوانا
• ✅ Design Patterns - 7 الگوی طراحی

🎨 Design Patterns پیاده‌سازی شده

Pattern	استفاده	مزیت
Strategy	درگاه‌های مختلف	انعطاف‌پذیری
Factory	ساخت درگاه‌ها	مدیریت ساخت
Adapter	HTTP Clients	جداسازی
Decorator	Rate Limiting	افزودن قابلیت
Repository	دسترسی به داده	انتزاع داده
Observer	Events	واکنش به رویدادها
Value Object	داده‌های دامنه	Type Safety

🔒 امنیت

• 🛡️ عدم افشای خطاهای داخلی
• ✅ Validation کامل ورودی‌ها
• 🔐 Idempotency Key برای جلوگیری از تکرار
• 🚦 Rate Limiting برای محافظت از API
• 🔒 Immutable Value Objects

⚡ قابلیت‌های پیشرفته

• 🔄 Retry Mechanism - تلاش مجدد خودکار
• 🚦 Rate Limiting - محدودیت درخواست
• 📢 Event System - سیستم رویدادها
• 💎 Value Objects - Type Safety
• 📦 DTOs - انتقال داده ساختاریافته
• 📝 Logging - ثبت لاگ جامع

---

📦 نصب

نیازمندی‌ها

• PHP 8.1 یا بالاتر
• Laravel 10.x یا 11.x
• Composer

نصب از طریق Composer

composer require ali/payment-gateway

---

🚀 شروع سریع

1️⃣ انتشار فایل‌ها

# انتشار config
php artisan vendor:publish --tag=payment-gateway-config

# انتشار migrations
php artisan vendor:publish --tag=payment-gateway-migrations

# اجرای migrations
php artisan migrate

2️⃣ تنظیم محیط

فایل .env خود را ویرایش کنید:

MELLAT_WSDL_URL=https://bpm.shaparak.ir/pgwchannel/services/pgw?wsdl
MELLAT_PAYMENT_URL=https://bpm.shaparak.ir/pgwchannel/startpay.mellat

3️⃣ ثبت درگاه

use Ali\PaymentGateway\Models\Gateway;

Gateway::create([
    'name' => 'بانک ملت',
    'driver' => 'mellat',
    'credentials' => json_encode([
        'terminal_id' => 'YOUR_TERMINAL_ID',
        'username' => 'YOUR_USERNAME',
        'password' => 'YOUR_PASSWORD',
    ]),
    'is_active' => true,
    'priority' => 1,
]);

4️⃣ استفاده

use Ali\PaymentGateway\Services\GatewayManager;

$manager = app(GatewayManager::class);

// شروع پرداخت
$result = $manager->initiatePayment([
    'gateway_id' => 1,
    'amount' => 100000, // ریال
    'callback_url' => route('payment.callback'),
]);

return redirect($result['redirect_url']);

📖 راهنمای کامل شروع سریع →

---

🏗️ معماری

این پکیج بر اساس Hexagonal Architecture طراحی شده است:

┌─────────────────────────────────────────────────────────┐
│                  Presentation Layer                      │
│              (Controllers, Routes, Views)                │
└─────────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────┐
│                  Application Layer                       │
│            (GatewayManager, Use Cases)                   │
└─────────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────┐
│                    Domain Layer                          │
│  (Entities, Value Objects, Domain Services, Interfaces)  │
└─────────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────┐
│                Infrastructure Layer                      │
│              (Adapters, HTTP Clients)                    │
└─────────────────────────────────────────────────────────┘

جریان داده

User Request → Controller → Manager → Resolver → Gateway → HTTP Client → Bank API

📖 مستندات کامل معماری →

---

💻 استفاده

شروع پرداخت

use Ali\PaymentGateway\Services\GatewayManager;

class PaymentController extends Controller
{
    public function start(Request $request, GatewayManager $manager)
    {
        try {
            $result = $manager->initiatePayment([
                'gateway_id' => $request->gateway_id,
                'user_id' => auth()->id(),
                'amount' => $request->amount,
                'callback_url' => route('payment.callback'),
                'metadata' => [
                    'order_id' => $request->order_id,
                    'description' => 'خرید محصول',
                ],
            ]);

            return redirect($result['redirect_url']);
        } catch (\Exception $e) {
            return back()->with('error', 'خطا در شروع پرداخت');
        }
    }
}

مدیریت Callback

public function callback(Request $request, GatewayManager $manager)
{
    try {
        $result = $manager->handleCallback(
            $request->input('track_id'),
            $request->all()
        );

        if ($result['status'] === 'success') {
            // پرداخت موفق - انجام عملیات
            $transaction = $result['transaction'];
            
            return redirect()->route('payment.success', [
                'reference' => $transaction->reference_number
            ]);
        }

        return redirect()->route('payment.failed');
    } catch (\Exception $e) {
        return redirect()->route('payment.failed');
    }
}

استفاده از Value Objects

use Ali\PaymentGateway\ValueObjects\Money;

// ایجاد مبلغ
$money = Money::fromToman(10000);
echo $money->format(); // "10,000 تومان"

// عملیات ریاضی
$total = $money->add(Money::fromToman(5000));
$discount = $money->multiply(0.1);

// مقایسه
if ($money->greaterThan(Money::fromToman(5000))) {
    // ...
}

استفاده از Events

use Ali\PaymentGateway\Events\PaymentVerified;
use Illuminate\Support\Facades\Event;

Event::listen(PaymentVerified::class, function ($event) {
    // ارسال ایمیل
    Mail::to($event->transaction->user)
        ->send(new PaymentSuccessEmail($event->transaction));
    
    // فعال‌سازی سفارش
    Order::find($event->transaction->order_id)->activate();
});

📖 راهنمای جامع استفاده →

---

📚 مستندات

سند	توضیح
README.md	معرفی و نصب
QUICK_START.md	شروع سریع در 5 دقیقه
USAGE.md	راهنمای جامع استفاده
ARCHITECTURE.md	معماری دقیق پروژه
PROJECT_STRUCTURE.md	ساختار فایل‌ها
IMPROVEMENTS_SUMMARY.md	خلاصه بهبودها
CONTRIBUTING.md	راهنمای مشارکت
CHANGELOG.md	تاریخچه تغییرات

---

🧪 تست

اجرای تمام تست‌ها

composer test

اجرای تست‌های Unit

composer test -- --testsuite=Unit

اجرای تست‌های Feature

composer test -- --testsuite=Feature

تولید گزارش Coverage

composer test -- --coverage-html coverage

استفاده از Makefile

make test          # اجرای تست‌ها
make test-unit     # تست‌های Unit
make test-feature  # تست‌های Feature
make coverage      # گزارش Coverage

---

🎯 افزودن درگاه جدید

1. ایجاد کلاس Gateway

namespace App\Gateways;

use Ali\PaymentGateway\Contracts\PaymentGatewayInterface;
use Ali\PaymentGateway\Models\Transaction;
use Ali\PaymentGateway\ValueObjects\VerificationResult;

class SamanGateway implements PaymentGatewayInterface
{
    public function initiate(Transaction $transaction): string
    {
        // پیاده‌سازی منطق شروع پرداخت
    }

    public function verify(Transaction $transaction, array $params): VerificationResult
    {
        // پیاده‌سازی منطق تایید پرداخت
    }

    public function getName(): string
    {
        return 'Saman';
    }

    public function isAvailable(): bool
    {
        return true;
    }
}

2. ثبت در Config

// config/gateways.php
'drivers' => [
    'mellat' => MellatGateway::class,
    'saman' => SamanGateway::class, // درگاه جدید
],

3. ثبت در دیتابیس

Gateway::create([
    'name' => 'بانک سامان',
    'driver' => 'saman',
    'credentials' => json_encode([...]),
    'is_active' => true,
]);

---

📊 آمار پروژه

مورد	تعداد
کل فایل‌ها	48+
خطوط کد	4,500+
کلاس‌ها	30+
تست‌ها	6
مستندات	9 فایل

---

🤝 مشارکت

مشارکت شما استقبال می‌شود! لطفاً راهنمای مشارکت را مطالعه کنید.

مراحل مشارکت

1. Fork کنید
2. Branch جدید بسازید (git checkout -b feature/amazing)
3. تغییرات را Commit کنید (git commit -m 'Add feature')
4. Push کنید (git push origin feature/amazing)
5. Pull Request ایجاد کنید

---

📝 مجوز

این پروژه تحت مجوز MIT منتشر شده است.

---

🙏 تشکر

از تمام کسانی که در این پروژه مشارکت کرده‌اند متشکریم!

---

📞 پشتیبانی

• GitHub Issues: github.com/ali/payment-gateway/issues
• Email: ali@example.com
• Documentation: github.com/ali/payment-gateway/wiki

---

ساخته شده با ❤️ در ایران

⭐ اگر این پروژه برای شما مفید بود، یک ستاره بدهید!

مستندات • معماری • مشارکت • تغییرات