Может войдёшь?
Черновики Написать статью Профиль

Laravel Cashier

перевод документация 5.х

  1. 1. Введение
    1. 1.1. Настройка
  2. 2. Подписки
    1. 2.1. Создание подписок
    2. 2.2. Проверка статуса подписки
    3. 2.3. Смена тарифа
    4. 2.4. Количество подписки
    5. 2.5. Налог на подписку
    6. 2.6. Отмена подписки
    7. 2.7. Возобновление подписки
  3. 3. Обработка веб-хуков Stripe
    1. 3.1. Неудавшиеся подписки
    2. 3.2. Другие веб-хуки
  4. 4. Одиночные платежи
    1. 4.1. Без предоплаты
  5. 5. Счета
Этот перевод актуален для англоязычной документации на (ветка 5.1) и (ветка 5.0). Опечатка? Выдели и нажми Ctrl+Enter.

Введение

Laravel Cashier (кассир — прим. пер.) обеспечивает выразительный и гибкий интерфейс для сервисов биллинговых подписок Stripe. Он сам создаст практически весь шаблонный код биллинговых подписок, который вы боитесь писать. В дополнение к основному управлению подписками Cashier может работать с купонами, заменой подписок, «величинами» подписок, отменой льготного периода, и даже генерировать PDF-файлы счетов.

Настройка

Composer

Сначала добавьте пакет Cashier в свой файл composer.json и выполните команду shcomposer update:

  • "laravel/cashier": "~5.0" — для Stripe SDK ~2.0 и версии Stripe APIs от 2015-02-18 и выше
  • "laravel/cashier": "~4.0" — для версии Stripe APIs от 2015-02-18 и выше
  • "laravel/cashier": "~3.0" — для версии Stripe APIs от 2015-02-16 включительно и выше

Поставщик услуг

Затем зарегистрируйте сервис-провайдер Laravel\Cashier\CashierServiceProvider в вашем файле настроек app.

Миграция

Перед тем как начать использовать Cashier, надо добавить несколько столбцов в БД. Не волнуйтесь, вы можете использовать Artisan-команду shcashier:table для создания миграции, которая добавит необходимые столбцы. Например, чтобы добавить столбец в таблицу пользователей, используйте shphp artisan cashier:table users.

После создания миграции просто выполните команду shmigrate.

Установка модели

Далее добавьте типаж Billable и соответствующие преобразователи даты в определение вашей модели:

PHP
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-ключ

Наконец, внесите ваш Stripe-ключ в конфигурационный файл services.php:

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

Подписки

Создание подписок

Для создания подписки сначала получите экземпляр оплачиваемой модели, который обычно является экземпляром App\User. Когда вы получили модель, вы можете использовать метод PHPsubscription() для управления подписками модели:

PHP
$user User::find(1);

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

Метод PHPcreate() автоматически создаст подписку Stripe, а также внесёт в вашу базу данных ID заказчика Stripe и другую связанную информацию по оплате. Если для вашего тарифа настроен пробный период в Stripe, то для записи пользователя автоматически будет задана дата окончания периода.

Если вы хотите использовать пробные периоды, но при этом управлять ими полностью из своего приложения, а не определять их в Stripe, то вам надо задать дату окончания периода вручную:

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

$user->save();

Дополнительная информация о пользователе

Если вы хотите указать дополнительную информацию о пользователе, передайте её вторым аргументом методу PHPcreate():

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

Подробнее о дополнительных полях, поддерживаемых Stripe, читайте в документации по созданию заказчика Stripe.

Купоны

Если надо применить купон при создании подписки, используйте метод PHPwithCoupon():

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

Проверка статуса подписки

Когда пользователь подписан на ваше приложение, вы можете легко проверить статус его подписки при помощи различных удобных методов. Во-первых, метод PHPsubscribed() возвращает true, если подписка пользователя активна, даже если в данный момент она на пробном периоде:

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

Метод PHPsubscribed создаёт отличный вариант для посредника маршрута, позволяя вам фильтровать доступ к маршрутам и контроллерам на основе статусов подписок:

