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
• Comprehensive subscription management
  • Create and manage RevenueCat customers
  • Check subscription status
  • Get active subscriptions
  • Access subscription history
  • Handle subscription events
• Entitlements management
  • Get all entitlements
  • Check specific entitlements
  • Verify entitlement status
• Offerings and products management
  • Get current offering
  • List available offerings
  • Access product information
• Automatic retry mechanism for failed API calls
• Caching support for API responses
• Comprehensive logging and error handling

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 Tables

The package creates the following database tables:

• customers: Stores customer information
• subscriptions: Stores subscription information

Models

The package provides the following models:

• Customer: Represents a customer
• Subscription: Represents a subscription

Usage

To use the package, add the Billable trait to your User model:

This will give your User model access to the following relationships:

• customer(): Get the customer associated with the user
• subscriptions(): Get the subscriptions associated with the user

Configuration

The package can be configured by publishing the configuration file:

This will create a config/cashier-revenue-cat.php file where you can configure:

• API Key
• Project ID
• Webhook Secret
• Webhook Endpoint
• Webhook Handler

Webhooks

The package provides webhook handling for RevenueCat events. To use webhooks:

1. Configure your webhook endpoint in RevenueCat to point to your application's webhook URL
2. Set the webhook secret in your configuration
3. The package will automatically handle incoming webhooks and dispatch events

Events

The package dispatches the following events:

• WebhookReceived: Dispatched when a webhook is received from RevenueCat

Testing

The package provides a test case that you can use in your tests:

This test case provides:

• Database configuration for testing
• RevenueCat configuration for testing
• Helper methods for creating test data

License

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