Skip to main content

Laravel Integration

Latest Version on Packagist Tests PHP Version

The genvoris/laravel package is the official Laravel integration for the Genvoris Virtual Try-On platform. It provides a service provider, Facade, Blade directives, webhook handling, and a server-side proxy — covering everything you need to add virtual try-on to a Laravel application without exposing your API key to the browser.

Requirements: PHP ^8.1, Laravel ^10 | ^11 | ^12

Links: Packagist · GitHub · Changelog

Installation​

composer require genvoris/laravel
php artisan genvoris:install

Add your credentials to .env:

GENVORIS_API_KEY=gvk_live_your_key_here
GENVORIS_WEBHOOK_SECRET=your_webhook_secret_here

Confirm the connection:

php artisan genvoris:test-connection

Configuration​

Publish the config file:

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

Key options in config/genvoris.php:

KeyDefaultDescription
api_keyenv('GENVORIS_API_KEY')Platform API key
api_base_urlhttps://genvoris.org/api/v1API base URL
timeout30HTTP timeout (seconds)
retry.times3Retries on 429 / 5xx
webhook.secretenv('GENVORIS_WEBHOOK_SECRET')HMAC signing secret
webhook.pathwebhooks/genvorisWebhook route prefix
proxy.pathgenvoris-proxyProxy route prefix
external_id_prefixlaravel_Prefix for external IDs
widget_urlhttps://api.genvoris.org/widget.jsWidget script URL

Quick Start​

1. Add the trait to your User model​

use Genvoris\Laravel\Concerns\HasGenvorisAccess;

class User extends Authenticatable
{
    use HasGenvorisAccess;
}

2. Mint a session token in a controller​

use Illuminate\Http\Request;
use Illuminate\Http\JsonResponse;

class TryOnController extends Controller
{
    public function session(Request $request): JsonResponse
    {
        $session = $request->user()->genvorisSession();
        return response()->json(['token' => $session->token]);
    }
}

3. Add the widget to your Blade layout​

{{-- In your <head> or before </body> --}}
@genvorisConfig(['productId' => $product->id])
@genvorisScripts

{{-- Where you want the button --}}
@genvorisTryOnButton(['productId' => $product->id, 'label' => 'Try On'])

API​

Facade​

use Genvoris\Laravel\Facades\Genvoris;

$customer = Genvoris::upsertCustomer('42', ['email' => 'alice@example.com']);
$session  = Genvoris::mintSession($customer->id);
$plans    = Genvoris::listPlans();
$usage    = Genvoris::customerUsage($customer->id);

HasGenvorisAccess methods​

MethodReturn typeDescription
genvorisExternalId()stringlaravel_{id}
syncToGenvoris(array $attrs)CustomerUpsert user in platform
genvorisSession(int $expiresIn)SessionMint a session token
genvorisUsage()CustomerUsageFetch usage/quota
canTryOn()boolWhether user has quota
genvorisCustomerId()?stringCached portal customer ID
genvorisPortalCustomer()CustomerFull portal customer object

Blade directives​

DirectiveOutput
@genvorisScripts<script src="..." defer> widget loader
@genvorisConfig($opts)<script>window.genvorisConfig = {...};</script>
@genvorisWidget($opts)Config + scripts combined
@genvorisTryOnButton($opts)<button data-genvoris-product="...">

Security: @genvorisConfig never includes api_key or webhook.secret in its output.

Webhooks​

Register your endpoint in the Genvoris dashboard:

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

The package auto-registers this route. Signature verification is handled automatically by the VerifyGenvorisWebhook middleware.

Listening to events​

use Genvoris\Laravel\Webhooks\Events\CustomerCreated;

Event::listen(CustomerCreated::class, function (CustomerCreated $event) {
    $data = $event->payload['data'];
    // provision local resources, send welcome email, etc.
});

All typed events expose a single $payload property (the full decoded JSON object).

Supported event types​

Portal event typeLaravel event class
end_customer.createdCustomerCreated
end_customer.updatedCustomerUpdated
end_customer.cancelledCustomerCancelled
end_customer.quota_warningCustomerQuotaWarning
end_customer.quota_exhaustedCustomerQuotaExhausted
end_customer.period_rolledCustomerPeriodRolled
plan.createdPlanCreated
plan.updatedPlanUpdated
plan.disabledPlanDisabled

You can also listen to GenvorisWebhookReceived to catch all events in one listener.

Proxy​

The package registers POST /genvoris-proxy/{path} to forward widget requests to api.genvoris.org with your API key injected server-side. The browser never sees your key.

Default allowed paths: api/analyze, api/tryon, api/config, api/status.

@genvorisConfig automatically sets window.genvorisConfig.apiProxyBase to the proxy URL.

Artisan Commands​

CommandDescription
php artisan genvoris:installInteractive setup wizard
php artisan genvoris:test-connectionVerify API key
php artisan genvoris:list-plansShow plans table
php artisan genvoris:list-customersShow customers table
php artisan genvoris:webhook-testSend a signed test webhook

Optional: Customer Sessions Table​

Publish and run the optional migration to cache customer IDs locally:

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

This creates genvoris_customer_sessions with a polymorphic user relationship. When present, HasGenvorisAccess reads from it instead of calling the API on every request.

Testing​

composer test

The test suite uses Http::fake() — no live API calls are made.

Further Reading​