PHP
public function handle($requestClosure $next)
{
  if (
$request->user() && ! $request->user()->subscribed()) {
    
// Этот пользователь не оплатил подписку...
    
return redirect('billing');
  }

  return 
$next($request);
}

Вы также можете определить, идёт ли до сих пор пробный период у пользователя, с помощью метода PHPonTrial(). Этот метод полезен для предупреждения пользователя о том, что он на пробном периоде:

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

Метод PHPonPlan() используется для определения, подписан ли пользователь на данный тариф, на основе его Stripe ID:

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

Статус отменённой подписки

Чтобы определить, был ли пользователь ранее активным подписчиком, но позже отменил подписку, используйте метод PHPcancelled():

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

Вы можете также определить, отменил ли пользователь подписку, но находится все ещё на «льготном периоде», пока подписка полностью не истекла. Например, если пользователь отменяет подписку 5 марта, которая по плану закончится 10 марта, пользователь будет на «льготном периоде» до 10 марта. Обратите внимание на то, что метод PHPsubscribed() всё ещё возвращает true в это время.

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

Метод PHPeverSubscribed() используется для определения, подписывался ли пользователь когда-либо на ваше приложение:

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

Смена тарифа

Когда пользователь подписан на ваше приложение, он может захотеть сменить свой тарифный план. Чтобы переключить пользователя на новую подписку, используйте метод PHPswap(). Например, мы легко можем переключить пользователя на подписку premium:

PHP
$user App\User::find(1);

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

Если пользователь был на пробном периоде, то пробный период продолжится. Кроме того, если у подписки есть «количество», то оно тоже применится. При смене тарифа вы можете использовать метод PHPprorate(), чтобы указать, что стоимость должна быть пересчитана пропорционально. Вдобавок, вы можете использовать метод PHPswapAndInvoice() для того, чтобы выставить счёт за смену тарифа немедленно:

PHP
$user->subscription('premium')
            ->
prorate()
            ->
swapAndInvoice();

Количество подписки

Иногда подписки зависят от «количества». Например, ваше приложение стоит $10 в месяц с одного пользователя учётной записи. Чтобы легко увеличить или уменьшить количество вашей подписки, используйте методы PHPincrement() и PHPdecrement():

PHP
$user User::find(1);

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

// Добавить 5 к текущему количеству подписок...
$user->subscription()->increment(5);

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

// Вычесть 5 от текущего количества подписок...
$user->subscription()->decrement(5);

Или вы можете задать конкретное количество с помощью метода PHPupdateQuantity():

PHP
$user->subscription()->updateQuantity(10);

Более подробная информация о количествах подписок в документации Stripe.

Налог на подписку

С помощью Cashier можно легко изменить значение tax_percent, посылаемое в Stripe. Чтобы указать процент налога, который пользователь платит за подписку, реализуйте метод PHPgetTaxPercent() в своей модели, и верните числовое значение от 0 до 100 с не более, чем двумя знаками после запятой.

PHP
public function getTaxPercent() {
  return 
20;
}

Это позволяет вам использовать разные налоговые ставки по-модельно, что будет полезно при наличии пользователей из разных стран.

Отмена подписки

Отменить подписку можно методом PHPcancel():

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

При отмене подписки Cashier автоматически задаст столбец subscription_ends_at в вашей базе данных. Этот столбец используется, чтобы знать, когда метод PHPsubscribed() должен начать возвращать false. Например, если клиент отменит подписку 1 марта, но срок подписки по плану до 5 марта, то метод PHPsubscribed() будет продолжать возвращать true до 5 марта.

Вы можете определить то, что пользователь отменил подписку, но находится на «льготном периоде», при помощи метода PHPonGracePeriod ():

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

Возобновление подписки

Если подписка была отменена пользователем, и вам надо её возобновить, используйте метод PHPresume():

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

Если пользователь отменит подписку и затем возобновит её до того, как она полностью истекла, тогда не произойдет моментального расчёта оплаты. Его подписка будет просто повторно активирована, и расчёт оплаты будет происходить по изначальному циклу.

Обработка веб-хуков Stripe

Неудавшиеся подписки

