Laravel Billing Core Laravel Package

Getting Started

Minimal Steps

1. Install & Publish Config

   composer require emeroid/laravel-billing-core
   php artisan vendor:publish --provider="Emeroid\Billing\BillingServiceProvider" --tag="billing-config"
   php artisan vendor:publish --provider="Emeroid\Billing\BillingServiceProvider" --tag="billing-migrations"
   php artisan migrate
   

   • Configure config/billing.php with your gateway (Paystack/PayPal) credentials.

2. Add Billable Trait to User Model

   use Emeroid\Billing\Traits\Billable;
   
   class User extends Authenticatable
   {
       use Billable;
   }
   

3. First Use Case: One-Time Payment

   use Emeroid\Billing\Facades\Billing;
   
   $user = auth()->user();
   $payment = Billing::charge($user, 1000, 'USD', [
       'description' => 'Premium Feature Unlock'
   ]);
   

Implementation Patterns

Core Workflows

1. Subscription Management

   // Subscribe a user to a plan
   $subscription = Billing::subscribe($user, 'monthly', [
       'price' => 2999, // $29.99
       'currency' => 'USD',
       'trial_days' => 7
   ]);
   
   // Cancel subscription (immediately or at end of period)
   $subscription->cancel(); // Immediate
   $subscription->cancel(true); // Cancel at end of period
   
   // Swap plans (e.g., upgrade/downgrade)
   $subscription->swapPlan('annual', [
       'price' => 24999, // $249.99
       'currency' => 'USD'
   ]);
   

2. Webhook Handling (Dunning)

   • Register a webhook controller to handle invoice.payment_failed events:

     public function handleWebhook(Request $request)
     {
         $event = Billing::handleWebhook($request);
         if ($event->type === 'invoice.payment_failed') {
             $subscription = $event->subscription;
             $subscription->markPastDue();
         }
     }
     

3. Event Listeners

   • Listen for subscription lifecycle events:

     // app/Providers/EventServiceProvider.php
     protected $listen = [
         'Emeroid\Billing\Events\SubscriptionStarted' => [
             'App\Listeners\SendWelcomeEmail',
         ],
         'Emeroid\Billing\Events\SubscriptionCancelled' => [
             'App\Listeners\NotifyUserCancellation',
         ],
     ];
     

Integration Tips

• Plan Management: Store plans in a plans table and reference them by ID in subscriptions.
• Grace Periods: Use cancelAtEndOfPeriod for smoother user experience.
• Multi-Gateway: Switch gateways by updating BILLING_GATEWAY in .env (e.g., paystack → paypal).

Gotchas and Tips

Pitfalls

1. Webhook Verification

   • Always verify webhook signatures to avoid spoofing attacks. Use the Billing::verifyWebhook() method.
   • Example:

     $isValid = Billing::verifyWebhook($request, $request->header('stripe-signature'));
     

2. Currency and Price Handling

   • Ensure prices are stored in the smallest currency unit (e.g., cents for USD). The package expects integers.
   • Example: $29.99 → 2999.

3. Subscription State Confusion

   • cancelled vs. past_due: Use markPastDue() for failed payments (dunning) and cancel() for intentional cancellations.
   • Check subscription status with $subscription->status (e.g., active, cancelled, past_due).

4. Migration Order

   • Run migrations after publishing the config to avoid errors:

     php artisan migrate
     

Debugging

• Log Webhook Events: Enable debug mode in config/billing.php to log webhook payloads:

  'debug' => env('BILLING_DEBUG', false),
  

• Test with Sandbox: Use Paystack/PayPal sandbox modes during development (BILLING_ENV=sandbox in .env).

Extension Points

1. Custom Gateways

   • Extend the Emeroid\Billing\Contracts\Gateway interface to add support for Stripe, Flutterwave, etc.
   • Example:

     class StripeGateway implements Gateway
     {
         public function charge(...)
         {
             // Custom Stripe logic
         }
     }
     

   • Register the gateway in config/billing.php under gateways.

2. Custom Events

   • Extend the event system by publishing custom events:

     event(new CustomSubscriptionEvent($subscription));
     

3. Plan Validation

   • Override plan validation logic by binding a custom validator to the plan.validating event:

     Billing::extend('plan.validating', function ($plan) {
         if ($plan->price < 100) {
             throw new \InvalidArgumentException('Price too low!');
         }
     });