صندوقدار لاراول

• معرفی
• پیکربندی
• اشتراک در یک طرح
• شارژ تک
• بدون کارت در جلو
• تعویض اشتراک ها
• مقدار اشتراک
• مالیات اشتراک
• لغو اشتراک
• از سرگیری یک اشتراک
• بررسی وضعیت اشتراک
• مدیریت اشتراک های ناموفق
• رسیدگی به سایر قلاب های راه راه
• فاکتورها

معرفی

Laravel Cashier یک رابط رسا و روان برای خدمات صورتحساب اشتراک Stripe فراهم می کند. تقریباً تمام کدهای صورت‌حساب اشتراک دیگ بخار را که از نوشتن آن می‌ترسید مدیریت می‌کند. علاوه بر مدیریت اشتراک اولیه، Cashier می‌تواند کوپن‌ها، تعویض اشتراک، "مقدار" اشتراک، دوره‌های مهلت لغو، و حتی فایل‌های PDF فاکتور تولید کند.

پیکربندی

composer

ابتدا بسته Cashier را به composer.json فایل خود اضافه کنید:

"laravel/cashier": "~5.0" (For Stripe SDK ~2.0, and Stripe APIs on 2015-02-18 version and later)
"laravel/cashier": "~4.0" (For Stripe APIs on 2015-02-18 version and later)
"laravel/cashier": "~3.0" (For Stripe APIs up to and including 2015-02-16 version)

ارائه دهنده خدمات

سپس در فایل پیکربندی Laravel\Cashier\CashierServiceProvider خود ثبت کنید. app

مهاجرت

قبل از استفاده از Cashier، باید چندین ستون به پایگاه داده شما اضافه کنیم. نگران نباشید، می توانید از cashier:table دستور Artisan برای ایجاد یک مهاجرت برای اضافه کردن ستون لازم استفاده کنید. به عنوان مثال، برای افزودن ستون به جدول کاربران از استفاده کنید php artisan cashier:table users . پس از ایجاد مهاجرت، به سادگی migrate دستور را اجرا کنید.

راه اندازی مدل

سپس، Billable صفت و جهش‌دهنده‌های تاریخ مناسب را به تعریف مدل خود اضافه کنید:

use Laravel\Cashier\Billable;
use Laravel\Cashier\Contracts\Billable as BillableContract;
 
class User extends Model implements BillableContract {
 
    use Billable;
 
    protected $dates = ['trial_ends_at', 'subscription_ends_at'];
 
}

کلید راه راه

در نهایت، کلید Stripe خود را در services.php فایل پیکربندی خود تنظیم کنید:

'stripe' => [
    'model'  => 'User',
    'secret' => env('STRIPE_API_SECRET'),
],

یا می توانید آن را در یکی از فایل های بوت استرپ یا ارائه دهندگان خدمات خود ذخیره کنید، مانند AppServiceProvider :

User::setStripeKey('stripe-key');

اشتراک در یک طرح

هنگامی که یک نمونه مدل دارید، می توانید به راحتی آن کاربر را در یک طرح Stripe معین مشترک کنید:

$user = User::find(1);
 
$user->subscription('monthly')->create($creditCardToken);

اگر می خواهید هنگام ایجاد اشتراک کوپن اعمال کنید، می توانید از withCoupon روش زیر استفاده کنید:

$user->subscription('monthly')
     ->withCoupon('code')
     ->create($creditCardToken);

این subscription روش به طور خودکار اشتراک Stripe را ایجاد می کند و همچنین پایگاه داده شما را با شناسه مشتری Stripe و سایر اطلاعات صورتحساب مرتبط به روز می کند. اگر برنامه شما آزمایشی در Stripe پیکربندی شده باشد، تاریخ پایان آزمایشی نیز به طور خودکار در سابقه کاربر تنظیم می‌شود.

اگر برنامه شما دارای دوره آزمایشی است که در Stripe پیکربندی نشده است ، باید پس از اشتراک، تاریخ پایان آزمایشی را به صورت دستی تنظیم کنید:

$user->trial_ends_at = Carbon::now()->addDays(14);
 
$user->save();

تعیین جزئیات کاربر اضافی

اگر می خواهید جزئیات بیشتری از مشتری را مشخص کنید، می توانید این کار را با ارسال آنها به عنوان آرگومان دوم در create متد انجام دهید:

$user->subscription('monthly')->create($creditCardToken, [
    'email' => $email, 'description' => 'Our First Customer'
]);

برای کسب اطلاعات بیشتر در مورد فیلدهای اضافی پشتیبانی شده توسط Stripe، مستندات Stripe در مورد ایجاد مشتری را بررسی کنید .

