> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avraapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel SDK overview and setup

> Install and configure the official AvraAPI Laravel SDK with the Facade or dependency injection.

The AvraAPI Laravel SDK registers one configured `ApixClient` singleton in your
Laravel application. Use the `AvraAPI` Facade for concise application code or
inject `ApixClient` where explicit dependencies are clearer. Both patterns use
the same client and return the same response objects.

<Warning>
  This package is for backend Laravel code only. Never put a Project Client
  Secret in a Blade view, browser JavaScript, mobile app, public repository, or
  client-facing response.
</Warning>

<CardGroup cols={2}>
  <Card title="Facade" icon="wand-magic-sparkles">
    Use `AvraAPI::currency()`, `AvraAPI::security()`, and the other service
    accessors in a controller, job, command, or service class.
  </Card>

  <Card title="Dependency injection" icon="cube">
    Type-hint `Avraapi\Apix\ApixClient` when a class should declare its
    AvraAPI dependency explicitly.
  </Card>
</CardGroup>

## Requirements

| Requirement | Supported value |
| - | - |
| PHP | PHP 8.2 or later |
| Laravel | Laravel 10, 11, or 12 |
| Composer | Available in the Laravel application environment |
| Package | `avraapi/laravel-sdk` |
| Credentials | A Project Client ID and Client Secret from an AvraAPI project |

The current Laravel SDK release is **1.2.0**. Composer installs its official
PHP SDK `^1.5.2` dependency automatically.

## Install the package

Run Composer from the root of your Laravel application:

```bash theme={null}
composer require avraapi/laravel-sdk
```

Composer package discovery registers `AvraApiServiceProvider` and the
`AvraAPI` alias. Do not add the provider or alias manually to `config/app.php`.

## Configure project credentials

The package merges its configuration defaults automatically. Publish an
application-owned `config/avraapi.php` file only when you want to inspect or
customise those settings:

```bash theme={null}
php artisan vendor:publish --tag="avraapi-config"
```

Keep your AvraAPI project credentials in the Laravel application's `.env`
file. `APIX_PROJECT_KEY` is the Project Client ID and `APIX_API_SECRET` is its
matching Client Secret.

```ini title=".env" theme={null}
APIX_PROJECT_KEY=your_project_client_id
APIX_API_SECRET=your_project_client_secret
APIX_ENV=development
```

`development` becomes `dev` and `production` becomes `prod`. The package
defaults to `production`, so set `APIX_ENV=development` deliberately when
working with a Development project.

| Setting | Purpose | Default |
| - | - | - |
| `APIX_ENV` | Environment; accepts `development`/`dev` and `production`/`prod`. | `production` |
| `APIX_BASE_URL` | Override for an approved non-production environment. | SDK production URL |
| `APIX_TIMEOUT` | Full HTTP request timeout in seconds. | `30` |
| `APIX_CONNECT_TIMEOUT` | Connection timeout in seconds. | `10` |

Keep the standard base URL for production. After changing `.env` values on a
cached deployment, rebuild or clear that deployment's Laravel configuration
cache before it accepts new requests.

## Use the Facade

Import the Facade in backend application code. Laravel resolves the shared
configured client; do not construct a new client for every request.

```php title="Use the AvraAPI Facade in a controller" theme={null}
<?php

namespace App\Http\Controllers;

use Avraapi\Laravel\Facades\AvraAPI;
use Illuminate\Http\JsonResponse;

final class CurrencyController extends Controller
{
    public function index(): JsonResponse
    {
        // AvraAPI SDK call.
        $response = AvraAPI::currency()->getCodes();

        // Your application code.
        return response()->json([
            'codes' => $response->data['codes'],
            'request_id' => $response->requestId,
        ]);
    }
}
```

The Composer alias also makes `AvraAPI` available to Laravel. Importing
`Avraapi\Laravel\Facades\AvraAPI` keeps the dependency explicit for IDEs and
static analysis.

## Use dependency injection

Inject `Avraapi\Apix\ApixClient` when a class should declare its dependency.
It and the Facade resolve the same singleton.

```php title="Inject the configured client" theme={null}
<?php

namespace App\Services;

use Avraapi\Apix\ApixClient;
use Avraapi\Apix\Responses\ApiResponse;

final class RiskCheckService
{
    public function __construct(
        private readonly ApixClient $avraapi,
    ) {}

    public function checkEmail(string $email): ApiResponse
    {
        // AvraAPI SDK call.
        return $this->avraapi->security()->checkBurnerEmail($email);
    }
}
```

Use one access pattern consistently inside a class. The Facade is convenient
at application edges; dependency injection makes service dependencies explicit
and easy to substitute in tests.

## Read a JSON response

Most provider operations return `ApiResponse`. The operation result is in
`data`; retain `requestId` in support records without retaining sensitive
provider payloads.

