Download the PHP package controlla/conekta-cashier without Composer
On this page you can find all versions of the php package controlla/conekta-cashier. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package conekta-cashier
Laravel Conekta Cashier
Port of Conekta Laravel Cashier to Conekta
Please note the latest version of Laravel Cashier supports Laravel 5+, if you are looking for the Laravel 4 implementation see the 1.0 branch.
Conekta Cashier
- Introduction
- Installation
- Configuration
- Customers
- Subscribing To A Plan
- Single Charges
- Swapping Subscriptions
- Cancelling A Subscription
- Resuming A Subscription
- Checking Subscription Status
- Handling Conekta Webhooks
- Testing
Introduction
Conekta Cashier provides an expressive, fluent interface to Conekta's subscription billing services. It handles almost all of the boilerplate subscription billing code you are dreading writing. In addition to basic subscription management, Cashier can handle coupons, swapping subscription, subscription "quantities", cancellation grace periods, and even generate invoice PDFs.
Installation
First, install the Cashier package for Conekta using the Composer package manager:
composer require controlla/conekta-cashier
Database Migrations
Conekta's service provider registers its own database migration directory, so remember to migrate your database after installing the package. The Cashier migrations will add several columns to your users
table as well as create a new subscriptions table to hold all of your customer's subscriptions
:
php artisan migrate
If you need to overwrite the migrations that ship with Cashier, you can publish them using the vendor:publish
Artisan command:
php artisan vendor:publish --tag="cashier-migrations"
If you would like to prevent Cashier's migrations from running entirely, you may use the ignoreMigrations
method provided by Cashier. Typically, this method should be called in the register
method of your AppServiceProvider
:
use Controlla\ConektaCashier\Cashier;
/**
* Register any application services.
*
* @return void
*/
public function register()
{
Cashier::ignoreMigrations();
}
Configuration
Billable Model
Before using Cashier, add the Billable
trait to your billable model definition. Typically, this will be the App\Models\User
model. This trait provides various methods to allow you to perform common billing tasks, such as creating subscriptions, applying coupons, and updating payment method information:
use Controlla\ConektaCashier\Billable;
class User extends Authenticatable
{
use Billable;
}
Cashier assumes your billable model will be the App\Models\User
class that ships with Laravel. If you wish to change this you may specify a different model via the useCustomerModel
method. This method should typically be called in the boot method of your AppServiceProvider
class:
use App\Models\Cashier\User;
use Controlla\ConektaCashier\Cashier;
/**
* Bootstrap any application services.
*
* @return void
*/
public function boot()
{
Cashier::useCustomerModel(User::class);
}
:exclamation: If you're using a model other than Laravel's supplied
App\Models\User
model, you'll need to publish and alter the Cashier migrations provided to match your alternative model's table
API Keys
Next, you should configure your Conekta API keys in your application's .env
file. You can retrieve your Conekta API keys from the Conekta control panel:
CONEKTA_KEY=your-conekta-key
CONEKTA_SECRET=your-conekta-secret
Currency Configuration
The default Cashier currency is Mexican pesos (MXN). You can change the default currency by setting the CASHIER_CURRENCY
environment variable within your application's .env
file:
CASHIER_CURRENCY=eur
In addition to configuring Cashier's currency, you may also specify a locale to be used when formatting money values for display on invoices. Internally, Cashier utilizes PHP's NumberFormatter class
to set the currency locale:
CASHIER_CURRENCY_LOCALE=nl_BE
Customers
Retrieving Customers
You can retrieve a customer by their Conekta ID using the Cashier::findBillable method. This method will return an instance of the billable model:
use Controlla\ConektaCashier\Cashier;
$user = Cashier::findBillable($conektaId);
Creating Customers
Occasionally, you may wish to create a Conekta customer without beginning a subscription. You may accomplish this using the createAsConektaCustomer method:
$conektaCustomer = $user->createAsConektaCustomer();
Subscribing To A Plan
Once you have a model instance, you can easily subscribe that user to a given Conekta plan:
$user = User::find(1);
$user->subscription('monthly')->create($creditCardToken);
You can also extend a subscription trial.
$subscription = $user->subscription('monthly')->create($creditCardToken);
$user->extendTrial(Carbon::now()->addMonth());
The subscription
method will automatically create the Conekta subscription, as well as update your database with Conekta customer ID and other relevant billing information. If your plan has a trial configured in Conekta, the trial end date will also automatically be set on the user record.
If your plan has a trial period that is not configured in Conekta, you must set the trial end date manually after subscribing:
$user->trial_ends_at = Carbon::now()->addDays(14);
$user->save();
Specifying Additional User Details
If you would like to specify additional customer details, you may do so by passing them as second argument to the create
method:
$user->subscription('monthly')->create($creditCardToken, [
'email' => $email, 'name' => 'Joe Doe'
]);
To learn more about the additional fields supported by Conekta, check out Conekta's documentation on customer creation.
Single Charges
If you would like to make a "one off" charge against a subscribed customer's credit card, you may use the charge
method:
$user->charge(100);
The charge
method accepts the amount you would like to charge in the lowest denominator of the currency. So, for example, the example above will charge 100 cents, or $1.00, against the user's credit card.
The charge
method accepts an array as its second argument, allowing you to pass any options you wish to the underlying Conekta charge creation:
$user->charge(100, [
'card' => $token,
]);
The charge
method will return false
if the charge fails. This typically indicates the charge was denied:
if ( ! $user->charge(100))
{
// The charge was denied...
}
If the charge is successful, the full Conekta response will be returned from the method.
Swapping Subscriptions
To swap a user to a new subscription, use the swap
method:
$user->subscription('premium')->swap();
If the user is on trial, the trial will be maintained as normal. Also, if a "quantity" exists for the subscription, that quantity will also be maintained.
Cancelling A Subscription
Cancelling a subscription is a walk in the park:
$user->subscription()->cancel();
When a subscription is cancelled, Cashier will automatically set the subscription_ends_at
column on your database. This column is used to know when the subscribed
method should begin returning false
. For example, if a customer cancels a subscription on March 1st, but the subscription was not scheduled to end until March 5th, the subscribed
method will continue to return true
until March 5th.
Resuming A Subscription
If a user has cancelled their subscription and you wish to resume it, use the resume
method:
$user->subscription('monthly')->resume($creditCardToken);
If the user cancels a subscription and then resumes that subscription before the subscription has fully expired, they will not be billed immediately. Their subscription will simply be re-activated, and they will be billed on the original billing cycle.
Checking Subscription Status
To verify that a user is subscribed to your application, use the subscribed
command:
if ($user->subscribed())
{
//
}
The subscribed
method makes a great candidate for a route middleware:
public function handle($request, Closure $next)
{
if ($request->user() && ! $request->user()->subscribed())
{
return redirect('billing');
}
return $next($request);
}
You may also determine if the user is still within their trial period (if applicable) using the onTrial
method:
if ($user->onTrial())
{
//
}
To determine if the user was once an active subscriber, but has cancelled their subscription, you may use the cancelled
method:
if ($user->cancelled())
{
//
}
You may also determine if a user has cancelled their subscription, but are still on their "grace period" until the subscription fully expires. For example, if a user cancels a subscription on March 5th that was scheduled to end on March 10th, the user is on their "grace period" until March 10th. Note that the subscribed
method still returns true
during this time.
if ($user->onGracePeriod())
{
//
}
The everSubscribed
method may be used to determine if the user has ever subscribed to a plan in your application:
if ($user->everSubscribed())
{
//
}
The onPlan
method may be used to determine if the user is subscribed to a given plan based on its ID:
if ($user->onPlan('monthly'))
{
//
}
Handling Conekta Webhooks
Conekta can notify your application of a variety of events via webhooks. By default, a route that points to Cashier's webhook controller is automatically registered by the Cashier service provider. This controller will handle all incoming webhook requests.
By default, the Conekta Cashier webhook controller will automatically handle cancelling subscriptions that have too many failed charges (as defined by your Conekta settings), customer updates, customer deletions, subscription updates, and payment method changes; however, as we'll soon discover, you can extend this controller to handle any Conekta webhook event you like.
To ensure your application can handle Conekta webhooks, be sure to configure the webhook URL in the Conekta control panel. By default, Cashier's webhook controller responds to the /conekta/webhook
URL path.
For convenience, Cashier includes a cashier:webhook
Artisan command. This command will create a webhook in Conekta that listens to all of the events required by Cashier:
php artisan cashier:webhook
By default, the created webhook will point to the URL defined by the APP_URL
environment variable and the cashier.webhook
route that is included with Cashier. You may provide the --url
option when invoking the command if you would like to use a different URL:
php artisan cashier:webhook --url "https://example.com/conekta/webhook"
Defining Webhook Event Handlers
Cashier automatically handles subscription cancellations for failed charges and other common Conekta webhook events. However, if you have additional webhook events you would like to handle, you may do so by listening to the following events that are dispatched by Cashier:
Controlla\ConektaCashier\Events\WebhookReceived
Controlla\ConektaCashier\Events\WebhookHandled
Both events contain the full payload of the Conekta webhook. For example, if you wish to handle the charge.paid
webhook, you may register a listener that will handle the event:
<?php
namespace App\Listeners;
use Controlla\ConektaCashier\Events\WebhookReceived;
class ConektaEventListener
{
/**
* Handle received Conekta webhooks.
*
* @param \Controlla\ConektaCashier\Events\WebhookReceived $event
* @return void
*/
public function handle(WebhookReceived $event)
{
if ($event->payload['type'] === 'charge.paid') {
// Handle the incoming event...
}
}
}
Once your listener has been defined, you may register it within your application's EventServiceProvider
:
<?php
namespace App\Providers;
use App\Listeners\ConektaEventListener;
use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider;
use Controlla\ConektaCashier\Events\WebhookReceived;
class EventServiceProvider extends ServiceProvider
{
protected $listen = [
WebhookReceived::class => [
ConektaEventListener::class,
],
];
}
Testing
When testing an application that uses Cashier, you may mock the actual HTTP requests to the Conekta API; however, this requires you to partially re-implement Cashier's own behavior. Therefore, we recommend allowing your tests to hit the actual Conekta API. While this is slower, it provides more confidence that your application is working as expected and any slow tests may be placed within their own PHPUnit testing group.
When testing, remember that Cashier itself already has a great test suite, so you should only focus on testing the subscription and payment flow of your own application and not every underlying Cashier behavior.
To get started, add the testing version of your Conekta secret to your phpunit.xml
file:
<env name="CONEKTA_SECRET" value="<your-key>"/>
Now, whenever you interact with Cashier while testing, it will send actual API requests to your Conekta testing environment.
All versions of conekta-cashier with dependencies
conekta/conekta-php Version dev-master
illuminate/contracts Version ^6.0|^7.0|^8.0
illuminate/filesystem Version ^6.0|^7.0|^8.0
illuminate/routing Version ^6.0|^7.0|^8.0
illuminate/support Version ^6.0|^7.0|^8.0
illuminate/view Version ^6.0|^7.0|^8.0
moneyphp/money Version 3.x-dev