Download the PHP package petersowah/laravel-cashier-revenue-cat without Composer

Laravel Cashier RevenueCat

A Laravel Cashier driver for RevenueCat, providing seamless integration with RevenueCat's subscription management platform for iOS and Android apps.

Features

• Easy integration with RevenueCat's API V2
• Webhook handling for subscription events
• Support for both iOS and Android subscriptions
• Secure webhook signature verification
• Event-driven architecture for subscription management
• Support for entitlements management
• Support for non-subscription purchases
• Caching support for API responses
• Comprehensive logging and error handling
• Automatic retry mechanism for failed API calls

Installation

You can install the package via composer:

Route Registration

The package automatically registers its routes when installed. However, if you're experiencing issues with routes not being registered, follow these steps:

1. Verify the service provider is registered in config/app.php:

2. Clear your route cache:

3. Verify the routes are registered:

You should see the webhook route listed with the name cashier-revenue-cat.webhook.

Common Route Registration Issues

1. Routes Not Showing Up

   • Make sure you've published the package's configuration
   • Verify the service provider is registered in config/app.php
   • Check that your .env file has the required configuration

2. Webhook Route Not Accessible

   • Verify the REVENUECAT_WEBHOOK_ENDPOINT is set correctly in your .env
   • Check that the route group (web or api) is appropriate for your use case
   • Ensure your web server is configured to handle the route
3. CSRF Token Issues
   • The webhook route is automatically excluded from CSRF protection
   • If you're still getting CSRF errors, verify the route is registered in the correct middleware group

Configuration

You can publish the config file with:

This will create a config/cashier-revenue-cat.php file in your config folder.

Environment Variables

Add these variables to your .env file:

Available Configuration Options

The package configuration is organized into several sections:

API Configuration

Webhook Configuration

Cache Configuration

Logging Configuration

Error Handling Configuration

Other Configuration

Webhook Security

The package includes several security features for webhooks:

1. Signature Verification: All webhooks are verified using the X-RevenueCat-Signature header
2. Rate Limiting: By default, webhooks are limited to 60 requests per minute per IP
3. IP Whitelisting: You can restrict webhook access to specific IP addresses
4. CSRF Protection: Webhook routes are automatically excluded from CSRF protection

To configure webhook security:

Custom Webhook Endpoint

To use a custom webhook endpoint, set the REVENUECAT_WEBHOOK_ENDPOINT environment variable:

The webhook URL will be: https://your-domain.com/api/revenuecat/webhook

Route Group Configuration

By default, the webhook route is registered in the web middleware group. You can change this by setting the REVENUECAT_ROUTE_GROUP environment variable:

This affects which middleware group the webhook route belongs to. The default is web.

For example, if you set REVENUECAT_ROUTE_GROUP=api, the webhook route will be registered as:

If you set REVENUECAT_ROUTE_GROUP=web, the webhook route will be registered as:

The route name will always be cashier-revenue-cat.webhook regardless of the group.

Mobile App Integration

iOS Integration

1. First, set up RevenueCat in your iOS app by adding the RevenueCat SDK:

2. Handle purchases in your iOS app:

Android Integration

1. Add the RevenueCat SDK to your Android app:

2. Handle purchases in your Android app:

Flutter Integration

1. Add the RevenueCat Flutter SDK to your pubspec.yaml:

2. Initialize RevenueCat in your Flutter app:

Laravel Backend Usage

Managing Subscribers

Handling Webhooks

1. The package automatically registers a webhook route at /webhook/revenuecat. You can configure the endpoint in your .env file:

