README

Alpha release -- under active development. Expect breaking changes.

Laravel integration for Vatly billing, inspired by Laravel Cashier. Provides Eloquent models, a Billable trait, checkout/subscription builders, webhook handling, and event listeners.

Built on top of vatly/vatly-fluent-php.

Installation

composer require vatly/vatly-laravel:v0.3.0-alpha.1

Pin to an exact version. This is an alpha release and the API will change.

Requirements

• PHP 8.2+
• Laravel 10, 11, or 12
• A Vatly API key (vatly.com)

Setup

1. Publish the config:

php artisan vendor:publish --tag=vatly-config

1. Add your API key to .env:

VATLY_API_KEY=test_xxxxxxxxxxxx
VATLY_WEBHOOK_SECRET=your-webhook-secret

1. Publish and run migrations:

php artisan vendor:publish --tag=vatly-migrations
php artisan vendor:publish --tag=vatly-billable-migrations
php artisan migrate

1. Add the Billable trait to your User model:

use Vatly\Laravel\Contracts\BillableInterface;
use Vatly\Laravel\Billable;

class User extends Authenticatable implements BillableInterface
{
    use Billable;
}

Usage

// Create a checkout
$checkout = $user->newCheckout()
    ->withItems(collect(['subscription_plan_id']))
    ->create(
        redirectUrlSuccess: 'https://example.com/success',
        redirectUrlCanceled: 'https://example.com/canceled',
    );

// Swap subscription plan
$user->subscription('default')->swap('plan_premium');

// Cancel subscription
$user->subscription('default')->cancel();

Webhooks

The package registers a webhook endpoint at /vatly/webhook automatically. Configure your webhook secret in the Vatly dashboard.

Events dispatched:

• Vatly\Events\WebhookReceived
• Vatly\Events\SubscriptionStarted
• Vatly\Events\SubscriptionCanceledImmediately
• Vatly\Events\SubscriptionCanceledWithGracePeriod

Testing

composer test

License

MIT