Genvoris Laravel

Official Laravel integration for the Genvoris Virtual Try-On platform.

Add virtual try-on experiences to your Laravel application in minutes: upsert customers, mint session tokens, proxy widget requests server-side, and handle webhooks — all with zero client-side API key exposure.

Requirements

Installation

composer require genvoris/laravel

Run the install command to publish config and add .env keys:

php artisan genvoris:install

Add your keys to .env:

GENVORIS_API_KEY=gvk_live_your_key_here
GENVORIS_WEBHOOK_SECRET=your_webhook_secret_here

Verify the connection:

php artisan genvoris:test-connection

Configuration

The published config/genvoris.php file exposes all options. The most important:

Basic Usage

Facade

use Genvoris\Laravel\Facades\Genvoris;

// Upsert a customer (auto-prefixes the external ID → "laravel_42")
$customer = Genvoris::upsertCustomer('42', ['email' => 'alice@example.com']);

// Mint a session token for the widget
$session = Genvoris::mintSession($customer->id);

// List your plans
$plans = Genvoris::listPlans();

// Get a customer's usage
$usage = Genvoris::customerUsage($customer->id);
if ($usage->canTryOn()) { /* ... */ }

Dependency injection

use Genvoris\Laravel\Genvoris;

class TryOnController extends Controller
{
    public function __construct(private readonly Genvoris $genvoris) {}

    public function session(Request $request): JsonResponse
    {
        $session = $this->genvoris->mintSession($request->user()->genvorisCustomerId());
        return response()->json(['token' => $session->token]);
    }
}

HasGenvorisAccess Trait

Add the trait to your User model (or any Eloquent model) to get Genvoris helpers:

use Genvoris\Laravel\Concerns\HasGenvorisAccess;

class User extends Authenticatable
{
    use HasGenvorisAccess;
}

Available methods:

// Returns "laravel_{id}"
$user->genvorisExternalId();

// Upsert the user in the Genvoris platform (auto-syncs email if present)
$customer = $user->syncToGenvoris(['planId' => 'plan_basic']);

// Mint a session token (syncs first if needed)
$session = $user->genvorisSession(expiresIn: 900);

// Usage & entitlement
$usage = $user->genvorisUsage();
$user->canTryOn(); // bool — returns false gracefully on API errors

// Full portal Customer object
$customer = $user->genvorisPortalCustomer();

Optional local cache table

Run the optional migration to cache customer IDs and avoid repeated API calls:

php artisan vendor:publish --tag=genvoris-migrations
php artisan migrate

Blade Directives

{{-- Load the widget script --}}
@genvorisScripts

{{-- Emit window.genvorisConfig (never exposes api_key) --}}
@genvorisConfig(['productId' => $product->id])

{{-- Combined shorthand --}}
@genvorisWidget(['productId' => $product->id])

{{-- Render a try-on button --}}
@genvorisTryOnButton(['productId' => $product->id, 'label' => 'Try On'])

Or use the Blade views directly:

@include('genvoris::widget', ['productId' => $product->id, 'token' => $session->token])
@include('genvoris::components.try-on-button', ['productId' => $product->id])

Webhooks

Register your endpoint in the Genvoris dashboard:

POST https://yourapp.com/webhooks/genvoris

The package auto-registers this route and verifies the HMAC-SHA256 signature on every request.

Listening to events

// In a service provider or EventServiceProvider
use Genvoris\Laravel\Webhooks\Events\CustomerCreated;
use Genvoris\Laravel\Webhooks\Events\GenvorisWebhookReceived;

Event::listen(CustomerCreated::class, function (CustomerCreated $event) {
    $payload = $event->payload;
    // create local user, send welcome email, etc.
});

// Catch all events
Event::listen(GenvorisWebhookReceived::class, function (GenvorisWebhookReceived $event) {
    Log::info("Genvoris webhook: {$event->type} ({$event->id})");
});

Or declare listeners in config/genvoris.php:

'webhook' => [
    'listeners' => [
        \Genvoris\Laravel\Webhooks\Events\CustomerCreated::class => [
            \App\Listeners\HandleGenvorisCustomerCreated::class,
        ],
    ],
],

Supported event types

All event classes are in the Genvoris\Laravel\Webhooks\Events namespace.

Manual verification

use Genvoris\Laravel\Webhooks\WebhookVerifier;

$ok = (new WebhookVerifier())->verify(
    $request->getContent(),
    $request->header('X-Genvoris-Signature'),
    config('genvoris.webhook.secret'),
);

Proxy

The package registers a POST /genvoris-proxy/{path} route that injects your API key server-side before forwarding to api.genvoris.org. Only paths in the proxy.allowed_paths allowlist are forwarded.

In your front-end widget configuration, set:

window.genvorisConfig = {
    apiProxyBase: '/genvoris-proxy/',
};

@genvorisConfig emits this automatically.

Artisan Commands

Testing

Install dev dependencies and run the suite:

composer install
composer test

Run code style checks:

composer lint:check   # check only
composer lint         # auto-fix

Changelog

See CHANGELOG.md for a list of changes.

Contributing

Bug reports and pull requests are welcome at the project's GitHub repository.
Before submitting a PR, please run composer test and composer lint:check.

License

MIT — see LICENSE.

Support

• Docs: https://docs.genvoris.org
• Email: support@genvoris.org