Core Concepts

This section explains the fundamental concepts and architecture of the Stripe Bundle.

What You’ll Learn

  • The key entities and interfaces in the bundle
  • How the bundle integrates with Symfony, Doctrine, and API Platform
  • The event system used for communication between components
  • How data flows between your application, the bundle, and Stripe

Architecture Overview

The Stripe Bundle is designed with a focus on flexibility, extensibility, and separation of concerns. It provides a layer of abstraction over the Stripe API that integrates seamlessly with Symfony applications while allowing for customization to fit your specific needs.

Key Components

The bundle consists of several key components:

  1. Contracts (Interfaces): Define the data structures and behaviors that your application entities must implement
  2. Services: Provide the core functionality for interacting with Stripe
  3. Event System: Enables communication between components and with your application
  4. Webhooks: Process events from Stripe and update your application accordingly

Core Entities and Interfaces

The bundle defines several interfaces that your application entities should implement:

StripeUserInterface

Represents a user in your application who can be a Stripe customer. This interface extends Symfony’s UserInterface and adds methods for:

  • Managing the Stripe customer ID
  • Handling billing information
  • Tracking subscriptions
  • Managing credit balances

Your application’s User entity should implement this interface to integrate with Stripe.

SubscriptionPlanInterface

Represents a subscription plan that users can subscribe to. It includes:

  • Plan details (name, description)
  • Pricing information (amount, currency)
  • Billing interval (monthly, yearly)
  • Trial period settings
  • Stripe product and price IDs

Your application can define multiple subscription plans with different features and pricing.

SubscriptionInterface

Represents a user’s subscription to a plan. It tracks:

  • The user and plan associated with the subscription
  • Subscription status (active, canceled, etc.)
  • Important dates (start date, end date, trial end date)
  • The Stripe subscription ID

This interface allows your application to track which users are subscribed to which plans.

StripeInvoiceInterface

Represents an invoice generated by Stripe. It includes:

  • The user associated with the invoice
  • The subscription (if applicable)
  • Amount and currency
  • Status (paid, unpaid, etc.)
  • Important dates (invoice date, due date, paid date)

Your application can store basic invoice information locally while fetching detailed information from Stripe when needed.

CreditTransactionInterface

Represents a transaction for credits used in pay-per-action billing. It tracks:

  • The user associated with the transaction
  • The amount of credits (positive for purchases, negative for usage)
  • Transaction type (purchase, usage)
  • Reference information (description, reference ID)
  • Monetary amount and currency (if applicable)

This interface enables your application to implement a credit system for pay-per-action features.

Services

The bundle provides several services that handle the interaction with Stripe:

StripeClient

A wrapper around the Stripe PHP SDK that provides:

  • Error handling and logging
  • A simplified interface for executing Stripe API calls
  • Integration with Symfony’s logging system

CustomerService

Manages Stripe customers and their relationship with your application users:

  • Creates and updates customers in Stripe
  • Syncs customer data between your application and Stripe
  • Handles billing information and tax IDs

SubscriptionService

Manages subscriptions and checkout sessions:

  • Creates checkout sessions for subscription purchases
  • Syncs subscription data between your application and Stripe
  • Handles subscription cancellations and updates

InvoiceService

Manages invoices and payments:

  • Syncs invoice data between your application and Stripe
  • Handles invoice payments and refunds
  • Provides methods for retrieving invoice details

CreditService

Manages credits for pay-per-action billing:

  • Creates checkout sessions for credit purchases
  • Tracks credit usage and balances
  • Handles credit transactions

UsageService

Manages usage records for metered billing:

  • Records usage for pay-as-you-go features
  • Adds one-time charges to invoices
  • Retrieves usage history

WebhookHandler

Processes webhooks from Stripe:

  • Verifies webhook signatures
  • Dispatches events based on webhook type
  • Handles errors and logging

Event System

The bundle uses Symfony’s event dispatcher to communicate between components and with your application. Events are dispatched for various actions, such as:

  • Subscription created or updated
  • Invoice created or paid
  • Customer created or updated
  • Credit purchased or used

Your application can listen to these events to implement custom logic, such as:

  • Sending emails to users
  • Updating application state
  • Logging activity
  • Triggering additional processes

Data Flow

The bundle manages the flow of data between your application, the bundle, and Stripe:

Application → Bundle → Stripe

When your application needs to interact with Stripe (e.g., create a subscription), it:

  1. Calls a method on one of the bundle’s services
  2. The service prepares the data and makes the appropriate API call to Stripe
  3. Stripe processes the request and returns a response
  4. The service handles the response and updates your application entities

Stripe → Bundle → Application

When Stripe needs to notify your application of an event (e.g., payment succeeded), it:

  1. Sends a webhook to your application’s webhook endpoint
  2. The WebhookHandler verifies the webhook and creates an event
  3. The event is dispatched to listeners in your application
  4. Your application updates its state based on the event

Integration Patterns

The bundle uses several patterns to integrate with your application:

Contract-Based Integration

The bundle defines interfaces that your application entities must implement. This allows the bundle to work with your entities without knowing their specific implementation details.

Event-Based Communication

The bundle dispatches events that your application can listen to. This allows your application to react to changes in Stripe without tight coupling to the bundle.

Symfony Integration

The bundle integrates with Symfony’s dependency injection, event dispatcher, and HTTP components to provide a seamless experience within your Symfony application.

Doctrine Integration

The bundle provides interfaces for entities that can be implemented in your Doctrine entities, allowing for easy persistence of Stripe-related data.

API Platform Integration

The bundle can expose Stripe-related resources through API Platform, allowing for easy creation of APIs for your frontend applications.

Payment Flows

The bundle supports several payment flows:

Subscription-Based Billing

Users subscribe to plans and are billed regularly (monthly, yearly, etc.). The bundle handles:

  • Creating checkout sessions for subscription purchases
  • Processing subscription webhooks
  • Tracking subscription status and renewal dates
  • Managing trial periods

Pay-Per-Action Billing

Users are billed based on their usage of specific features. The bundle supports two approaches:

  1. Credit-Based: Users purchase credits that they can spend on actions
  2. Metered Billing: Usage is tracked and billed at the end of the billing period

Direct Checkout

Users are redirected to Stripe Checkout for payment, providing a secure and user-friendly payment experience. The bundle handles:

  • Creating checkout sessions with the appropriate products and prices
  • Processing successful payment webhooks
  • Updating your application based on payment status

Copyright © 2025 Tomedio. Distributed under an MIT license.