ترقية وتخفيض الاشتراكات هي ميزة شائعة في التطبيقات التي تقدم خدمات قائمة على الاشتراك. في هذا الدليل، سنتعلم كيفية تنفيذ هذه الوظيفة في تطبيق Laravel باستخدام Stripe PHP SDK.

يفترض هذا الدليل أن لديك فهماً أساسياً لـ Laravel ولديك حساب Stripe معد. إذا كنت جديداً على Stripe، فكر في مراجعة وثائق Stripe الرسمية قبل المتابعة.

المتطلبات الأساسية

Laravel مثبت على نظامك.
حساب Stripe مع مفاتيح API للاختبار.
حزمة stripe-php مثبتة عبر Composer.

إعداد Stripe في Laravel

أولاً، ثبّت مكتبة Stripe PHP باستخدام Composer:

composer require stripe/stripe-php

بعد ذلك، هيّئ مفاتيح Stripe API الخاصة بك. يمكنك تعيينها في ملف .env:

STRIPE_KEY=your_stripe_publishable_key
STRIPE_SECRET=your_stripe_secret_key

ثم أضفها إلى ملف config/services.php:

'stripe' => [
    'key' => env('STRIPE_KEY'),
    'secret' => env('STRIPE_SECRET'),
],

استرداد الاشتراك والعناصر

لترقية أو تخفيض اشتراك، تحتاج أولاً إلى استرداد الاشتراك وعناصره:

\Stripe\Stripe::setApiKey(config('services.stripe.secret'));
 
$subscriptionId = 'sub_XXXXXXXXXXXX';
 
$subscription = \Stripe\Subscription::retrieve($subscriptionId);
 
$subscriptionItemId = $subscription->items->data[0]->id;

ترقية أو تخفيض الاشتراك

يمكنك تحديث الاشتراك عن طريق تغيير السعر المرتبط بعنصر الاشتراك. تأكد من تحديد id عنصر الاشتراك و price_id الجديد:

$newPriceId = 'price_YYYYYYYYYYYYYY';
 
$updatedSubscription = \Stripe\Subscription::update($subscriptionId, [
    'items' => [
        [
            'id' => $subscriptionItemId,
            'price' => $newPriceId,
        ],
    ],
]);

هذا يستبدل السعر الحالي بالسعر الجديد. إذا لم تحدد id عنصر الاشتراك، سيضيف Stripe السعر الجديد كعنصر إضافي، مما يؤدي إلى تفعيل كلا السعرين.

التعامل مع الكميات

إذا كان اشتراكك يستخدم كميات، تحتاج إلى الحفاظ على الكمية الموجودة عند التحديث:

$quantity = $subscription->items->data[0]->quantity;
 
$updatedSubscription = \Stripe\Subscription::update($subscriptionId, [
    'items' => [
        [
            'id' => $subscriptionItemId,
            'price' => $newPriceId,
            'quantity' => $quantity,
        ],
    ],
]);

التناسب والفوترة

بشكل افتراضي، يطبق Stripe التناسبات عندما تغير اشتراك العميل. إذا كنت تريد تعطيل التناسبات، يمكنك تعيين معامل proration_behavior إلى none:

$updatedSubscription = \Stripe\Subscription::update($subscriptionId, [
    'items' => [
        [
            'id' => $subscriptionItemId,
            'price' => $newPriceId,
        ],
    ],
    'proration_behavior' => 'none',
]);

بدلاً من ذلك، لمعاينة الفاتورة القادمة، يمكنك استخدام:

$upcomingInvoice = \Stripe\Invoice::upcoming([
    'customer' => $subscription->customer,
    'subscription' => $subscriptionId,
    'subscription_items' => [
        [
            'id' => $subscriptionItemId,
            'price' => $newPriceId,
        ],
    ],
]);

الخلاصة

في هذا الدليل، تعلمنا كيفية ترقية وتخفيض الاشتراكات في تطبيق Laravel باستخدام Stripe PHP SDK. تذكر دائماً اختبار تغييراتك في بيئة اختبار قبل النشر في الإنتاج.

لمزيد من المعلومات، راجع وثائق اشتراكات Stripe.