Stripe Php Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require stripe/stripe-php
   

   Add to composer.json autoload if not using Composer's default:

   "autoload": {
       "psr-4": {
           "App\\": "src/",
           "Stripe\\": "vendor/stripe/stripe-php/src/"
       }
   }
   

2. Initialize Client:

   require __DIR__ . '/vendor/autoload.php';
   \Stripe\Stripe::setApiKey(config('services.stripe.key')); // Laravel config
   

3. First Use Case: Create a customer and charge:

   $customer = \Stripe\Customer::create([
       'email' => 'user@example.com',
       'name' => 'John Doe',
       'payment_method' => 'pm_123',
   ]);
   $charge = \Stripe\Charge::create([
       'amount' => 1000,
       'currency' => 'usd',
       'customer' => $customer->id,
   ]);
   

Where to Look First

• API Docs for resource-specific methods.
• Laravel Integration Guide (if using Laravel).
• StripeClient class for service-based patterns (preferred in modern versions).

Implementation Patterns

Core Workflows

1. Service-Based Pattern (Recommended)

   $stripe = new \Stripe\StripeClient(config('services.stripe.key'));
   $customer = $stripe->customers->create([...]);
   

   • Pros: Cleaner, more explicit, supports dependency injection.
   • Cons: Requires SDK v7.33.0+ (use legacy \Stripe\Customer::create() otherwise).

2. Legacy Static Pattern

   \Stripe\Stripe::setApiKey(config('services.stripe.key'));
   $customer = \Stripe\Customer::create([...]);
   

   • Use Case: Quick scripts or older codebases.

3. Webhook Handling

   use Stripe\Webhook;
   
   $payload = file_get_contents('php://input');
   $sig_header = $_SERVER['HTTP_STRIPE_SIGNATURE'];
   $event = Webhook::constructEvent($payload, $sig_header, config('services.stripe.webhook_secret'));
   
   switch ($event->type) {
       case 'payment_intent.succeeded':
           // Handle success
           break;
   }
   

   • Tip: Use Laravel’s stripe/webhooks package for built-in middleware.

4. Subscription Management

   $subscription = $stripe->subscriptions->create([
       'customer' => $customer->id,
       'items' => [['price' => 'price_123']],
   ]);
   

   • Tip: Use subscription_items for dynamic updates.

Integration Tips

• Laravel: Publish config with php artisan vendor:publish --tag=stripe-config.
• Testing: Use stripe-mock for local testing:

  stripe-mock
  

  Mock requests in tests:

  $this->mockStripe('customers/create', ['id' => 'cus_123']);
  

• Idempotency: Always use for critical operations (e.g., charges):

  $charge = \Stripe\Charge::create([...], ['idempotency_key' => 'unique_key']);
  

Gotchas and Tips

Pitfalls

1. TLS 1.2 Requirement

   • Error: invalid_request_error with TLS 1.0/1.1.
   • Fix: Upgrade PHP/cURL or force TLS 1.2:

     \Stripe\Stripe::setCABundlePath('/path/to/ca-bundle.crt');
     

     Or set cURL options:

     $curl = new \Stripe\HttpClient\CurlClient([CURLOPT_SSLVERSION => CURL_SSLVERSION_TLSv1_2]);
     \Stripe\ApiRequestor::setHttpClient($curl);
     

2. Legacy vs. Modern SDK

   • Issue: Mixing \Stripe\Customer::create() (legacy) with $stripe->customers->create() (modern).
   • Fix: Stick to one pattern per project. Use the migration guide.

3. Webhook Verification

   • Gotcha: Forgetting to verify signatures in production.
   • Fix: Always validate with Webhook::constructEvent() and use HTTP_STRIPE_SIGNATURE.

4. Rate Limits

   • Error: 429 Too Many Requests.
   • Fix: Implement exponential backoff or use Stripe::setMaxNetworkRetries(3).

5. Undocumented Fields

   • Workaround: Use rawRequest for beta features or undocumented endpoints:

     $response = $stripe->rawRequest('post', '/v1/beta_endpoint', [...]);
     

Debugging Tips

• Enable Logging:

  \Stripe\Stripe::setLogger(new \Monolog\Logger('stripe', [...]));
  

• Inspect Raw Responses:

  $customer = \Stripe\Customer::create([...]);
  $lastResponse = $customer->getLastResponse();
  print_r($lastResponse->headers); // Debug headers
  

• Test Locally: Use stripe-mock to avoid hitting live API during development.

Extension Points

1. Custom HTTP Client

   • Override timeouts, proxies, or add headers:

     $client = new \Stripe\HttpClient\CurlClient([
         CURLOPT_PROXY => 'http://proxy:8080',
         CURLOPT_TIMEOUT => 30,
     ]);
     \Stripe\ApiRequestor::setHttpClient($client);
     

2. Telemetry

   • Disable if privacy is a concern:

     \Stripe\Stripe::setEnableTelemetry(false);
     

3. Beta Features

   • Use -beta.X versions for public previews:

     composer require stripe/stripe-php:v15.0.0-beta.1
     

   • Enable with:

     \Stripe\Stripe::addBetaVersion('feature_beta', 'v3');
     

4. Laravel Service Provider

   • Bind StripeClient to the container:

     $this->app->singleton(\Stripe\StripeClient::class, function ($app) {
         return new \Stripe\StripeClient(config('services.stripe.key'));
     });
     

   • Inject into controllers:

     public function __construct(private \Stripe\StripeClient $stripe) {}