شارژ تک

اگر می‌خواهید برای کارت اعتباری مشترک مشتری یک هزینه «یکباره» اعمال کنید، می‌توانید از charge روش زیر استفاده کنید:

$user->charge(100);

این charge روش مبلغی را که می‌خواهید با کمترین مخرج ارز شارژ کنید، می‌پذیرد . بنابراین، برای مثال، مثال بالا 100 سنت یا 1.00 دلار از کارت اعتباری کاربر دریافت می کند.

این charge روش یک آرایه را به عنوان آرگومان دوم خود می پذیرد و به شما امکان می دهد هر گزینه ای را که می خواهید به ایجاد شارژ Stripe زیربنایی منتقل کنید:

$user->charge(100, [
    'source' => $token,
    'receipt_email' => $user->email,
]);

اگر شارژ نشد، روش charge برمی‌گردد . false این معمولاً نشان می دهد که اتهام رد شده است:

if ( ! $user->charge(100))
{
    // The charge was denied...
}

اگر شارژ با موفقیت انجام شود، پاسخ کامل Stripe از روش برگردانده می شود.

بدون کارت در جلو

اگر برنامه شما یک نسخه آزمایشی رایگان و بدون کارت اعتباری از قبل ارائه می دهد، cardUpFront ویژگی را در مدل خود به صورت زیر تنظیم کنید false :

protected $cardUpFront = false;

هنگام ایجاد حساب، مطمئن شوید که تاریخ پایان آزمایشی را روی مدل تنظیم کنید:

$user->trial_ends_at = Carbon::now()->addDays(14);
 
$user->save();

تعویض اشتراک ها

برای تعویض کاربر با یک اشتراک جدید، از swap روش زیر استفاده کنید:

$user->subscription('premium')->swap();

اگر کاربر در حال آزمایش باشد، آزمایشی به صورت عادی حفظ خواهد شد. همچنین، اگر "کمیتی" برای اشتراک وجود داشته باشد، آن مقدار نیز حفظ خواهد شد.

مقدار اشتراک

گاهی اوقات اشتراک ها تحت تأثیر "کمیت" قرار می گیرند. به عنوان مثال، برنامه شما ممکن است 10 دلار در ماه برای هر کاربر در یک حساب دریافت کند. برای افزایش یا کاهش آسان تعداد اشتراک خود، از روش های increment و استفاده کنید decrement :

$user = User::find(1);
 
$user->subscription()->increment();
 
// Add five to the subscription's current quantity...
$user->subscription()->increment(5);
 
$user->subscription()->decrement();
 
// Subtract five to the subscription's current quantity...
$user->subscription()->decrement(5);

مالیات اشتراک

با Cashier، نادیده گرفتن ارزش ارسال شده به Stripe آسان است tax_percent . برای مشخص کردن درصد مالیاتی که کاربر برای اشتراک می پردازد، getTaxPercent روش را در مدل خود پیاده کنید و یک مقدار عددی بین 0 تا 100 را با حداکثر 2 رقم اعشار برگردانید.

public function getTaxPercent()
{
    return 20;
}

این به شما امکان می دهد نرخ مالیات را بر اساس مدل به مدل اعمال کنید، که ممکن است برای پایگاه کاربری که چندین کشور را در بر می گیرد مفید باشد.

لغو اشتراک

لغو اشتراک یک پیاده روی در پارک است:

$user->subscription()->cancel();

هنگامی که یک اشتراک لغو می شود، صندوقدار به طور خودکار subscription_ends_at ستون را در پایگاه داده شما تنظیم می کند. از این ستون برای دانستن زمان subscribed شروع بازگشت متد استفاده می شود false . به عنوان مثال، اگر مشتری در تاریخ 1 مارس اشتراک خود را لغو کند، اما قرار نبود اشتراک تا 5 مارس پایان یابد، این روش تا 5 مارس subscribed ادامه خواهد داشت . true

از سرگیری یک اشتراک

اگر کاربری اشتراک خود را لغو کرده است و می‌خواهید آن را از سر بگیرید، از resume روش زیر استفاده کنید:

$user->subscription('monthly')->resume($creditCardToken);

اگر کاربر اشتراکی را لغو کند و سپس آن اشتراک را قبل از انقضای کامل اشتراک از سر بگیرد، بلافاصله صورتحساب دریافت نخواهد شد. اشتراک آنها به سادگی دوباره فعال می شود و صورتحساب آنها در چرخه صورتحساب اصلی محاسبه می شود.

