> ## 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.

# PHP SDK overview and setup

> Install and configure the official AvraAPI PHP SDK for a secure backend integration.

The AvraAPI PHP SDK is the recommended integration path for PHP applications.
It adds your Project Client ID, Client Secret, and selected environment to each
request, then returns JSON as an `ApiResponse` or generated media as a
`BinaryResponse`.

<Note>
  This SDK runs in your backend. Never put a Project Client Secret in browser
  JavaScript, a mobile application, a public repository, or any client-facing
  configuration.
</Note>

## Requirements

| Requirement | Supported value |
| - | - |
| PHP | PHP 8.2 or later |
| Composer | Available in the backend application environment |
| Package | `avraapi/php-sdk` |
| HTTP client | Included through the package dependencies |
| Credentials | A Project Client ID and Client Secret from an AvraAPI project |

The current published PHP SDK release is **1.5.2**.

## Install the SDK

Run Composer from the backend application where you want to use AvraAPI:

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

After Composer finishes, import `Avraapi\Apix\ApixClient` from your
application code. The SDK has no Laravel dependency, so it can be used in a
plain PHP application or inside a framework.

## Configure project credentials

Create a project in AvraAPI, enable the services you need, then keep its
credentials in backend environment configuration. The SDK uses the following
names:

```ini title="Your backend environment configuration" theme={null}
APIX_PROJECT_KEY=your_project_client_id
APIX_API_SECRET=your_project_client_secret
APIX_ENV=development
```

`APIX_PROJECT_KEY` is the Project Client ID shown in AvraAPI. The SDK sends it
as the project authentication identifier. `APIX_API_SECRET` is the matching
Client Secret and must remain private.

The SDK does not load a `.env` file by itself. Use your framework, deployment
platform, or environment loader to make these values available through
`getenv()` or `$_ENV` before creating the client.

### Optional configuration

| Setting | Purpose | Default |
| - | - | - |
| `APIX_ENV` | Selects the project environment. `development` becomes `dev`; `production` becomes `prod`. | `dev` |
| `APIX_BASE_URL` | Overrides the AvraAPI base URL for an approved non-production environment. | `https://avraapi.com/api/v1` |
| `APIX_TIMEOUT` | Sets the full HTTP request timeout in seconds. | `30` |
| `APIX_CONNECT_TIMEOUT` | Sets the connection timeout in seconds. | `10` |

Keep the default base URL for a normal production integration. Explicit values
given to the client take priority over process environment values; process
environment values take priority over `$_ENV`.

## Create and reuse the client

Create one client after your application configuration is loaded, then reuse it
through your application container or service layer. Its service accessors are
lazy, so a service is only created when your application first uses it.

```php title="Environment-based setup" theme={null}
<?php

declare(strict_types=1);

use Avraapi\Apix\ApixClient;

// AvraAPI SDK call: reads APIX_PROJECT_KEY, APIX_API_SECRET, and APIX_ENV.
$avraapi = new ApixClient();
```

If your application already manages configuration in code, pass the values
explicitly. The PHP SDK accepts both the environment-style names above and the
camel-case aliases shown here.

```php title="Explicit setup" theme={null}
<?php

declare(strict_types=1);

use Avraapi\Apix\ApixClient;

// AvraAPI SDK call.
$avraapi = new ApixClient([
    'apiKey' => 'your_project_client_id',
    'apiSecret' => 'your_project_client_secret',
    'env' => 'development',
    'timeout' => 30,
    'connectTimeout' => 10,
]);
```

The Client ID and Client Secret are required. If either value cannot be found,
the client throws an `InvalidArgumentException` before a request is sent.

## Use Privacy Mode for one provider request

All PHP provider services support `withPrivacyMode()`. Call it immediately
before a provider operation when that one request needs the AvraAPI privacy
guarantee:

```php title="Enable Privacy Mode for the next request" theme={null}
<?php

// AvraAPI SDK call. The next Security request carries X-Privacy-Mode: 1.
$response = $avraapi->security()
    ->withPrivacyMode()
    ->checkBurnerEmail('customer@example.com');
```

The SDK automatically clears Privacy Mode after that request. It preserves
normal routing, billing, and usage tracking, while suppressing request and
response payload storage under the platform privacy guarantee. It does not
make the request anonymous. Use it only for provider-service calls; the
generic `call()` method does not accept this fluent option.

