Stripe SDK PHP: integrazione base

L'SDK PHP ufficiale di Stripe (stripe-php) semplifica drasticamente l'integrazione dei pagamenti in applicazioni PHP. Supporta PHP 7.4+ e include tutte le funzionalità della Stripe API con tipizzazione e gestione errori robusta.

Installazione e setup

L'installazione avviene via Composer con 'composer require stripe/stripe-php'. Inizializza il client con Stripe::setApiKey(getenv('STRIPE_SECRET_KEY')); o, in versione orientata agli oggetti, new StripeClient. La libreria gestisce automaticamente retry, timeout (di default 80 secondi) e parse degli errori in eccezioni tipizzate.

Creazione PaymentIntent e webhook

Per accettare un pagamento crea un PaymentIntent lato server con amount, currency e customer, poi passa il client_secret al frontend per il completamento. La gestione webhook richiede di verificare la firma con Webhook::constructEvent usando l'endpoint signing secret. Tutti gli oggetti restituiti sono istanze di classi Stripe specifiche (PaymentIntent, Customer, ecc.) con accesso tramite proprietà magiche.

Laravel Cashier e Symfony Pay

Per Laravel esiste Cashier (laravel/cashier), pacchetto ufficiale che semplifica subscription, trial, swap plan, single charge, invoice download. Si integra con il modello User aggiungendo trait Billable e supporta nativamente Stripe Billing webhook. Per Symfony esiste l'ottimo paddle/symfony-bundle e Stripe-Bundle community-driven. Entrambi gestiscono auto-discovery webhook, encrypted column per Stripe customer ID, e helper come $user->subscribed('pro') che astrae la logica subscription. Riduce il boilerplate del 70-80% rispetto SDK puro.

Error handling completo PHP

L'SDK PHP solleva eccezioni tipizzate: \Stripe\Exception\CardException (carta rifiutata, includ decline code), RateLimitException (429, attendi e ritenta), InvalidRequestException (parametri errati, no retry utile), AuthenticationException (chiave invalida, alert ops), ApiConnectionException (timeout/network, ritenta), ApiException (5xx Stripe down). Wrappa ogni chiamata Stripe in try/catch multi-tipo: CardException si mostra al cliente con messaggio decline, le altre si loggano con Sentry/Bugsnag e si gestiscono con retry intelligente. Non mostrare mai stack trace al cliente finale.

Testing strategies con PHPUnit

Test integration Stripe in PHPUnit: 1) Mock dell'SDK con stripe-mock (binary ufficiale che simula API Stripe localmente su port 12111); 2) Unit test logica business con StripeClient mocked tramite reflection; 3) Integration test contro Sandbox Stripe (richiede internet, slower); 4) Webhook test con Stripe CLI trigger + assertion su DB state. Esempio mock: setApiBase('http://localhost:12111') in test bootstrap. stripe-mock supporta tutti gli endpoint con response realistici da spec OpenAPI. Permette TDD veloce senza dependency su API esterna.

Stripe CLI per sviluppo PHP

Stripe CLI accelera sviluppo PHP: 'stripe listen --forward-to localhost/webhook.php' inoltra eventi Live/Test a webhook locale. 'stripe trigger payment_intent.succeeded' genera evento test on-demand. 'stripe logs tail' streams API call real-time per debug. 'stripe products list' / 'create' permette CRUD da terminale senza Dashboard. Per CI/CD: stripe-cli in Docker container, trigger event automatici come parte di integration test suite. Integration con PHPStorm/VSCode per breakpoint debugging su webhook handler in arrivo.

Composer e versioning PHP

Best practice Composer per stripe/stripe-php: 1) Pin major version in composer.json (^13.0 invece di * o ^10.0); 2) composer.lock committed per build deterministic; 3) Update periodico controllato (composer outdated + review changelog); 4) Test integration esistente dopo update PRIMA di deploy production; 5) Use Composer Audit per security advisory check; 6) Separare dev dependency (stripe-mock per test) da prod. Composer Scripts utili: 'post-install-cmd': verifica versione PHP compatibile, generate IDE helper file per autocompletion. Per progetti enterprise PHP, considera Packagist Private per host repository internamente con cached release per resilience supply chain.

Stripe libraries community e ecosystem

Oltre l'SDK ufficiale, ecosystem PHP Stripe include: 1) Laravel Cashier (subscription gestita end-to-end); 2) Symfony StripeBundle (integration framework-native); 3) WordPress plugin WP Simple Pay, WooCommerce Stripe; 4) Drupal Stripe module; 5) Magento module Stripe Payments; 6) PrestaShop module Stripe ufficiale. Tutti basati su stripe-php sottostante. Maintained da community + Stripe partner ufficiali. Per progetti custom non basati su framework, l'SDK pure è scelta consigliata - mantieni controllo totale e debt tecnico minimo. Per progetti su framework standard, usa library framework-specific per accelerare sviluppo (save 60-70% boilerplate).

Procedura passo-passo

1. Esegui 'composer require stripe/stripe-php' nella root del progetto.
2. Crea un file .env con STRIPE_SECRET_KEY=sk_test_... e STRIPE_WEBHOOK_SECRET=whsec_...
3. Inizializza il client in bootstrap.php: \Stripe\Stripe::setApiKey(getenv('STRIPE_SECRET_KEY')).
4. Crea l'endpoint create-payment-intent.php che restituisce client_secret.
5. Lato frontend usa Stripe.js + Payment Element per confermare il pagamento.
6. Crea webhook.php che verifica firma con Webhook::constructEvent.
7. Gestisci payment_intent.succeeded aggiornando il DB ordine.
8. Testa con Stripe CLI: stripe listen --forward-to localhost/webhook.php.

Errori comuni e come risolverli

• API key in plain code: rischio fuga su Git; usa env variable e .env.dist.
• Mancata verifica firma webhook: endpoint vulnerabile; usa sempre constructEvent.
• Mancata gestione StripeException: errori 4xx/5xx non gestiti; wrappa chiamate in try/catch.
• Versione PHP obsoleta: stripe-php >= 13 richiede PHP 7.4+; aggiorna se necessario.

Domande frequenti

D: Quale versione PHP è richiesta?
R: PHP 7.4+ per l'ultima major version dell'SDK.

D: L'SDK supporta async?
R: Le chiamate sono sincrone; per async usa Guzzle promise o worker queue.

D: Posso usare l'SDK con Laravel/Symfony?
R: Sì, integrazione nativa; esistono anche pacchetti dedicati (cashier-stripe).

D: L'SDK fa retry automatico?
R: Sì, su errori di rete e 5xx con backoff esponenziale.

Hai bisogno di aiuto?

Se vuoi integrare Stripe con il team di G Tech Group, scrivici tramite il modulo di contatto.