بررسی وضعیت اشتراک

برای تأیید اینکه یک کاربر در برنامه شما مشترک شده است، از subscribed روش زیر استفاده کنید:

if ($user->subscribed())
{
    //
}

این subscribed روش کاندیدای عالی برای میان افزار مسیر است :

public function handle($request, Closure $next)
{
    if ($request->user() && ! $request->user()->subscribed())
    {
        return redirect('billing');
    }
 
    return $next($request);
}

همچنین می‌توانید تعیین کنید که آیا کاربر هنوز در دوره آزمایشی خود است (در صورت وجود) با استفاده از onTrial روش:

if ($user->onTrial())
{
    //
}

برای تعیین اینکه آیا کاربر زمانی مشترک فعال بوده است، اما اشتراک خود را لغو کرده است، می توانید از cancelled روش زیر استفاده کنید:

if ($user->cancelled())
{
    //
}

همچنین می‌توانید تعیین کنید که آیا یک کاربر اشتراک خود را لغو کرده است یا خیر، اما هنوز در «دوره مهلت» خود است تا زمانی که اشتراک به طور کامل منقضی شود. به عنوان مثال، اگر کاربر اشتراکی را در تاریخ 5 مارس لغو کند که قرار بود در 10 مارس به پایان برسد، کاربر تا 10 مارس در "مهلت مهلت" خود است. توجه داشته باشید که subscribed روش همچنان true در این مدت باز می گردد.

if ($user->onGracePeriod())
{
    //
}

این everSubscribed روش ممکن است برای تعیین اینکه آیا کاربر تا به حال در طرحی در برنامه شما مشترک شده است یا خیر استفاده شود:

if ($user->everSubscribed())
{
    //
}

این onPlan روش ممکن است برای تعیین اینکه آیا کاربر در یک طرح معین بر اساس شناسه آن مشترک شده است یا خیر استفاده شود:

if ($user->onPlan('monthly'))
{
    //
}

مدیریت اشتراک های ناموفق

اگر اعتبار کارت اعتباری مشتری منقضی شود چه می شود؟ جای نگرانی نیست - Cashier شامل یک کنترلر Webhook است که به راحتی می تواند اشتراک مشتری را برای شما لغو کند. فقط یک مسیر را به سمت کنترلر مشخص کنید:

Route::post('stripe/webhook', 'Laravel\Cashier\WebhookController@handleWebhook');

خودشه! پرداخت های ناموفق توسط کنترل کننده ضبط و رسیدگی می شود. هنگامی که Stripe تشخیص دهد که اشتراک ناموفق بوده است، کنترل کننده اشتراک مشتری را لغو می کند (معمولاً پس از سه بار تلاش برای پرداخت ناموفق). URI stripe/webhook در این مثال فقط برای مثال است. شما باید URI را در تنظیمات Stripe خود پیکربندی کنید.

رسیدگی به سایر قلاب های راه راه

اگر رویدادهای Stripe webhook دیگری دارید که می خواهید مدیریت کنید، به سادگی کنترلر Webhook را گسترش دهید. نام روش‌های شما باید مطابق با قرارداد مورد انتظار Cashier باشد، به‌ویژه، متدها باید با پیشوند handle و نام وب‌قلاب Stripe که می‌خواهید مدیریت کنید، مطابقت داشته باشد. به عنوان مثال، اگر می خواهید invoice.payment_succeeded وب هوک را مدیریت کنید، باید یک handleInvoicePaymentSucceeded روش به کنترلر اضافه کنید.

class WebhookController extends Laravel\Cashier\WebhookController {
 
    public function handleInvoicePaymentSucceeded($payload)
    {
        // Handle The Event
    }
 
}

توجه: کنترلر Webhook علاوه بر به روز رسانی اطلاعات اشتراک در پایگاه داده شما، اشتراک را از طریق Stripe API نیز لغو می کند.

فاکتورها

با استفاده از روش زیر می توانید به راحتی آرایه ای از فاکتورهای یک کاربر را بازیابی کنید invoices :

$invoices = $user->invoices();

هنگام فهرست کردن فاکتورها برای مشتری، می توانید از این روش های کمکی برای نمایش اطلاعات فاکتور مربوطه استفاده کنید:

{{ $invoice->id }}
 
{{ $invoice->dateString() }}
 
{{ $invoice->dollars() }}

از downloadInvoice روشی برای تولید فایل PDF فاکتور استفاده کنید. بله، واقعاً به همین راحتی است:

return $user->downloadInvoice($invoice->id, [
    'vendor'  => 'Your Company',
    'product' => 'Your Product',
]);