PHPackages abdelaziz-hassan/authentica - 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. abdelaziz-hassan/authentica ActiveLibrary[Authentication & Authorization](/categories/authentication) abdelaziz-hassan/authentica =========================== Secure Laravel client for Authentica API (OTP, Nafath, Face, Voice). v1.0.0(7mo ago)17MITPHPPHP ^8.1 Since Oct 5Pushed 7mo agoCompare [ Source](https://github.com/AbdelAziz-hassan/authentica)[ Packagist](https://packagist.org/packages/abdelaziz-hassan/authentica)[ RSS](/packages/abdelaziz-hassan-authentica/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (5)Versions (2)Used By (0) Authentica for Laravel ====================== [](#authentica-for-laravel) > A secure, DX‑friendly Laravel SDK for **Authentica** (Format: 1A, Host: `https://api.authentica.sa/api/v2`). > Features: OTP (SMS/WhatsApp/Email), Nafath (with **package‑handled webhook → single event**), Face & Voice verification, and an **optional circuit breaker**. --- Table of Contents ----------------- [](#table-of-contents) - [Highlights](#highlights) - [Requirements](#requirements) - [Installation](#installation) - [Configuration](#configuration) - [Usage](#usage) - [OTP](#otp) - [Nafath](#nafath) - [Webhook (package‑handled)](#webhook-packagehandled) - [Face Verification](#face-verification) - [Voice Verification](#voice-verification) - [Circuit Breaker (Optional)](#circuit-breaker-optional) - [Security Notes](#security-notes) - [Troubleshooting](#troubleshooting) - [Versioning](#versioning) - [License](#license) --- Highlights ---------- [](#highlights) - **Clean API** returning a predictable shape: `{ ok, status, body, message, circuit? }` - **Zero app boilerplate** for Nafath webhooks — the package authenticates, validates, and **dispatches a single Laravel event** for you to handle. - **Secure by default**: JSON‑only responses, strict validation, Basic/Password webhook auth. - **Production‑ready** optional **circuit breaker** that you can enable/disable and choose the backing store for (Cache or in‑memory). --- Requirements ------------ [](#requirements) - PHP **8.1+** - Laravel **9.x / 10.x / 11.x** - Composer --- Installation ------------ [](#installation) ``` composer require abdelaziz-hassan/authentica ``` The service provider and facades are auto‑discovered. (Optional) Publish the configuration file: ``` php artisan vendor:publish --tag=authentica-config ``` --- Configuration ------------- [](#configuration) Set the basics in `.env`: ``` AUTHENTICA_API_KEY=your-authentica-api-key AUTHENTICA_HOST=https://api.authentica.sa/api/v2 ``` ### Nafath Webhook [](#nafath-webhook) Enable and choose **one** auth mode: ``` AUTHENTICA_NAFATH_WEBHOOK_ENABLED=true AUTHENTICA_NAFATH_WEBHOOK_PATH=/webhooks/authentica/nafath # ONE of: body_password | basic AUTHENTICA_NAFATH_WEBHOOK_AUTH=body_password # Body password mode AUTHENTICA_NAFATH_PASSWORD_LABEL=Password AUTHENTICA_NAFATH_PASSWORD_VALUE=super-secret # OR Basic mode (header OR body labels accepted) # AUTHENTICA_NAFATH_WEBHOOK_AUTH=basic # AUTHENTICA_NAFATH_BASIC_USER_LABEL=username # AUTHENTICA_NAFATH_BASIC_USER_VALUE=authentica # AUTHENTICA_NAFATH_BASIC_PASS_LABEL=password # AUTHENTICA_NAFATH_BASIC_PASS_VALUE=strongpass ``` ### Circuit Breaker (Optional) [](#circuit-breaker-optional) Disabled by default. Enable if you want the SDK to **fast‑fail** during upstream outages: ``` AUTHENTICA_CIRCUIT_ENABLED=true AUTHENTICA_CIRCUIT_DRIVER=cache # or: array (in‑memory) # AUTHENTICA_CIRCUIT_FAILURES=5 # AUTHENTICA_CIRCUIT_OPEN=60 # AUTHENTICA_CIRCUIT_SUCC=2 ``` --- Usage ----- [](#usage) Import the facade: ``` use AbdelAzizHassan\Authentica\Facades\Authentica; ``` All client calls return: ``` [ 'ok' => bool, // Http::successful() 'status' => int, // HTTP status (0 => network error) 'body' => array|null, // decoded JSON 'message' => string|null, // body['message'] if present 'circuit' => ['state' => 'closed|open|half_open'] // when breaker enabled ] ``` ### OTP [](#otp) **Send OTP** ``` $res = Authentica::sendOtp([ 'method' => 'sms', // sms|whatsapp|email 'phone' => '+9665XXXXXXXXX', // required for sms/whatsapp // 'email' => 'user@test.test', // required for email // 'template_id' => 31, // 'fallback_email' => 'fallback@test.test', // 'otp' => '123456', // optional custom OTP ]); ``` **Verify OTP** ``` $res = Authentica::verifyOtp([ 'phone' => '+9665XXXXXXXXX', // or 'email' 'email' => 'user@test.test', 'otp' => '123456', ]); ``` ### Nafath [](#nafath) **Start verification** ``` $res = Authentica::verifyByNafath([ 'national_id' => '123XXXXXXX', ]); // $res['body']['data'] -> ['TransactionId' => '...', 'Code' => '...'] ``` **Nafath with data** ``` // 1) request OTP to device $r1 = Authentica::nafathRequest([ 'national_id' => '123XXXXXXX', 'phone_number'=> '966XXXXXXX', ]); // 2) verify to get Code $r2 = Authentica::nafathVerify([ 'otp' => 'xxxxxx', 'request_id' => 'xxxxx-xxxx-xxxx-xxxx-xxxxxxxxx', ]); ``` ### Webhook (package‑handled) [](#webhook-packagehandled) The package registers a `POST` route (default `/webhooks/authentica/nafath`). It **authenticates**, **validates**, and **dispatches** one event: ``` \AbdelAzizHassan\Authentica\Webhooks\Events\NafathWebhookReceived ``` Listen to it in your app: ``` // app/Providers/EventServiceProvider.php protected $listen = [ \AbdelAzizHassan\Authentica\Webhooks\Events\NafathWebhookReceived::class => [ \App\Listeners\HandleNafathWebhook::class, ], ]; ``` ``` // app/Listeners/HandleNafathWebhook.php use AbdelAzizHassan\Authentica\Webhooks\Events\NafathWebhookReceived; class HandleNafathWebhook { public function handle(NafathWebhookReceived $e): void { // $e->transactionId string // $e->nationalId string // $e->status "COMPLETED" | "REJECTED" // $e->raw full original payload // ... your logic here ... } } ``` **Example payload from Authentica** ``` { "TransactionId": "6419747b-b0d7-4564-8755-a7f554d16b10", "NationalId": "1234567891", "Status": "COMPLETED", "Password": "your-secure-password" } ``` ### Face Verification [](#face-verification) ``` // Verify by face (base64 images as JSON) $res = Authentica::verifyByFace([ 'user_id' => 'u-123', // 'registered_face_image' => 'base64-...', 'query_face_image' => 'base64-...', ]); // Store/Get/Delete reference face image Authentica::storeFaceImage('u-123', ['face_image' => 'base64-...']); Authentica::getFaceImage('u-123'); Authentica::deleteFaceImage('u-123'); ``` ### Voice Verification [](#voice-verification) ``` // Verify by voice (base64 audio as JSON) $res = Authentica::verifyByVoice([ 'user_id' => 'u-123', // 'registered_audio' => 'base64-...', 'query_audio' => 'base64-...', ]); // Store/Get/Delete reference audio Authentica::storeVoice('u-123', ['audio' => 'base64-...']); Authentica::getVoice('u-123'); Authentica::deleteVoice('u-123'); ``` --- Circuit Breaker (Optional) -------------------------- [](#circuit-breaker-optional-1) When enabled, the SDK protects your app from upstream instability. - Opens after consecutive **network errors** or configured **HTTP statuses** (`429,500,502,503,504` by default). - While open, calls **short‑circuit** with: ``` { "ok": false, "status": 503, "message": "Upstream temporarily unavailable (circuit open)" } ``` - After a cool‑down, it **half‑opens** and closes on a few successes. Enable in `.env`: ``` AUTHENTICA_CIRCUIT_ENABLED=true AUTHENTICA_CIRCUIT_DRIVER=cache # or array # AUTHENTICA_CIRCUIT_FAILURES=5 # AUTHENTICA_CIRCUIT_OPEN=60 # AUTHENTICA_CIRCUIT_SUCC=2 ``` You can check the state in every response: ``` $res['circuit']['state'] ?? null; // 'closed' | 'open' | 'half_open' ``` --- Security Notes -------------- [](#security-notes) - **Webhook auth**: choose **one** mode — `body_password` or `basic`. - **Basic** accepts standard `Authorization: Basic …` header **or** labeled fields in JSON (`username_label`/`password_label`). - All webhook responses are **JSON** (no Blade pages). - Inputs are **validated**; failures return `422` with details. --- Troubleshooting --------------- [](#troubleshooting) - **Got Blade/HTML in webhook?** Ensure the route is under the `api` stack and the package’s JSON middleware is active (it is by default). - **Auth fails on webhook**: Double‑check your `.env` values and whether you’re sending header or labeled fields. - **Circuit always open**: Start with `AUTHENTICA_CIRCUIT_FAILURES=1` in dev and watch logs; ensure your cache driver works if using `cache` mode. --- Versioning ---------- [](#versioning) Follows **SemVer**. Targets Authentica **Format: 1A**, base host `https://api.authentica.sa/api/v2`. --- License ------- [](#license) MIT © AbdelAziz Hassan ### Health Score 32 — LowBetter than 72% of packages Maintenance64 Regular maintenance activity Popularity6 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 Unknown Total 1 Last Release 219d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/4b4b21d692e7a0a35af567d933cafe1598c096f844bba2d5038ef2aedc832ad6?d=identicon)[AbdelAziz-hassan](/maintainers/AbdelAziz-hassan) --- Top Contributors [![AbdelAziz-hassan](https://avatars.githubusercontent.com/u/26216921?v=4)](https://github.com/AbdelAziz-hassan "AbdelAziz-hassan (1 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/abdelaziz-hassan-authentica/health.svg) ``` [![Health](https://phpackages.com/badges/abdelaziz-hassan-authentica/health.svg)](https://phpackages.com/packages/abdelaziz-hassan-authentica) ``` ### Alternatives [php-open-source-saver/jwt-auth JSON Web Token Authentication for Laravel and Lumen 8359.8M53](/packages/php-open-source-saver-jwt-auth)[laragear/two-factor On-premises 2FA Authentication for out-of-the-box. 339785.3k8](/packages/laragear-two-factor)[illuminate/auth The Illuminate Auth package. 9327.3M1.0k](/packages/illuminate-auth)[josiasmontag/laravel-recaptchav3 Recaptcha V3 for Laravel package 2641.6M2](/packages/josiasmontag-laravel-recaptchav3)[rahul900day/laravel-captcha Different types of Captcha implementation for Laravel Application. 10715.9k](/packages/rahul900day-laravel-captcha)[jurager/teams Laravel package to manage team functionality and operate with user permissions. 22817.3k](/packages/jurager-teams) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)