PHPackages                             monkeyscloud/monkeyslegion-stripe - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [PSR & Standards](/categories/psr-standards)
4. /
5. monkeyscloud/monkeyslegion-stripe

ActiveLibrary[PSR & Standards](/categories/psr-standards)

monkeyscloud/monkeyslegion-stripe
=================================

First-class Stripe integration package for the MonkeysLegion framework.

1.0.4(5mo ago)035MITPHPPHP ^8.4CI failing

Since Aug 3Pushed 5mo agoCompare

[ Source](https://github.com/MonkeysCloud/MonkeysLegion-Stripe)[ Packagist](https://packagist.org/packages/monkeyscloud/monkeyslegion-stripe)[ RSS](/packages/monkeyscloud-monkeyslegion-stripe/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (7)Versions (7)Used By (0)

MonkeysLegion Stripe Integration
================================

[](#monkeyslegion-stripe-integration)

[![PHP Version](https://camo.githubusercontent.com/2aed50cc19486e0407775311c22f530383b2791ca08b8c9583ebb80cb5e364e7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e342532422d626c75652e737667)](https://php.net)[![License](https://camo.githubusercontent.com/8bb50fd2278f18fc326bf71f6e88ca8f884f72f179d3e555e20ed30157190d0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e2e737667)](LICENSE)

First-class Stripe integration package for the MonkeysLegion PHP framework, providing PSR-compliant HTTP clients and service container integration.

📋 What You'll Learn
-------------------

[](#-what-youll-learn)

This documentation covers everything you need to integrate Stripe payments into your MonkeysLegion application:

- **🚀 Quick Start**: Get up and running in minutes with automated setup
- **🔧 Configuration**: Environment variables, key management, and security setup
- **🔑 Key Management**: Interactive CLI tools for managing Stripe API keys and webhook secrets
- **📋 Service Registration**: Dependency injection setup with MonkeysLegion DI container
- **💳 Payment Operations**: Complete API for payment intents, checkout sessions, subscriptions, and products
- **🔄 Test/Live Mode**: Seamless switching between test and production environments
- **🪝 Webhook Handling**: Secure webhook processing with signature verification and idempotency
- **📊 Logging**: PSR-3 compatible logging with Monolog integration
- **🛡️ Security**: Payload validation, size limits, and secure key storage

Documentation
-------------

[](#documentation)

All usage, configuration, and API references can be found in the [official Monkeys Legion Stripe package documentation](https://monkeyslegion.com/docs/packages/stripe).

🚀 Quick Start
-------------

[](#-quick-start)

```
# Install the package
composer require monkeyscloud/monkeyslegion-stripe

# Publish the configuration file
php vendor/bin/ml stripe:install

# Set up your Stripe keys interactively
php vendor/bin/key-helper set

# Validate your configuration
php vendor/bin/key-helper validate

# Test webhook signature verification
php vendor/bin/key-helper webhook:test
```

Features
--------

[](#features)

- **PSR-Compliant**: Built with PSR standards for maximum compatibility
- **Service Container Integration**: Automatic dependency injection
- **Configuration Management**: Environment-based configuration with merging support
- **HTTP Client Abstraction**: PSR-18 HTTP client implementation
- **Key Management**: Built-in tools for managing Stripe API keys and webhook secrets
- **Webhook Testing**: Comprehensive webhook signature validation testing
- **Environment Awareness**: Supports `.env.` files for `dev`, `prod`, and `test` environments

Requirements
------------

[](#requirements)

- PHP 8.4 or higher
- MonkeysLegion Core ^1.0
- MonkeysLegion DI ^1.0 (`composer require monkeyscloud/monkeyslegion-di`)
- Stripe PHP SDK ^17.3

Environment Awareness
---------------------

[](#environment-awareness)

The package supports environment-specific configurations using `.env.` files. By default, the `dev` environment is used. You can specify the environment using the `--stage` flag.

### Example

[](#example)

```
# Use the dev environment (default)
php vendor/bin/key-helper validate

# Use the test environment
php vendor/bin/key-helper --stage=test validate

# Use the production environment
php vendor/bin/key-helper --stage=prod validate
```

The `.env.` file will be used based on the specified stage.

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require monkeyscloud/monkeyslegion-stripe
```

Configuration
-------------

[](#configuration)

### Publish Configuration File

[](#publish-configuration-file)

Publish the configuration file to your project:

```
php vendor/monkeyscloud/monkeyslegion-stripe/publish.php
```

### Environment Variables

[](#environment-variables)

Configure your Stripe settings using the following environment variables:

```
# Essential Stripe API keys (managed by key-helper)
STRIPE_SECRET_KEY=sk_test_...            # Main secret key for backend API calls
STRIPE_PUBLISHABLE_KEY=pk_test_...       # Public key for frontend Stripe.js
STRIPE_WEBHOOK_SECRET=whsec_...          # Webhook secret for production/main environment
STRIPE_TEST_KEY=sk_test_...              # Additional test secret key
STRIPE_WEBHOOK_SECRET_TEST=whsec_...     # Webhook secret specifically for test mode

# Optional Stripe API configuration (not validated by key-helper)
STRIPE_API_VERSION=2025-04-30            # Stripe API version your code expects
STRIPE_CURRENCY=usd                      # Default currency for transactions
STRIPE_CURRENCY_LIMIT=100000             # Maximum transaction amount in cents

# Optional webhook configuration
STRIPE_WEBHOOK_TOLERANCE=20              # Time tolerance for webhook signature validation (seconds)
STRIPE_WEBHOOK_DEFAULT_TTL=172800        # Default time-to-live for webhook events (seconds)
STRIPE_MAX_PAYLOAD_SIZE=131072           # Maximum webhook payload size in bytes (default: 128KB)

# Optional idempotency configuration
STRIPE_IDEMPOTENCY_TABLE=stripe_memory   # Database table for storing idempotency events

# Optional API request configuration
STRIPE_TIMEOUT=60                        # Timeout for API requests (seconds)
STRIPE_WEBHOOK_RETRIES=3                 # Maximum number of retries for failed webhook events

# Optional Stripe API endpoint
STRIPE_API_URL=https://api.stripe.com    # Stripe API base URL
```

**Note**: The key-helper utility validates only the essential Stripe keys. Additional configuration variables can be added manually to your `.env` files as needed.

### Configuration Structure

[](#configuration-structure)

The configuration file supports the following options:

```
return [
    'secret_key'      => getenv('STRIPE_SECRET_KEY') ?: '',
    'publishable_key' => getenv('STRIPE_PUBLISHABLE_KEY') ?: '',
    'webhook_secret'  => getenv('STRIPE_WEBHOOK_SECRET') ?: '',
    'test_key'        => getenv('STRIPE_TEST_KEY') ?: '',
    'api_version'     => getenv('STRIPE_API_VERSION') ?: '2025-04-30',
    'currency'        => getenv('STRIPE_CURRENCY') ?: 'usd',
    'currency_limit'  => (int)(getenv('STRIPE_CURRENCY_LIMIT') ?: 100000),
    'webhook_tolerance' => (int)(getenv('STRIPE_WEBHOOK_TOLERANCE') ?: 20),
    'webhook_default_ttl' => (int)(getenv('STRIPE_WEBHOOK_DEFAULT_TTL') ?: 172800),
    'idempotency_table' => getenv('STRIPE_IDEMPOTENCY_TABLE') ?: 'stripe_memory',
    'timeout'         => (int)(getenv('STRIPE_TIMEOUT') ?: 60),
    'webhook_retries' => (int)(getenv('STRIPE_WEBHOOK_RETRIES') ?: 3),
    'api_url'         => getenv('STRIPE_API_URL') ?: 'https://api.stripe.com',
];
```

Key Management
--------------

[](#key-management)

The package includes a comprehensive key management utility for generating, validating, and managing Stripe API keys and webhook secrets. All operations are performed through the command line interface.

### Key-Helper Features

[](#key-helper-features)

- **Environment-Aware**: Works with `.env.dev`, `.env.prod`, `.env.test` files
- **Secure Key Generation**: Uses cryptographically secure random bytes
- **Format Validation**: Validates Stripe key formats and structures
- **Interactive Setup**: Guided setup for all essential Stripe keys
- **Key Rotation**: Safe rotation of existing keys with backup
- **Webhook Testing**: Live webhook secret validation with Stripe SDK
- **Batch Operations**: Validate all keys at once or individually

### Command Reference

[](#command-reference)

```
php vendor/bin/key-helper [--stage=dev|prod|test] [COMMAND] [OPTIONS]

Available Commands:
  generate [KEY_TYPE]          # Generate and save a new key (default: STRIPE_SECRET_KEY)
  set [KEY_NAME] [VALUE]       # Set a specific key or enter interactive mode
  rotate [KEY_TYPE]            # Rotate (replace) an existing key with backup
  validate [KEY_TYPE]          # Validate keys (all if no type specified)
  show [KEY_TYPE]              # Display current key value
  list                         # List all Stripe/webhook keys in environment
  webhook:test                 # Test webhook secret validation with simulated payload

Available Key Types:
  secret                       # STRIPE_SECRET_KEY
  test                         # STRIPE_TEST_KEY
  publishable                  # STRIPE_PUBLISHABLE_KEY
  webhook                      # STRIPE_WEBHOOK_SECRET
  webhook_test                 # STRIPE_WEBHOOK_SECRET_TEST

Stage Options:
  --stage=dev                  # Use .env.dev file (default)
  --stage=prod                 # Use .env.prod file
  --stage=test                 # Use .env.test file
```

### Environment-Specific Key Management

[](#environment-specific-key-management)

The `--stage` flag allows you to manage keys for specific environments (`dev`, `prod`, `test`).

#### Example

[](#example-1)

```
# Set keys for the test environment
php vendor/bin/key-helper --stage=test set

# Validate keys for the production environment
php vendor/bin/key-helper --stage=prod validate

# Generate a new key for the dev environment
php vendor/bin/key-helper --stage=dev generate
```

The `.env.` file will be updated or validated based on the specified stage.

**Default behavior without stage flag**: Uses `.env.dev` file

### Generate New Keys

[](#generate-new-keys)

#### Generate Default Secret Key

[](#generate-default-secret-key)

```
# Generates STRIPE_SECRET_KEY (sk_test_* format)
php vendor/bin/key-helper generate
```

#### Generate Specific Key Types

[](#generate-specific-key-types)

```
# Generate webhook secret placeholder
php vendor/bin/key-helper generate webhook

# Generate secret key placeholder
php vendor/bin/key-helper generate secret

# Generate publishable key placeholder
php vendor/bin/key-helper generate publishable

# Generate test webhook secret
php vendor/bin/key-helper generate webhook_test
```

### Rotate Keys

[](#rotate-keys)

#### Rotate Security Keys

[](#rotate-security-keys)

```
# Rotate secret keys with new generated values
php vendor/bin/key-helper rotate secret
php vendor/bin/key-helper rotate webhook
php vendor/bin/key-helper rotate publishable
php vendor/bin/key-helper rotate webhook_test
```

#### Environment-Specific Rotation

[](#environment-specific-rotation)

```
# Rotate production keys
php vendor/bin/key-helper --stage=prod rotate secret
php vendor/bin/key-helper --stage=prod rotate webhook

# Rotate test environment keys
php vendor/bin/key-helper --stage=test rotate webhook
```

### Set Keys

[](#set-keys)

#### Set Individual Keys

[](#set-individual-keys)

```
# Set a specific key value
php vendor/bin/key-helper set STRIPE_SECRET_KEY sk_test_your_key_here

# Set webhook secret
php vendor/bin/key-helper set STRIPE_WEBHOOK_SECRET whsec_your_secret_here
```

#### Interactive Setup Mode

[](#interactive-setup-mode)

```
# Enter interactive mode to set all Stripe keys
php vendor/bin/key-helper set

# Interactive prompts for:
# - STRIPE_PUBLISHABLE_KEY
# - STRIPE_SECRET_KEY
# - STRIPE_TEST_KEY
# - STRIPE_WEBHOOK_SECRET
# - STRIPE_WEBHOOK_SECRET_TEST
# - STRIPE_API_VERSION
# Press Enter to skip any key
```

### Validate Keys

[](#validate-keys)

#### Validate All Keys

[](#validate-all-keys)

```
# Validates all Stripe keys and shows comprehensive status
php vendor/bin/key-helper validate

# Example output:
# ✅ STRIPE_SECRET_KEY (secret): VALID
# ✅ STRIPE_PUBLISHABLE_KEY (publishable): VALID
# ⚠️  STRIPE_WEBHOOK_SECRET (webhook): NOT SET
# ✅ STRIPE_WEBHOOK_SECRET_TEST (webhook_test): VALID
```

#### Validate Specific Keys

[](#validate-specific-keys)

```
# Validate individual key types
php vendor/bin/key-helper validate secret
php vendor/bin/key-helper validate webhook
php vendor/bin/key-helper validate webhook_test
```

#### Validate Keys for a Specific Environment

[](#validate-keys-for-a-specific-environment)

```
# Validate keys for the test environment
php vendor/bin/key-helper --stage=test validate

# Validate specific key in production
php vendor/bin/key-helper --stage=prod validate secret
```

### Advanced Key Management

[](#advanced-key-management)

#### Show Current Key Values

[](#show-current-key-values)

```
# Display current key values
php vendor/bin/key-helper show secret
php vendor/bin/key-helper show webhook
php vendor/bin/key-helper show webhook_test

# Show keys for specific environment
php vendor/bin/key-helper --stage=prod show secret
```

#### List All Configuration Keys

[](#list-all-configuration-keys)

```
# List all STRIPE and WEBHOOK keys
php vendor/bin/key-helper list

# Example output:
# STRIPE and WEBHOOK keys found:
#   STRIPE_SECRET_KEY = sk_test_...
#   STRIPE_PUBLISHABLE_KEY = pk_test_...
#   STRIPE_WEBHOOK_SECRET = whsec_...
#   STRIPE_WEBHOOK_SECRET_TEST = whsec_...
```

#### Webhook Secret Testing

[](#webhook-secret-testing)

```
# Test webhook secret validation with simulated Stripe payload
php vendor/bin/key-helper webhook:test

# Example output:
# Testing webhook secret validation...
# ✅ Webhook secret validation: VALID
# HTTP Status: 200 OK
# Process Time: 15.42ms
# Event Type: payment_intent.succeeded
```

### Key Validation Features

[](#key-validation-features)

The key-helper validates different types of keys with specific format requirements:

#### Supported Validation Types

[](#supported-validation-types)

- **Stripe Secret Keys**: `sk_test_*` or `sk_live_*` format, minimum 20 characters
- **Stripe Publishable Keys**: `pk_test_*` or `pk_live_*` format, minimum 20 characters
- **Webhook Secrets**: `whsec_*` format, minimum 7 characters
- **Generated Keys**: 64-character hexadecimal strings for app keys
- **Placeholder Validation**: Accepts partial keys ending with `...` for development

#### Error Handling

[](#error-handling)

```
# Example validation errors:
# ❌ STRIPE_SECRET_KEY (secret): INVALID
# ⚠️  STRIPE_WEBHOOK_SECRET (webhook): NOT SET
# ✅ STRIPE_PUBLISHABLE_KEY (publishable): VALID
```

### Environment File Management

[](#environment-file-management)

The key-helper safely manages environment files with these features:

#### File Safety

[](#file-safety)

- **Atomic Operations**: All file operations are atomic to prevent corruption
- **Backup on Rotation**: Old keys are displayed before replacement
- **Comment Preservation**: Comments in `.env` files are preserved during updates
- **Directory Creation**: Automatically creates directories if they don't exist

#### Multi-Environment Support

[](#multi-environment-support)

- **Stage-Specific Files**: Supports `.env.dev`, `.env.prod`, `.env.test`
- **Environment Isolation**: Each environment has separate key management
- **Consistent Interface**: Same commands work across all environments

#### Key Generation Security

[](#key-generation-security)

- **Cryptographically Secure**: Uses PHP's `random_bytes()` for key generation
- **Appropriate Formats**: Generates keys in correct Stripe format (sk\_test\_, pk\_test\_, whsec\_)
- **Configurable Length**: Supports different key lengths for different purposes

Service Registration
--------------------

[](#service-registration)

### Registration

[](#registration)

(In Your app.php)

register the service provider by: Install DI package via Composer:

```
composer require monkeyscloud/monkeyslegion-stripe
```php
use MonkeysLegion\DI\ContainerBuilder;
use MonkeysLegion\Stripe\Provider\StripeServiceProvider;

// Create a new container builder instance
$containerBuilder = new ContainerBuilder();

// Register the Stripe service provider
StripeServiceProvider::register($containerBuilder);

// Build the container
$container = $containerBuilder->build();

// Globalize it
define('ML_CONTAINER', $container);

// Get Stripe services using class names
$stripeClient = ML_CONTAINER->get(\Stripe\StripeClient::class);
$stripeGateway = ML_CONTAINER->get(\MonkeysLegion\Stripe\Client\StripeGateway::class);
$checkoutSession = ML_CONTAINER->get(\MonkeysLegion\Stripe\Client\CheckoutSession::class);
$subscription = ML_CONTAINER->get(\MonkeysLegion\Stripe\Client\Subscription::class);
$product = ML_CONTAINER->get(\MonkeysLegion\Stripe\Client\Product::class);
$setupIntentService = ML_CONTAINER->get(\MonkeysLegion\Stripe\Client\SetupIntentService::class);
$webhookController = ML_CONTAINER->get(\MonkeysLegion\Stripe\Webhook\WebhookController::class);
```

### Test Mode Management

[](#test-mode-management)

All client services support switching between test and live modes:

```
// Switch to test mode (default)
$stripeGateway->setTestMode(true);      // Uses STRIPE_TEST_KEY
$checkoutSession->setTestMode(true);    // Uses STRIPE_TEST_KEY
$subscription->setTestMode(true);       // Uses STRIPE_TEST_KEY

// Switch to live mode for production
$stripeGateway->setTestMode(false);     // Uses STRIPE_SECRET_KEY
$checkoutSession->setTestMode(false);   // Uses STRIPE_SECRET_KEY
$subscription->setTestMode(false);      // Uses STRIPE_SECRET_KEY

// You may use this approach if you prefer
$isProduction = ($_ENV['APP_ENV'] ?? 'dev') === 'prod';
$stripeGateway->setTestMode(!$isProduction);
```

Usage
-----

[](#usage)

### Payment Intent Operations

[](#payment-intent-operations)

```
// Get the gateway service
$stripeGateway = $container->get(\MonkeysLegion\Stripe\Client\StripeGateway::class);

// Create a payment intent
$paymentIntent = $stripeGateway->createPaymentIntent(
    2000,        // amount in cents
    'usd',       // currency
    true         // enable automatic payment methods
);

// Retrieve a payment intent
$paymentIntent = $stripeGateway->retrievePaymentIntent('pi_1234567890');

// Confirm a payment intent
$confirmedPayment = $stripeGateway->confirmPaymentIntent('pi_1234567890', [
    'payment_method' => 'pm_card_visa'
]);

// Cancel a payment intent
$cancelledPayment = $stripeGateway->cancelPaymentIntent('pi_1234567890');

// Capture a payment intent (for manual capture)
$capturedPayment = $stripeGateway->capturePaymentIntent('pi_1234567890');

// Refund a payment intent
$refund = $stripeGateway->refundPaymentIntent('pi_1234567890', [
    'amount' => 1000  // partial refund
]);

// Update a payment intent
$updatedPayment = $stripeGateway->updatePaymentIntent('pi_1234567890', [
    'description' => 'Updated payment description'
]);

// List payment intents
$paymentIntents = $stripeGateway->listPaymentIntent([
    'limit' => 10,
    'customer' => 'cus_1234567890'
]);

// Search payment intents
$searchResults = $stripeGateway->searchPaymentIntent([
    'query' => 'status:\'succeeded\' AND metadata[\'order_id\']:\'12345\''
]);

// Increment authorization
$incrementedPayment = $stripeGateway->incrementAuthorization('pi_1234567890', 500);

// Check if payment intent is valid
$isValid = $stripeGateway->isValidPaymentIntent('pi_1234567890');
```

### Checkout Session Operations

[](#checkout-session-operations)

```
// Get the checkout service
$checkoutSession = $container->get(\MonkeysLegion\Stripe\Client\CheckoutSession::class);

// Create a checkout session
$session = $checkoutSession->createCheckoutSession([
    'mode' => 'payment',
    'line_items' => [
        [
            'price_data' => [
                'currency' => 'usd',
                'product_data' => [
                    'name' => 'Premium Plan'
                ],
                'unit_amount' => 2000,
            ],
            'quantity' => 1,
        ],
    ],
    'success_url' => 'https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
    'cancel_url' => 'https://example.com/cancel',
]);

// Retrieve a checkout session
$session = $checkoutSession->retrieveCheckoutSession('cs_1234567890');

// List checkout sessions
$sessions = $checkoutSession->listCheckoutSessions([
    'limit' => 10
]);

// Expire a checkout session
$expiredSession = $checkoutSession->expireCheckoutSession('cs_1234567890');

// List line items from a session
$lineItems = $checkoutSession->listLineItems('cs_1234567890');

// Get checkout URL directly
$checkoutUrl = $checkoutSession->getCheckoutUrl([
    'mode' => 'payment',
    'line_items' => [/* ... */],
    'success_url' => 'https://example.com/success',
    'cancel_url' => 'https://example.com/cancel',
]);

// Validate checkout session
$isValid = $checkoutSession->isValidCheckoutSession('cs_1234567890');

// Check if session is expired
$isExpired = $checkoutSession->isExpiredCheckoutSession('cs_1234567890');
```

### Subscription Operations

[](#subscription-operations)

```
// Get the subscription service
$subscription = $container->get(\MonkeysLegion\Stripe\Client\Subscription::class);

// Create a subscription
$newSubscription = $subscription->createSubscription(
    'cus_1234567890',  // customer ID
    'price_1234567890', // price ID
    [
        'trial_period_days' => 7,
        'metadata' => ['plan' => 'premium']
    ]
);

// Retrieve a subscription
$subscription = $subscription->retrieveSubscription('sub_1234567890');

// Update a subscription
$updatedSubscription = $subscription->updateSubscription('sub_1234567890', [
    'metadata' => ['updated' => 'true'],
    'proration_behavior' => 'create_prorations'
]);

// Cancel a subscription
$cancelledSubscription = $subscription->cancelSubscription('sub_1234567890', [
    'at_period_end' => true
]);

// List customer subscriptions
$subscriptions = $subscription->listSubscriptions('cus_1234567890', [
    'status' => 'active',
    'limit' => 10
]);

// Resume a subscription
$resumedSubscription = $subscription->resumeSubscription('sub_1234567890');

// Search subscriptions
$searchResults = $subscription->searchSubscriptions([
    'query' => 'status:\'active\' AND metadata[\'plan\']:\'premium\''
]);
```

### Product Operations

[](#product-operations)

```
// Get the product service
$product = $container->get(\MonkeysLegion\Stripe\Client\Product::class);

// Create a product
$newProduct = $product->createProduct([
    'name' => 'Premium Software License',
    'description' => 'Annual software license with premium features',
    'metadata' => ['category' => 'software']
]);

// Retrieve a product
$product = $product->retrieveProduct('prod_1234567890');

// Update a product
$updatedProduct = $product->updateProduct('prod_1234567890', [
    'name' => 'Updated Premium License',
    'description' => 'Updated description'
]);

// Delete a product
$deletedProduct = $product->deleteProduct('prod_1234567890');

// List products
$products = $product->listProducts([
    'active' => true,
    'limit' => 10
]);

// Search products
$searchResults = $product->searchProducts(
    'metadata[\'category\']:\'software\'',
    ['limit' => 20]
);
```

### Setup Intent Operations

[](#setup-intent-operations)

```
// Get the setup intent service
$setupIntentService = $container->get(\MonkeysLegion\Stripe\Client\SetupIntentService::class);

// Create a setup intent
$setupIntent = $setupIntentService->createSetupIntent([
    'customer' => 'cus_1234567890',
    'payment_method_types' => ['card'],
    'usage' => 'off_session'
]);

// Retrieve a setup intent
$setupIntent = $setupIntentService->retrieveSetupIntent('seti_1234567890');

// Confirm a setup intent
$confirmedSetupIntent = $setupIntentService->confirmSetupIntent('seti_1234567890', [
    'payment_method' => 'pm_card_visa'
]);

// Cancel a setup intent
$cancelledSetupIntent = $setupIntentService->cancelSetupIntent('seti_1234567890');

// Update a setup intent
$updatedSetupIntent = $setupIntentService->updateSetupIntent('seti_1234567890', [
    'metadata' => ['updated' => 'true']
]);

// List setup intents
$setupIntents = $setupIntentService->listSetupIntents([
    'customer' => 'cus_1234567890',
    'limit' => 10
]);

// Validate setup intent
$isValid = $setupIntentService->isValidSetupIntent('seti_1234567890');
```

### Webhook Handling

[](#webhook-handling)

### Setting Up Webhooks

[](#setting-up-webhooks)

1. **Configure Webhook Secret**```
    # Set your webhook secret from Stripe Dashboard
    php vendor/bin/key-helper set STRIPE_WEBHOOK_SECRET whsec_your_secret_here

    # Verify it's configured correctly
    php vendor/bin/key-helper webhook:test
    ```

```
// Get the webhook controller
$webhookController = ML_CONTAINER->get(\MonkeysLegion\Stripe\Webhook\WebhookController::class);

// Handle incoming webhook
$payload = file_get_contents('php://input');
$sigHeader = $_SERVER['HTTP_STRIPE_SIGNATURE'] ?? '';

$result = $webhookController->handle($payload, $sigHeader, function($event) {
    return ['status' => 'success', 'event' => $event['type']];
});

// Complete webhook endpoint example
function handleWebhook() {
    // This should be at your app.php
    $containerBuilder = new ContainerBuilder();
    StripeServiceProvider::register($containerBuilder);
    $container = $containerBuilder->build();
    define('ML_CONTAINER', $container);

    //
    $webhookController = ML_CONTAINER->get(\MonkeysLegion\Stripe\Webhook\WebhookController::class);

    $payload = file_get_contents('php://input');
    $sigHeader = $_SERVER['HTTP_STRIPE_SIGNATURE'] ?? '';

    try {
        $result = $webhookController->handle($payload, $sigHeader, function ($event) {
            // Your event handling logic here
            return processStripeEvent($event);
        });

        http_response_code(200);
        echo json_encode($result);
    } catch (\Throwable $e) {
        $code = $e->getCode();

        // Ensure we don't return invalid HTTP codes
        if ($code < 100 || $code >= 600) $code = 500

        http_response_code($code);
        echo json_encode(['error' => $e->getMessage()]);
    }
}
```

```
// Production mode (APP_ENV=prod):
// - Retries: Rate limits, API connection errors, server errors (5xx)
// - No Retry: Card errors, invalid requests, authentication errors
// - Uses exponential backoff: 60s, 120s, 180s

// Development mode (APP_ENV=dev):
// - No retries for any errors (fail fast for debugging)
// - Immediate error reporting
```

This package provides also a robust webhook handling system that securely processes Stripe events while preventing duplicate processing.

### Environment-Aware Storage

[](#environment-aware-storage)

The package automatically selects the appropriate storage backend for webhook idempotency based on your `APP_ENV` environment variable:

- **Development** (`dev`, default): **InMemoryStore** - Fast, no persistence needed for development
- **Testing** (`test`, `testing`): **SQLiteStore** - Persistent but lightweight SQLite database for testing
- **Production** (`prod`, `production`): **MySQLStore** - Robust, scalable MySQL database storage

```
# Set your environment in .env file
APP_ENV=dev      # Uses InMemoryStore
APP_ENV=test     # Uses SQLiteStore
APP_ENV=prod     # Uses MySQLStore (requires database configuration)
```

### Production Mode Features

[](#production-mode-features)

In production mode (`APP_ENV=prod`), the webhook system provides additional robustness:

- **Automatic Retries**: Retries transient errors (rate limits, API connection issues) with exponential backoff
- **MySQL Storage**: Persistent storage for webhook idempotency across server restarts
- **Enhanced Logging**: Detailed error logging and retry attempts
- **Timeout Handling**: Process forking with timeout enforcement (Linux/Unix only)

### Error Handling &amp; Retry Logic

[](#error-handling--retry-logic)

The webhook controller implements intelligent error handling based on the environment:

### Storage Implementation Details

[](#storage-implementation-details)

#### InMemoryStore (Development)

[](#inmemorystore-development)

- Pure PHP array storage
- No persistence between requests
- Automatic TTL-based cleanup
- Zero configuration required

#### SQLiteStore (Testing)

[](#sqlitestore-testing)

- Lightweight file-based database
- Persists across requests
- Creates database file automatically
- Default location: system temp directory

#### MySQLStore (Production)

[](#mysqlstore-production)

- Full database persistence
- Requires `QueryBuilder` and `Connection`
- Uses configurable table name (`idempotency_store`)
- Supports clustering and high availability

### Database Schema

[](#database-schema)

For production MySQL storage, the following table is required:

```
CREATE TABLE idempotency_store (
    id INT AUTO_INCREMENT PRIMARY KEY,
    event_id VARCHAR(255) UNIQUE NOT NULL,
    processed_at DATETIME NOT NULL,
    expiry DATETIME NULL,
    data JSON NULL,
    INDEX idx_event_id (event_id),
    INDEX idx_expiry (expiry)
);
```

### Configuring Webhook Processing

[](#configuring-webhook-processing)

You can customize webhook processing behavior through environment variables:

```
# Webhook processing configuration
STRIPE_TIMEOUT=60                    # Timeout for webhook processing (seconds)
STRIPE_WEBHOOK_RETRIES=3             # Maximum retry attempts (production only)
STRIPE_WEBHOOK_TOLERANCE=20          # Signature timestamp tolerance (seconds)
STRIPE_WEBHOOK_DEFAULT_TTL=172800    # Event storage TTL (48 hours in seconds)
```

### Configuring Expiration

[](#configuring-expiration)

By default, processed events are stored for 48 hours. You can customize this:

```
// In your app configuration
return [
    'webhook_default_ttl' => 86400, // 24 hours (in seconds)    // ...other config
];
```

PSR-3 Logger Integration
------------------------

[](#psr-3-logger-integration)

The package includes built-in PSR-3 logger support for comprehensive logging of Stripe operations and webhook processing.

### Default Logger Behavior

[](#default-logger-behavior)

By default, the package uses an internal Logger class that supports PSR-3 LoggerInterface. The logging behavior adapts to your environment:

- **Development** (`APP_ENV=dev`): Debug level messages
- **Testing** (`APP_ENV=test`): Notice level messages
- **Production** (`APP_ENV=prod`): Warning level messages

### Logger Features

[](#logger-features)

- **Structured Logging**: Includes context data like request IDs, error codes, and retry counts
- **Environment-Aware**: Automatically adjusts log levels based on APP\_ENV
- **Operation Tracking**: Logs all Stripe API calls, webhook processing, and error handling
- **Security**: Sensitive data like API keys are never logged

### Webhook Payload Size Limits

[](#webhook-payload-size-limits)

For security, webhook payloads are limited to a maximum size to prevent memory exhaustion attacks:

- **Default Size Limit**: 128KB (131,072 bytes)
- **Environment Variable**: `STRIPE_MAX_PAYLOAD_SIZE=131072`
- **Automatic Validation**: Payloads exceeding the limit are rejected with detailed logging

```
# Configure webhook payload size limit
STRIPE_MAX_PAYLOAD_SIZE=131072  # 128KB (default)
STRIPE_MAX_PAYLOAD_SIZE=262144  # 256KB (custom)
```

The payload validation includes:

- Size limit checking
- JSON format validation
- Empty payload detection
- Detailed error logging for debugging

###  Health Score

39

—

LowBetter than 85% of packages

Maintenance75

Regular maintenance activity

Popularity7

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity57

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 73% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~27 days

Total

5

Last Release

170d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/51e4df19377776baa8eafb605d9e7d2374b855c686f552c20d6856e94e3597c3?d=identicon)[yorchperaza](/maintainers/yorchperaza)

---

Top Contributors

[![Amanar-Marouane](https://avatars.githubusercontent.com/u/155680356?v=4)](https://github.com/Amanar-Marouane "Amanar-Marouane (54 commits)")[![yorchperaza](https://avatars.githubusercontent.com/u/2913369?v=4)](https://github.com/yorchperaza "yorchperaza (20 commits)")

---

Tags

psrstripebillingpaymentsubscriptionscheckoutmonkeyslegion

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/monkeyscloud-monkeyslegion-stripe/health.svg)

```
[![Health](https://phpackages.com/badges/monkeyscloud-monkeyslegion-stripe/health.svg)](https://phpackages.com/packages/monkeyscloud-monkeyslegion-stripe)
```

###  Alternatives

[laravel/cashier

Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services.

2.5k25.9M106](/packages/laravel-cashier)[checkout/checkout-sdk-php

Checkout.com SDK for PHP

553.3M7](/packages/checkout-checkout-sdk-php)[enupal/stripe

Allows customers sign up for recurring and one-time payments with Stripe, perfect for orders, donations, subscriptions, and events. Create simple payment forms in seconds easily without coding. For Craft CMS 3.x

3416.5k1](/packages/enupal-stripe)[payum/stripe

The Payum extension. It provides Stripe payment integration.

22573.1k3](/packages/payum-stripe)[sebdesign/laravel-viva-payments

A Laravel package for integrating the Viva Payments gateway

4845.9k](/packages/sebdesign-laravel-viva-payments)[flux-se/sylius-stripe-plugin

Sylius Stripe plugin using Payment Request

1029.3k](/packages/flux-se-sylius-stripe-plugin)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)