PHPackages                             velixbiometrics/sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. velixbiometrics/sdk

ActiveLibrary[Authentication & Authorization](/categories/authentication)

velixbiometrics/sdk
===================

SDK oficial do VELIX — controle de acesso biométrico

v1.2.180(1mo ago)00MITPHPPHP >=8.1

Since Jul 6Pushed 1mo agoCompare

[ Source](https://github.com/VELIX-Biometrics/sdk-velix-php)[ Packagist](https://packagist.org/packages/velixbiometrics/sdk)[ Docs](https://github.com/VELIX-Biometrics/sdk-velix-php)[ RSS](/packages/velixbiometrics-sdk/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (3)Versions (4)Used By (0)

velixbiometrics/sdk — PHP SDK [![version](https://camo.githubusercontent.com/622c4f8e131a3f961b6e7a47b6c66422d96d83816f52038c9bd13687664f3ed6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d302e312e302d2d616c706861312d626c7565)](https://camo.githubusercontent.com/622c4f8e131a3f961b6e7a47b6c66422d96d83816f52038c9bd13687664f3ed6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d302e312e302d2d616c706861312d626c7565)
==================================================================================================================================================================================================================================================================================================================================================================================================================================================================================

[](#velixbiometricssdk--php-sdk-)

> ⚠️ **Alpha / pre-release**, mas já publicado e confirmado funcionando de ponta a ponta contra a API real de staging (onboarding, LGPD, me, events). **Packagist:**

Official PHP SDK for the VELIX Biometrics platform — facial access control B2B SaaS.

Requirements
------------

[](#requirements)

- PHP 8.1+
- ext-json
- Composer

Installation
------------

[](#installation)

```
composer require velixbiometrics/sdk
```

Auth
----

[](#auth)

All requests are authenticated with an API key issued per tenant application. Send it via the `x-api-key` header (default) or `Authorization: Bearer vlx_...` (accepted by the same guard). Never use any other auth mechanism.

Quick Start
-----------

[](#quick-start)

```
use Velix\VelixClient;
use Velix\Modules\CheckinModule;

$client = new VelixClient([
    'apiUrl'  => $_ENV['VELIX_API_URL'],
    'apiKey'  => $_ENV['VELIX_API_KEY'],
    'timeout' => 30, // seconds; default is 30s (30000ms) per SDK contract, always overridable
]);

$result = (new CheckinModule($client))->identify($frameBase64);
echo $result->matched ? 'MATCHED' : 'NOT MATCHED';
```

Environment Variables
---------------------

[](#environment-variables)

VariableRequiredDescription`VELIX_API_URL`YesAPI base URL (`https://api.velixbiometrics.com`)`VELIX_API_KEY`YesAPI key (`vlx_...`)Modules
-------

[](#modules)

Only the 6 real endpoints of `/v1/api/*` are implemented. `PersonsModule`, `TenantsModule` and `WebhooksModule::configure()` are kept for backward-compatible autoloading only — every method throws `RuntimeException` since no corresponding endpoint exists on the real API.

ModuleMethodEndpointScope`OnboardingModule``enroll()``POST /v1/api/onboarding``onboarding:write``CheckinModule``identify()``POST /v1/api/checkin/identify``checkin:write``LgpdModule``requestDeletion()``POST /v1/api/deletion-request``lgpd:write``MeModule``get()``GET /v1/api/me/{personId}``me:read``EventsModule``createGuest()``POST /v1/api/events/{id}/guests``events:write``EventsModule``getGuest()``GET /v1/api/events/{id}/guests/{guestId}``events:read`**Velix Time is not covered.** No `/v1/api/time/*` endpoint exists in the backend yet (see task #616) — there is no Time-related class in this SDK to call.

Onboarding Module
-----------------

[](#onboarding-module)

```
use Velix\Modules\OnboardingModule;

$onboarding = new OnboardingModule($client);

$result = $onboarding->enroll('João Silva', [$frame1, $frame2, $frame3], [
    'email' => 'joao@company.com',
    'external_id' => 'EMP-001',
]);

// $result->personId, $result->identityId, $result->enrolled, $result->framesProcessed
```

Checkin Module
--------------

[](#checkin-module)

```
use Velix\Modules\CheckinModule;

$checkin = new CheckinModule($client);

$result = $checkin->identify($frameBase64, [
    'topK' => 3,
    'location' => ['latitude' => -23.55, 'longitude' => -46.63],
]);

// $result->matched, $result->subjectId, $result->subjectName, $result->livenessOk, $result->model
// Liveness/similarity score is never exposed — only booleans.
```

`qr()` and `pin()` throw `RuntimeException` — no such endpoint exists in `/v1/api/*`.

Me Module
---------

[](#me-module)

```
use Velix\Modules\MeModule;

$me = (new MeModule($client))->get('person-uuid');
// $me->id, $me->name, $me->email, $me->phone, $me->photoUrl, $me->createdAt
```

LGPD Module
-----------

[](#lgpd-module)

```
use Velix\Modules\LgpdModule;

$result = (new LgpdModule($client))->requestDeletion('person-uuid');
// $result->protocolNumber, $result->message
```

Events Module
-------------

[](#events-module)

```
use Velix\Modules\EventsModule;

$events = new EventsModule($client);

$guest = $events->createGuest('event-uuid', [
    'name' => 'Maria Souza',
    'email' => 'maria@example.com',
]);

$guest = $events->getGuest('event-uuid', $guest->id);
```

`list()`, `get()`, `create()`, `configure()`, `delete()` throw `RuntimeException` — no such event-management endpoints exist in `/v1/api/*`.

Webhook Signature Validation
----------------------------

[](#webhook-signature-validation)

`WebhooksModule::validateSignature()` is a pure local helper (no HTTP call) and remains functional. `WebhooksModule::configure()` throws `RuntimeException` — no matching endpoint.

```
use Velix\Modules\WebhooksModule;

$valid = WebhooksModule::validateSignature(
    payload:   file_get_contents('php://input'),
    signature: $_SERVER['HTTP_X_VELIX_SIGNATURE'],
    secret:    $_ENV['VELIX_WEBHOOK_SECRET']
);

if (!$valid) {
    http_response_code(401);
    exit;
}
```

Error Handling
--------------

[](#error-handling)

```
use Velix\Exceptions\AuthException;
use Velix\Exceptions\BiometricException;
use Velix\Exceptions\VelixException;

try {
    $result = $checkin->identify($frameBase64);
} catch (AuthException $e) {
    echo 'Invalid API key';
} catch (BiometricException $e) {
    echo 'Face not recognized or liveness failed';
} catch (VelixException $e) {
    echo "HTTP {$e->getCode()}: {$e->getMessage()}";
}
```

Running Tests
-------------

[](#running-tests)

```
composer install
composer exec phpunit
```

Local Development
-----------------

[](#local-development)

```
composer install
composer exec phpunit -- --testdox
```

Get an API Key
--------------

[](#get-an-api-key)

Access the dashboard at **velixbiometrics.com** → Settings → API Keys → New Key.

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance91

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~2 days

Total

2

Last Release

43d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/298506193?v=4)[VELIX Biometrics](/maintainers/velixbiometrics)[@velixbiometrics](https://github.com/velixbiometrics)

---

Top Contributors

[![brajola](https://avatars.githubusercontent.com/u/505824?v=4)](https://github.com/brajola "brajola (12 commits)")

---

Tags

phpsdkFacial Recognitionbiometricsvelix

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/velixbiometrics-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/velixbiometrics-sdk/health.svg)](https://phpackages.com/packages/velixbiometrics-sdk)
```

###  Alternatives

[aws/aws-sdk-php

AWS SDK for PHP - Use Amazon Web Services in your PHP project

6.2k555.0M2.8k](/packages/aws-aws-sdk-php)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

353.6k](/packages/eslazarev-wildberries-sdk)[ellaisys/aws-cognito

Laravel Authentication using AWS Cognito (Web and API)

121269.8k1](/packages/ellaisys-aws-cognito)[kinde-oss/kinde-auth-php

Kinde PHP SDK for authentication

2293.1k3](/packages/kinde-oss-kinde-auth-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)