```php title="Read an ApiResponse" theme={null}
use Avraapi\Laravel\Facades\AvraAPI;

// AvraAPI SDK call.
$response = AvraAPI::security()->checkVpn('203.0.113.10');

// Your application code.
$isVpn = $response->data['is_vpn'];
$countryCode = $response->data['country_code'];
$requestId = $response->requestId;
```

| `ApiResponse` property or helper | Use it for |
| - | - |
| `data` | The operation-specific result fields. |
| `meta` | Optional response metadata. |
| `requestId` | Support and troubleshooting correlation. |
| `httpStatus` | Successful HTTP status. |
| `get()` and `has()` | Reading nested values with dot notation. |

## Return generated media from a controller

Utilities can return `BinaryResponse` for PNG, SVG, or PDF output. Return its
body with its content type. A utility configured for Base64 returns
`ApiResponse` instead.

```php title="Return a generated QR image" theme={null}
<?php

namespace App\Http\Controllers;

use Avraapi\Apix\Responses\BinaryResponse;
use Avraapi\Laravel\Facades\AvraAPI;
use Illuminate\Http\Response;

final class QrCodeController extends Controller
{
    public function show(): Response
    {
        // AvraAPI SDK call.
        $result = AvraAPI::utilities()->generateQr('https://example.com');

        abort_unless($result instanceof BinaryResponse, 502, 'QR media was not returned.');

        // Your application code.
        return response($result->body, $result->httpStatus, [
            'Content-Type' => $result->contentType,
            'Content-Length' => (string) $result->size,
        ]);
    }
}
```

Use `isPdf()`, `isPng()`, or `isSvg()` before selecting a media-specific
workflow. The [Laravel Utility guide](/sdk/laravel/utility-services) documents
the underlying output choices and response modes.

## Use Privacy Mode for one provider request

All provider services inherit `withPrivacyMode()`. It sends
`X-Privacy-Mode: 1` for the next request only and then clears automatically.

```php title="Enable Privacy Mode for the next Security request" theme={null}
use Avraapi\Laravel\Facades\AvraAPI;

// AvraAPI SDK call.
$response = AvraAPI::security()
    ->withPrivacyMode()
    ->checkBurnerEmail('customer@example.com');
```

Privacy Mode keeps routing, billing, and usage tracking while applying the
platform privacy guarantee to request and response payload storage. It does
not make a request anonymous. The generic `AvraAPI::call()` method does not
offer this fluent control.

<Note>
  `lookupIp(..., privacyMode: true)` and the Utilities `privacyMode: true`
  arguments remain supported and use the same header. Prefer
  `withPrivacyMode()` for a consistent one-request style.
</Note>

## Handle errors safely

The Laravel package preserves the PHP SDK's typed exceptions. Catch a specific
exception where your application has a recovery path, then use
`ApixException` as the safe fallback.

```php title="Map an SDK failure to a Laravel response" theme={null}
use Avraapi\Apix\Exceptions\ApixException;
use Avraapi\Apix\Exceptions\ApixValidationException;
use Avraapi\Laravel\Facades\AvraAPI;

try {
    // AvraAPI SDK call.
    $response = AvraAPI::security()->checkBurnerEmail($email);
} catch (ApixValidationException $exception) {
    return response()->json([
        'message' => 'Check the submitted value.',
        'errors' => $exception->getValidationErrors(),
    ], 422);
} catch (ApixException $exception) {
    // Keep this only in backend logs or support records.
    report($exception);

    return response()->json([
        'message' => 'The service is temporarily unavailable.',
        'request_id' => $exception->getRequestId(),
    ], 503);
}
```

Never return a Client Secret, raw provider diagnostic, or sensitive exception
payload to a browser response. See the [REST API guide](/api-reference/rest-api)
for the standard AvraAPI response and error envelope.

## Universal Payment Gateway

The Laravel SDK exposes the server-side UPG service through
`AvraAPI::payment()` or an injected `ApixClient`. It uses the same typed
options and result objects as the PHP SDK. Your application still owns pending
orders, idempotency, callback routes, fulfilment, and final business decisions.

<Card title="Universal Payment Gateway documentation" icon="credit-card" href="/universal-payment-gateway/overview">
  Follow the canonical checkout lifecycle, Payment Elements, completion, and
  gateway-specific guides. Do not invent Laravel-specific payment routes,
  events, jobs, or queues that the SDK does not provide.
</Card>

## Next steps

<CardGroup cols={2}>
  <Card title="REST API Reference" icon="server" href="/api-reference/overview">
    Review provider request and response contracts.
  </Card>

  <Card title="Universal Payment Gateway" icon="credit-card" href="/universal-payment-gateway/overview">
    Build a server-authoritative payment integration.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.