Laravel Recurly Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require christhompsontldr/laravel-recurly
   

   Add the service provider to config/app.php under providers:

   ChrisThompsontldr\LaravelRecurly\LaravelRecurlyServiceProvider::class,
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="ChrisThompsontldr\LaravelRecurly\LaravelRecurlyServiceProvider"
   

   Update .env with your Recurly API keys:

   RECURLY_API_KEY=your_api_key_here
   RECURLY_SUBDOMAIN=your_subdomain
   

3. First Use Case Fetch a customer in a controller or service:

   use ChrisThompsontldr\LaravelRecurly\Facades\Recurly;
   
   $customer = Recurly::customer()->find('customer_code');
   

Implementation Patterns

Core Workflows

1. Customer Management

   • Create/update customers:

     Recurly::customer()->create([
         'account_code' => 'user123',
         'email' => 'user@example.com',
         'first_name' => 'John',
         'last_name' => 'Doe',
     ]);
     

   • List customers:

     $customers = Recurly::customer()->all();
     

2. Subscription Handling

   • Create a subscription:

     Recurly::subscription()->create([
         'account_code' => 'user123',
         'plan_code' => 'monthly_plan',
         'billing_info' => [
             'first_name' => 'John',
             'last_name' => 'Doe',
             'number' => '4111111111111111',
             'month' => '12',
             'year' => '2025',
         ],
     ]);
     

   • Cancel a subscription:

     Recurly::subscription()->cancel('subscription_code');
     

3. Webhook Handling

   • Register a webhook route in routes/web.php:

     Route::post('/recurly/webhook', 'RecurlyWebhookController@handle');
     

   • Process webhooks in a controller:

     public function handle(Request $request) {
         $event = Recurly::webhook()->parse($request->input());
         // Handle event (e.g., subscription canceled)
     }
     

4. Integration with Laravel Auth

   • Attach Recurly account codes to Laravel users:

     // In User model
     public function recurlyAccount() {
         return $this->hasOne(RecurlyAccount::class);
     }
     

   • Sync accounts on login:

     $user->recurlyAccount()->updateOrCreate([
         'account_code' => 'user_' . $user->id,
     ], [
         'email' => $user->email,
     ]);
     

Gotchas and Tips

Pitfalls

1. Deprecated Laravel Version

   • The package is designed for Laravel 5.x and may not work with newer versions (e.g., Laravel 8+). Test thoroughly if upgrading.
   • Workaround: Use a compatibility layer like laravel/framework:^5.8 or fork the package.

2. Recurly Client Version Lock

   • The package pins recurly/recurly-client:2.6.*, which is very old (2016). Newer Recurly APIs may break compatibility.
   • Workaround: Override the client in config/laravel-recurly.php:

     'client' => \Recurly\RecurlyClient::class, // Use a newer version if needed
     

3. Webhook Security

   • The package does not include built-in webhook signature verification. Always validate signatures manually:

     use Recurly\Webhook;
     
     $webhook = new Webhook($request->input());
     if (!$webhook->verifySignature($request->header('X-Recurly-Signature'))) {
         abort(403, 'Invalid signature');
     }
     

4. Error Handling

   • Recurly API errors are not automatically converted to Laravel exceptions. Wrap calls in try-catch:

     try {
         $customer = Recurly::customer()->find('nonexistent');
     } catch (\Recurly\Error\RecurlyError $e) {
         Log::error("Recurly error: " . $e->getMessage());
         return response()->json(['error' => 'Payment failed'], 400);
     }
     

Tips

1. Testing

   • Use Recurly’s sandbox environment for testing. Set RECURLY_SUBDOMAIN=sandbox in .env.testing.

2. Logging

   • Enable debug logging in config/laravel-recurly.php:

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

   • Log webhook events for debugging:

     Log::debug('Recurly webhook event:', $event->toArray());
     

3. Performance

   • Cache Recurly client instances if making frequent API calls:

     $client = app('recurly.client'); // Reuse instance
     

4. Extending Functionality

   • Add custom methods to the facade for frequent operations:

     // In AppServiceProvider
     Recurly::extend('subscription', function ($app) {
         return new class {
             public function getActiveForUser($user) {
                 return Recurly::subscription()->all(['account_code' => $user->recurly_account_code]);
             }
         };
     });
     

   • Use the facade in views:

     @inject('recurly', 'ChrisThompsontldr\LaravelRecurly\Facades\Recurly')
     {{ $recurly->subscription()->getActiveForUser(auth()->user())->count() }} active subscriptions
     

5. Migration Notes

   • If upgrading Laravel, ensure middleware like VerifyCsrfToken doesn’t interfere with Recurly webhooks. Exclude the route:

     Route::post('/recurly/webhook', 'RecurlyWebhookController@handle')->middleware('webhook.verify');