2. Set up the webhook URL in your RevenueCat dashboard:

   • Log in to your RevenueCat dashboard at https://app.revenuecat.com
   • Go to Project Settings (gear icon) in the left sidebar
   • Click on "Webhooks" in the settings menu
   • Click "Add Webhook"
   • Enter your webhook URL (e.g., https://your-app.com/webhook/revenuecat)
   • Select the events you want to receive
   • RevenueCat will generate a webhook secret for you

3. Configure your webhook secret in your .env file:

4. You have two options for handling webhooks:

   a. Use the default webhook handler (no configuration needed): The package will automatically use the built-in webhook handler.

   b. Create your own webhook handler:

   This will:

   • Publish the webhook handler to app/Listeners/HandleRevenueCatWebhook.php
   • Publish the webhook controller to app/Http/Controllers/RevenueCat/WebhookController.php
   • Update the configuration to use your published controller
   • Update the route registration to use your published controller

   Your custom handler should implement the following interface:

   Note: The webhook handler configuration must include both the class name and the method name (e.g., Class@method). The method name is required and must be specified after the @ symbol. The method should accept a Request object and return a Response.

   After publishing, the webhook route will use your published controller at App\Http\Controllers\RevenueCat\WebhookController, which will dispatch the webhook event to your configured handler. You can customize both the controller and handler to implement your specific webhook handling logic.

5. The package automatically handles the following webhook events:

   • INITIAL_PURCHASE
   • RENEWAL
   • CANCELLATION
   • NON_RENEWING_PURCHASE
   • SUBSCRIPTION_PAUSED
   • SUBSCRIPTION_RESUMED
   • PRODUCT_CHANGE
   • BILLING_ISSUE
   • REFUND
   • SUBSCRIPTION_PERIOD_CHANGED

6. Listen to webhook events in your application:

7. The default webhook handler includes comprehensive event handling:

The webhook endpoint is automatically secured with signature verification using the X-RevenueCat-Signature header. The package will verify the signature using your configured webhook secret before processing any webhook events.

Webhook Event Handling

The package dispatches a WebhookReceived event for each webhook request. You can listen to this event in your application by:

1. Registering the event listener in your EventServiceProvider:

2. Creating a listener to handle the event:

3. Implementing the event handling logic in your listener:

The event payload contains all the information from the RevenueCat webhook, including:

• Event type
• Event ID
• Timestamp
• Subscriber information
• Product information
• Entitlements
• And more

You can access this information in your event listener to implement your business logic.

Webhook Event Types

The package handles the following webhook event types:

1. INITIAL_PURCHASE

   • Triggered when a user makes their first purchase
   • Contains initial subscription details and user information

2. RENEWAL

   • Triggered when a subscription is renewed
   • Contains updated subscription period information

3. CANCELLATION

   • Triggered when a subscription is cancelled
   • Contains cancellation details and effective date

4. NON_RENEWING_PURCHASE

   • Triggered when a subscription is set to not renew
   • Contains information about when the subscription will end

5. SUBSCRIPTION_PAUSED

   • Triggered when a subscription is paused
   • Contains pause duration and reason

6. SUBSCRIPTION_RESUMED

   • Triggered when a paused subscription is resumed
   • Contains updated subscription status

7. PRODUCT_CHANGE

   • Triggered when a subscription product is changed
   • Contains old and new product information

8. BILLING_ISSUE

   • Triggered when there's a billing problem
   • Contains error details and resolution steps

9. REFUND

   • Triggered when a purchase is refunded
   • Contains refund amount and reason
10. SUBSCRIPTION_PERIOD_CHANGED
    • Triggered when a subscription period is modified
    • Contains old and new period information

Each event type provides specific data in the payload that you can use to implement your business logic. The event listener example above shows how to handle each type of event.

Database Schema

The package includes migrations for the following tables:

• customers: Stores RevenueCat customer information

  • id: Primary key
  • revenuecat_id: RevenueCat's customer identifier
  • email: Customer's email address
  • display_name: Customer's display name
  • phone_number: Customer's phone number
  • metadata: JSON column for additional customer attributes
  • billable_type: Polymorphic relationship type
  • billable_id: Polymorphic relationship ID
  • Timestamps

• subscriptions: Stores subscription information

  • id: Primary key
  • billable_type: Polymorphic relationship type
  • billable_id: Polymorphic relationship ID
  • revenuecat_id: RevenueCat's subscription identifier
  • name: Subscription name
  • product_id: RevenueCat product identifier
  • price_id: RevenueCat price identifier
  • status: Subscription status
  • current_period_start: Start of current billing period
  • current_period_end: End of current billing period
  • trial_start: Start of trial period
  • trial_end: End of trial period
  • canceled_at: When the subscription was canceled
  • ended_at: When the subscription ended
  • paused_at: When the subscription was paused
  • resumed_at: When the subscription was resumed
  • metadata: JSON column for additional subscription attributes
  • Timestamps

• subscription_items: Stores subscription line items

  • id: Primary key
  • subscription_id: Foreign key to subscriptions
  • product_id: RevenueCat product identifier
  • price_id: RevenueCat price identifier
  • quantity: Quantity of items
  • metadata: JSON column for additional item attributes
  • Timestamps
• receipts: Stores transaction receipts
  • id: Primary key
  • billable_type: Polymorphic relationship type
  • billable_id: Polymorphic relationship ID
  • transaction_id: RevenueCat transaction identifier
  • store: App store identifier (App Store/Play Store)
  • environment: Production or sandbox
  • price: Transaction amount
  • currency: Transaction currency
  • purchase_date: When the purchase was made
  • expiration_date: When the purchase expires
  • metadata: JSON column for additional receipt attributes
  • Timestamps

Models

The package includes the following models in the PeterSowah\LaravelCashierRevenueCat\Models namespace:

• Customer: Represents a RevenueCat customer
• Subscription: Represents a customer's subscription
• Receipt: Represents a transaction receipt

To use these models in your application, you can either:

1. Use them directly:

2. Or extend them for custom functionality:

Testing

The package includes a comprehensive test suite. To run the tests:

This will run both PHPUnit tests and PHPStan static analysis. You can run them separately:

The package maintains a high level of type safety and follows Laravel's coding standards.

Contributing

Please see CONTRIBUTING.md for details.

Security

If you discover any security-related issues, please email [email protected] instead of using the issue tracker.

Credits

• Peter Sowah
• All Contributors

License

The MIT License (MIT). Please see License File for more information.