Filament Payments Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require tomatophp/filament-payments
   

   Publish the package assets and config:

   php artisan vendor:publish --provider="TomatoPHP\FilamentPayments\FilamentPaymentsServiceProvider" --tag="filament-payments-config"
   php artisan vendor:publish --provider="TomatoPHP\FilamentPayments\FilamentPaymentsServiceProvider" --tag="filament-payments-migrations"
   

   Run migrations:

   php artisan migrate
   

2. Register the plugin in app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \TomatoPHP\FilamentPayments\FilamentPaymentsPlugin::make(),
           ]);
   }
   

3. First Use Case:

   • Navigate to Filament Admin Panel > Payments to view existing payments.
   • Configure a payment gateway (e.g., Stripe, PayPal) via Payment Gates under the plugin menu.
   • Create a payment action (e.g., "Subscribe to Pro Plan") linked to a gateway and amount.

Implementation Patterns

Core Workflows

1. Gateway Configuration:

   • Define gateways in config/filament-payments.php or via the Payment Gates admin panel.
   • Example for Stripe:

     'gates' => [
         'stripe' => [
             'driver' => 'stripe',
             'key' => env('STRIPE_KEY'),
             'secret' => env('STRIPE_SECRET'),
             'currency' => 'usd',
         ],
     ],
     

   • Use the TomatoPHP\FilamentPayments\Gateways\Gateway facade to dynamically fetch gateways:

     $gateway = \TomatoPHP\FilamentPayments\Facades\Gateway::find('stripe');
     

2. Creating Payments:

   • Attach payments to Filament resources via Payment Actions:

     use TomatoPHP\FilamentPayments\Actions\CreatePaymentAction;
     
     public static function getActions(): array
     {
         return [
             CreatePaymentAction::make()
                 ->gateway('stripe')
                 ->amount(9.99)
                 ->name('Upgrade to Pro'),
         ];
     }
     

   • Trigger payments programmatically:

     $payment = \TomatoPHP\FilamentPayments\Facades\Payment::create([
         'gateway_id' => 1,
         'amount' => 9.99,
         'currency' => 'usd',
         'metadata' => ['user_id' => auth()->id()],
     ]);
     

3. Webhook Handling:

   • Register a webhook controller to handle gateway callbacks (e.g., Stripe events):

     use TomatoPHP\FilamentPayments\Webhooks\StripeWebhookController;
     
     Route::post('/filament-payments/webhooks/stripe', [StripeWebhookController::class, 'handle']);
     

   • Verify and process events in app/Http/Controllers/WebhookController.php:

     public function handle(Request $request)
     {
         return \TomatoPHP\FilamentPayments\Facades\Webhook::handle($request);
     }
     

4. Subscription Management:

   • Use the TomatoPHP\FilamentPayments\Subscriptions\Subscription model to manage recurring payments:

     $subscription = \TomatoPHP\FilamentPayments\Facades\Subscription::create([
         'gateway_id' => 1,
         'user_id' => auth()->id(),
         'plan' => 'premium',
     ]);
     

Integration Tips

• Custom Fields: Extend the Payment model to add custom fields (e.g., invoice_number):

  use TomatoPHP\FilamentPayments\Models\Payment;
  
  class CustomPayment extends Payment
  {
      protected $casts = [
          'invoice_number' => 'string',
      ];
  }
  

  Update the config to use your custom model:

  'models' => [
      'payment' => \App\Models\CustomPayment::class,
  ],
  

• Localization: Override labels and messages in resources/lang/en/payments.php:

  return [
      'actions' => [
          'create_payment' => 'Make Payment',
      ],
  ];
  

• Testing: Use test modes for gateways (e.g., Stripe test keys) and mock webhooks:

  $gateway = \TomatoPHP\FilamentPayments\Facades\Gateway::find('stripe-test');
  

Gotchas and Tips

Pitfalls

1. Webhook Verification:

   • Always verify webhook signatures in production. Use the Webhook::handle() method with the verify option:

     \TomatoPHP\FilamentPayments\Facades\Webhook::handle($request, verify: true);
     

   • For Stripe, ensure the STRIPE_WEBHOOK_SECRET is set in .env.

2. Gateway-Specific Quirks:

   • PayPal: Use sandbox mode for testing (sandbox: true in config).
   • Stripe: Ensure STRIPE_KEY and STRIPE_SECRET are correctly set. For subscriptions, use TomatoPHP\FilamentPayments\Subscriptions\Subscription methods like create() or cancel().
   • Custom Gateways: Implement the TomatoPHP\FilamentPayments\Contracts\Gateway interface for third-party integrations.

3. Migration Conflicts:

   • If you customize the Payment or Gateway tables, run php artisan vendor:publish --tag="filament-payments-migrations" again to update the published migrations.

4. Permission Issues:

   • Ensure users have the view payments, create payments, or manage gates permissions in Filament. Add roles via:

     public static function getPages(): array
     {
         return [
             \TomatoPHP\FilamentPayments\Resources\PaymentResource::class,
             \TomatoPHP\FilamentPayments\Resources\GatewayResource::class,
         ];
     }
     

Debugging

• Logs: Enable debug mode in config/filament-payments.php:

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

  Check logs in storage/logs/laravel.log for gateway errors.

• Webhook Testing: Use tools like Stripe CLI or Ngrok to test webhooks locally:

  stripe listen --forward-to localhost:8000/filament-payments/webhooks/stripe
  

Extension Points

1. Custom Actions: Extend CreatePaymentAction to add pre/post-payment logic:

   use TomatoPHP\FilamentPayments\Actions\Concerns\InteractsWithPayments;
   
   class CustomPaymentAction extends CreatePaymentAction
   {
       use InteractsWithPayments;
   
       protected function afterPaymentCreated(Payment $payment)
       {
           // Send email, update user role, etc.
       }
   }
   

2. Gateway Drivers: Create custom drivers by implementing the Gateway contract:

   namespace App\Gateways;
   
   use TomatoPHP\FilamentPayments\Contracts\Gateway;
   
   class CustomGateway implements Gateway
   {
       public function createPayment(array $data): array
       {
           // Custom logic
       }
   
       // Implement other required methods
   }
   

   Register the driver in the config:

   'gateways' => [
       'custom' => [
           'driver' => \App\Gateways\CustomGateway::class,
       ],
   ],
   

3. Resource Customization: Override the default resources by binding them in AppServiceProvider:

   public function boot()
   {
       $this->app->bind(
           \TomatoPHP\FilamentPayments\Resources\PaymentResource::class,
           \App\Resources\CustomPaymentResource::class
       );
   }