<Note>
  `lookupIp(..., privacyMode: true)` and the Utility methods' existing
  `privacyMode: true` arguments remain supported. They use the same
  `X-Privacy-Mode: 1` header. Prefer `withPrivacyMode()` for a consistent
  fluent style across every provider service.
</Note>

## Read a JSON response

Most provider services return an `ApiResponse`. It contains the full decoded
payload in `raw`, the operation result in `data`, optional metadata in `meta`,
the request trace identifier in `requestId`, and the HTTP status in
`httpStatus`.

```php title="Read a JSON result" theme={null}
<?php

// AvraAPI SDK call.
$response = $avraapi->currency()->getCodes();

// Your application code.
$codes = $response->data['codes'];
$requestId = $response->requestId;
```

Keep `requestId` with your application logs or support record. It is the safest
way to trace an AvraAPI request without storing sensitive request data.

| `ApiResponse` property | Use it for |
| - | - |
| `data` | The operation-specific result fields. |
| `meta` | Optional response metadata when the operation supplies it. |
| `requestId` | Support and troubleshooting correlation. |
| `httpStatus` | The successful HTTP response status. |
| `get()` and `has()` | Safely reading nested values with dot notation. |

## Handle generated files and images

Utilities can return a `BinaryResponse` for PNG, SVG, or PDF output. The
object contains the raw `body`, `contentType`, `size`, HTTP status, and an
optional `requestId`.

```php title="Save generated binary output" theme={null}
<?php

use Avraapi\Apix\Responses\BinaryResponse;

// AvraAPI SDK call. PNG is the default QR output format.
$response = $avraapi->utilities()->generateQr('https://example.com');

// Your application code.
if ($response instanceof BinaryResponse) {
    $savedPath = $response->saveAs(__DIR__.'/generated/qr-code.png');
}
```

`saveAs()` creates missing directories when it can. Use `isPdf()`, `isPng()`,
or `isSvg()` before selecting a media-specific application workflow. A utility
operation configured for Base64 returns `ApiResponse` instead; the Utilities
guide explains each output choice.

## Handle errors safely

The SDK throws typed exceptions for non-success API responses. Catch a specific
exception when your application has a clear recovery path, then use
`ApixException` as the common fallback.

```php title="Safe exception handling" theme={null}
<?php

use Avraapi\Apix\Exceptions\ApixException;
use Avraapi\Apix\Exceptions\ApixNetworkException;
use Avraapi\Apix\Exceptions\ApixValidationException;

try {
    // AvraAPI SDK call.
    $response = $avraapi->security()->checkBurnerEmail('customer@example.com');
} catch (ApixValidationException $exception) {
    // Your application code: show or record only the relevant field feedback.
    $fieldErrors = $exception->getValidationErrors();
} catch (ApixNetworkException $exception) {
    // Your application code: use a controlled retry policy when appropriate.
    $requestId = null;
} catch (ApixException $exception) {
    // Your application code: retain this ID for support without exposing details to users.
    $requestId = $exception->getRequestId();
}
```

| Exception | Typical reason | Recommended handling |
| - | - | - |
| `ApixAuthenticationException` | HTTP `401`: Client ID, Client Secret, project state, or environment does not match. | Correct configuration; do not retry unchanged credentials. |
| `ApixInsufficientFundsException` | HTTP `402`: the project cannot cover a billable request. | Restore the project balance before retrying. |
| `ApixValidationException` | HTTP `422`: request data is invalid. | Read `getValidationErrors()`, correct the input, and send a new request. |
| `ApixRateLimitException` | HTTP `429`: the configured rate limit was reached. | Back off and respect `Retry-After` when present. |
| `ApixServiceUnavailableException` | HTTP `503`: the project or service is unavailable. | Retry only when your workflow permits it. |
| `ApixNetworkException` | No usable response reached the SDK. | Check connectivity and use a controlled retry policy. |

Never return a Client Secret, raw exception payload, or provider diagnostic to a
browser response.

## Universal Payment Gateway

UPG is currently supported through the PHP SDK. Payment initiation, completion,
and provider-specific operations are server-side work. Keep payment completion
and sensitive callback handling in your backend, and use the dedicated payment
documentation for the complete flow.

<Card title="Universal Payment Gateway documentation" icon="credit-card" href="/universal-payment-gateway/overview">
  Read the payment lifecycle, Quick Setup, advanced integration guidance, and
  gateway-specific capabilities.
</Card>

## Next steps

Use the service guides for method-level inputs and output details, or use the
[REST API Reference](/api-reference/overview) when you need direct HTTP control
for a released provider operation.


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