Что если срок действия банковской карты клиента истёк? Никаких проблем — Cashier включает в себя контроллер PHPWebhook, который может легко отменить подписку клиента. Просто укажите путь к контроллеру:

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

Вот и всё! Неудавшиеся платежи будут перехвачены и обработаны контроллером. Контроллер отменит подписку клиента, если Stripe определит, что подписка не удалась (обычно после трёх неудавшихся платежей). URI Stripe/webhook в этом примере взят просто для примера. Вам надо настроить URI в параметрах вашего Stripe.

Поскольку веб-хуки Stripe должны идти в обход CSRF проверок Laravel, не забудьте включить URI в список иключений вашего посредника VerifyCsrfToken:

PHP
protected $except = [
    
'stripe/*',
];

Другие веб-хуки

Если у вас есть дополнительные webhook-события для Stripe, которые вы хотели бы обработать, просто наследуйте контроллер PHPWebhook. Ваши имена методов должны соответствовать принятому в Cashier соглашению, в частности, методы должны быть снабжены префиксом handle и именем того webhook-события Stripe, которое вы хотите обработать, в стиле «CamelCase». Например, если вы хотите обработать webhook PHPinvoice.payment_succeeded, вы должны добавить метод PHPhandleInvoicePaymentSucceeded() в контроллер.

PHP
<?php

namespace App\Http\Controllers;

use 
Laravel\Cashier\WebhookController as BaseController;

class 
WebhookController extends BaseController
{
  
/**
   * Обработка веб-хука stripe.
   *
   * @param  array  $payload
   * @return Response
   */
  
public function handleInvoicePaymentSucceeded($payload)
  {
    
// Обработка события
  
}
}

Одиночные платежи

Если вы хотите сделать «одноразовый» платёж вместо использования банковской карты подписанного пользователя, используйте метод PHPcharge() для экземпляра модели. Метод PHPcharge() принимает сумму, которую необходимо оплатить, с наименьшим знаменателем используемой в вашем приложении валюты. Например, в этом примере будет списано 100 центов, или $1, с банковской карты пользователя:

PHP
$user->charge(100);

Метод PHPcharge() принимает в качестве второго аргумента массив, позволяя вам передавать любые необходимые параметры для создания основного Stripe-платежа:

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

Метод PHPcharge() вернёт false, если платёж не пройдёт. Обычно это значит, что платёж был отклонён:

PHP
if ( ! $user->charge(100)) {
  
// Платёж был отклонён...
}

Если платёж прошёл успешно, метод возвратит полный Stripe-ответ.

+ 5.0

добавлено в 5.0 ()

Без предоплаты

Если в вашем приложении будет бесплатный пробный период, не требующий предварительного предъявления банковской карты, установите свойство cardUpFront вашей модели в false:

PHP
protected $cardUpFront false;

При создании аккаунта не забудьте установить дату окончания пробного периода в модели:

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

$user->save();

Счета

Вы можете легко получить массив счетов пользователя, используя метод PHPinvoices():

PHP
$invoices $user->invoices();

При просмотре счетов клиента вы можете использовать эти вспомогательные методы, чтобы вывести на экран соответствующую информацию о счёте. Например, вам может понадобиться просмотреть каждый счёт в таблице, позволив пользователю легко скачать любой из них:

PHP
<table>
  @foreach (
$invoices as $invoice)
    <
tr>
      <
td>{{ $invoice->dateString() }}</td>
      <
td>{{ $invoice->dollars() }}</td>
      <
td><a href="/user/invoice/{{ $invoice->id }}">Download</a></td>
    </
tr>
  @endforeach
</
table>

Создание PDF-файлов счетов

Используйте метод PHPdownloadInvoice() в маршруте или контроллере, чтобы cгенерировать PDF-файл счёта. Этот метод автоматически сгенерирует нужный HTTP-отклик чтобы отправить загрузку в браузер:

PHP
Route::get('user/invoice/{invoice}', function ($invoiceId) {
  return 
Auth::user()->downloadInvoice($invoiceId, [
    
'vendor'  => 'Your Company',
    
'product' => 'Your Product',
  ]);
});

Написать комментарий

Разметка: ? ?

Авторизуйся, чтобы прокомментировать.