shekel / shekel
Payment package for laravel applications
Installs: 22
Dependents: 0
Suggesters: 0
Security: 0
Stars: 2
Watchers: 6
Forks: 0
Open Issues: 0
Type:project
Requires
- stripe/stripe-php: ^7.13
Requires (Dev)
- mockery/mockery: ^1.0
- orchestra/testbench: ^3.8|^4.0|^5.0
- phpunit/phpunit: ^7.5|^8.0
This package is auto-updated.
Last update: 2024-04-04 20:10:20 UTC
README
Via Composer
$ composer require shekel/shekel
For Laravel version < 5.5
If you don't use auto-discovery, add the ServiceProvider to the providers array in config/app.php
Shekel\ShekelServiceProvider::class,
Migrations
In order to use shekel you need to run migrations. It will add a meta field to your users table. Additionally subscriptions and plans tables will be created.
If you want to disable migrations just add Shekel::$disableMigrations = true;
to your AppServiceProvider boot method.
Configuration
Billable model
To use shekel just add Billable trait to your model that you will be billing.
use Shekel\Traits\Billable; class User extends Authenticatable { use Billable; }
If you are using a different model just define it in your .env file
BILLABLE_MODEL=\App\MyModel
API keys
In order to use stripe you need to add your stripe public and secret keys to the .env file. You can find your api keys in your stripe dashboard > Developers > API keys
STRIPE_PUBLIC=pk_test_xxxxxx
STRIPE_SECRET=sk_test_xxxxxx
Currency configuration
Default currency is set to USD, but you can change that in your .env file
BILLABLE_CURRENCY=eur
List of supported currencies (by stripe for now):
USD, AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BIF, BMD, BND, BOB, BRL, BSD, BWP, BZD, CAD, CDF, CHF, CLP, CNY, COP, CRC, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ETB, EUR, FJD, FKP, GBP, GEL, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, ISK, JMD, JPY, KES, KGS, KHR, KMF, KRW, KYD, KZT, LAK, LBP, LKR, LRD, LSL, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SEK, SGD, SHP, SLL, SOS, SRD, STD, SZL, THB, TJS, TOP, TRY, TTD, TWD, TZS, UAH, UGX, UYU, UZS, VND, VUV, WST, XAF, XCD, XOF, XPF, YER, ZAR, ZMW
Usage
Plans
In order to make subscriptions first you need to create a new plan.
use Shekel\Models\Plan; $plan = Plan::create([ 'title' => 'Basic monthly', //Your plan name 'price' => 999, //Plan price in cents 'billing_period' => 'monthly', //Supported periods - daily, weekly, monthly, yearly 'trial_period_days' => 30, //trial days (max 730) ]);
All data is validated under the hood, and a plan in stripe database is created assuming stripe is enabled.
To update a plan you can use laravels default update method and the plan will update in stripe also. NOTICE: stripe does not allow updating any fields except trial_period_days so all updates are validated and will throw ValidationException if you try to update any restricted fields.
//WILL THROW AN EXCEPTION $plan->update(['title' => 'my-title']); //WILL UPDATE NORMALY $plan->update(['trial_period_days' => 10]);
To delete a plan just call the delete method. Stripe plan will also be deleted (but the product that the plan is attached to will remain intact).
$plan->delete();
If all is successful you should go to your stripe dashboard > Billing > Products and see a new product created.
Forms
After creating a plan you need to setup a payment form.
First you will need to list your plans so use can pick whitch plan he is subscribing to.
//TODO create a @include('Shekel::plans') view helper.
<div class="mb-3 mt-3"> <label>Plan</label> <select name="billing_plan_id" class="form-control"> @foreach($plans as $plan) <option value="{{ $plan->id }}">{{ $plan->title }} - {{ number_format($plan->price / 100, 2) }}</option> @endforeach </select> </div>
After that you need to add a credit card field in your form. Package provides a helper so you don't need to deal with stripes html/css/js.
@include('Shekel::stripe.payment_form')
Last thing to do is adding shekel-form
class to your html form.
<form method="POST" action="{{ route('register') }}" class="shekel-form">
//TODO Think through use case scenarios and make more convenient helpers. Adding a class to a form is not practical and register form is not the only use case.
Subscriptions
After submitting a form to your controller you need to subscribe the user to a plan. To do that all you need to do is call stripeSubscription method on the user model. First argument is plan id that you are subscribing to and the second parameter is a payment method string privided by stripe from the credit card form.
class RegisterController extends Controller { public function create(Request $request) { $user = User::create($request->all()); $plan = $request->input('billing_plan_id'); $paymentMethod = $request->input('payment_method'); $user->newSubscription('stripe', $plan, $paymentMethod)->create(); } }
And thats it. Your user is now subscribed to your defined plan.
Canceling a subscripton
To cancel a subscription just run:
$user->subscription()->cancel();
To cancel multiple subscriptions use the provided subscritions relationship:
use Shekel\Models\Subscription; $user->subscriptions()->each(fn(Subscription $subscription) => $subscription->cancel());
By default canceling a subscription will hold it's grace period until the subscription expires. If you want to cancel the subscription now use cancelNow method.
$user->subscription()->cancelNow();
Changing the plan that user subscribes to
If you want to change users subscription plan just call changePlan method on any subscription. Single argument needed is the plan id that you want to swap to.
$user->subscription()->changePlan(2);
Handling subscription quantities
If you have a quantity based subscription (eg. subscription price is based on how many users a team has) then you can use changeQuantity method to increase or decrease it. Single argument required is the quantity amount number.
$user->subscription()->changeQuantity(2);
By default quantity is always set to 1 so if you want to adjust the quantity while creating the subscription use quantity method.
$user->newSubscription('stripe', $plan_id, $paymentMethod)->quantity(2)->create();