> ## 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 utility services

> Use the AvraAPI Laravel SDK to generate QR codes, barcodes, and PDFs.

Use `AvraAPI::utilities()` for the four released Utility operations. Image and
binary-PDF modes return `BinaryResponse`; Base64 modes return `ApiResponse`.
Choose the response type before you write application handling code.

The Laravel package discovers the `AvraAPI` Facade alias automatically. Import
`Avraapi\Laravel\Facades\AvraAPI` when you prefer an explicit dependency for
IDE and static-analysis support.

<Note>
  Generated output can contain customer or business data. Keep Utility calls
  and generated media in your backend. Use
  `AvraAPI::utilities()->withPrivacyMode()` immediately before an operation
  when the request needs the shared AvraAPI privacy guarantee. It sends
  `X-Privacy-Mode: 1` only for the next request and then clears automatically.
  Existing `privacyMode: true` method arguments remain supported.
</Note>

## Generate a QR code

`generateQr()` accepts text, a URL, or a vCard value. Its complete signature is:

**SDK function**

```php title="Copy the SDK call" theme={null}
$response = AvraAPI::utilities()->generateQr(
    data: 'QR_CONTENT',
);
```

| Argument | Use |
| - | - |
| `data` | Text, URL, or vCard value to encode. |

Optional `format`, size, colour, logo, and privacy settings are available in
the full signature below.

```php theme={null}
generateQr(
    string $data,
    string $format = 'png',
    ?int $size = null,
    ?string $foregroundColor = null,
    ?string $backgroundColor = null,
    ?string $logoUrl = null,
    ?int $logoSizePercent = null,
    bool $privacyMode = false,
): ApiResponse|BinaryResponse
```

Use `png` (the default) or `svg` for `BinaryResponse`; use `base64` for an
`ApiResponse` containing a PNG data URI.

```php title="Return a styled PNG QR code from Laravel" theme={null}
<?php

use Avraapi\Apix\Responses\BinaryResponse;
use Avraapi\Laravel\Facades\AvraAPI;

// AvraAPI SDK call.
$response = AvraAPI::utilities()->generateQr(
    data: 'https://example.com/receipt/ORDER-2026-001',
    format: 'png',
    size: 400,
    foregroundColor: '0450ff',
    backgroundColor: 'ffffff',
    logoUrl: 'https://example.com/brand-mark.png',
    logoSizePercent: 20,
    privacyMode: true,
);

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

### PNG or SVG response

For `png`, the success body is the PNG bytes with `Content-Type: image/png`.
For `svg`, it is SVG media with `Content-Type: image/svg+xml`. The SDK exposes
the exact body in `$response->body`, MIME type in `$response->contentType`,
byte count in `$response->size`, and the optional request trace in
`$response->requestId`.

```php title="Read a Base64 QR response" theme={null}
<?php

use Avraapi\Apix\Responses\ApiResponse;
use Avraapi\Laravel\Facades\AvraAPI;

// AvraAPI SDK call.
$response = AvraAPI::utilities()->generateQr(
    data: 'https://example.com/receipt/ORDER-2026-001',
    format: 'base64',
);

// Your application code.
if ($response instanceof ApiResponse) {
    $dataUri = $response->data['data_uri'];
}
```

### Base64 response

```json theme={null}
{
  "success": true,
  "request_id": "01f00000-0000-4000-8000-000000000021",
  "data": {
    "format": "base64",
    "data_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
  }
}
```

`logoUrl` must be a public HTTP or HTTPS image that AvraAPI can fetch. It is
applied to PNG and Base64 output; SVG does not include the logo. See
[Generate a QR code](/api-reference/utilities/qr-generate) for validation and
media-response details.

## Generate a barcode

`generateBarcode()` always returns `BinaryResponse`; barcode generation has no
Base64 SDK response mode.

**SDK function**

```php title="Copy the SDK call" theme={null}
$response = AvraAPI::utilities()->generateBarcode(
    data: 'BARCODE_CONTENT',
);
```

| Argument | Use |
| - | - |
| `data` | Value to encode in the selected barcode type. |

Optional barcode type, media format, dimensions, and privacy settings are
available in the full signature below.

```php theme={null}
generateBarcode(
    string $data,
    string $type = 'C128',
    string $format = 'png',
    ?int $height = null,
    float|int|null $widthFactor = null,
    bool $privacyMode = false,
): BinaryResponse
```

The SDK exposes the `type`, `format`, `height`, `widthFactor`, and
`privacyMode` options shown above. `C128` and `png` are the defaults.

```php title="Return a barcode image from Laravel" theme={null}
<?php

use Avraapi\Laravel\Facades\AvraAPI;

// AvraAPI SDK call.
$response = AvraAPI::utilities()->generateBarcode(
    data: 'ORDER-2026-001',
    type: 'C128',
    format: 'png',
    height: 80,
    widthFactor: 2,
);

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

### PNG or SVG response

For `png`, the successful response body is barcode media with
`Content-Type: image/png`; for `svg`, it is `image/svg+xml`. Do not try to read
the media body as JSON. Use `saveAs()`, send `$response->body` into your own
image response, or use `toDataUri()` when your backend needs to embed it.

The full barcode type list and type-specific validation rules are in
[Generate a barcode](/api-reference/utilities/barcode-generate).

## Generate a PDF from HTML

`generatePdf()` renders HTML to a PDF. Use `binary` (the default) for
`BinaryResponse`, or `base64` for JSON with Base64 PDF bytes.

**SDK function**

```php title="Copy the SDK call" theme={null}
$response = AvraAPI::utilities()->generatePdf(
    html: '<html><body>Document content</body></html>',
);
```

| Argument | Use |
| - | - |
| `html` | HTML document or fragment to render. |

Optional response type, page, margin, encoding, and privacy settings are
available in the full signature below.

```php theme={null}
generatePdf(
    string $html,
    string $responseType = 'binary',
    string $pageSize = 'A4',
    string $orientation = 'portrait',
    ?array $margins = null,
    bool $isBase64 = false,
    bool $privacyMode = false,
): ApiResponse|BinaryResponse
```

`$margins` accepts `top`, `right`, `bottom`, and `left` values in millimetres.
When `$isBase64` is true, pass a Base64-encoded HTML value as `$html`.

```php title="Return a binary PDF from Laravel" theme={null}
<?php

use Avraapi\Apix\Responses\BinaryResponse;
use Avraapi\Laravel\Facades\AvraAPI;

// AvraAPI SDK call.
$response = AvraAPI::utilities()->generatePdf(
    html: '<html><body><h1>Order receipt</h1></body></html>',
    responseType: 'binary',
    pageSize: 'A4',
    orientation: 'portrait',
    margins: ['top' => 15, 'right' => 15, 'bottom' => 15, 'left' => 15],
    privacyMode: true,
);

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

### Binary PDF response

With `responseType: 'binary'`, the success body is PDF media with
`Content-Type: application/pdf`. The `BinaryResponse` exposes the raw PDF as
`body`; it is not a JSON object.

```php title="Read a Base64 PDF response" theme={null}
<?php

use Avraapi\Apix\Responses\ApiResponse;
use Avraapi\Laravel\Facades\AvraAPI;

// AvraAPI SDK call.
$response = AvraAPI::utilities()->generatePdf(
    html: '<html><body><h1>Order receipt</h1></body></html>',
    responseType: 'base64',
    privacyMode: true,
);

// Your application code.
if ($response instanceof ApiResponse) {
    $base64Pdf = $response->data['data'];
    $mediaType = $response->data['media_type'];
}
```

### Base64 response

```json theme={null}
{
  "success": true,
  "request_id": "abd340d9-2491-4403-b076-51f395048c8d",
  "data": {
    "format": "base64",
    "media_type": "application/pdf",
    "data": "JVBERi0xLjcKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZw..."
  }
}
```

The Base64 value is document data, not a download URL. Decode and store or
stream it only in a protected application context. See
[Generate a PDF](/api-reference/utilities/pdf-generate) for the complete HTML,
privacy, and response contract.

## Generate a PDF from raw HTML with Base64 transport

`generatePdfFromBase64()` is a convenience wrapper for complex HTML. Pass raw,
unencoded HTML; the SDK Base64-encodes it and calls `generatePdf()` with
`isBase64: true`.

**SDK function**

```php title="Copy the SDK call" theme={null}
$response = AvraAPI::utilities()->generatePdfFromBase64(
    html: '<html><body>Document content</body></html>',
);
```

| Argument | Use |
| - | - |
| `html` | Raw HTML; do not encode it yourself. |

Optional response type, page, margin, and privacy settings are available in
the full signature below.

```php theme={null}
generatePdfFromBase64(
    string $html,
    string $responseType = 'binary',
    string $pageSize = 'A4',
    string $orientation = 'portrait',
    ?array $margins = null,
    bool $privacyMode = false,
): ApiResponse|BinaryResponse
```

```php title="Render complex HTML without manual encoding" theme={null}
<?php

use Avraapi\Apix\Responses\BinaryResponse;
use Avraapi\Laravel\Facades\AvraAPI;

// Your application code: raw HTML, not Base64 text.
$html = view('pdf.receipt', ['order' => $order])->render();

// AvraAPI SDK call.
$response = AvraAPI::utilities()->generatePdfFromBase64(
    html: $html,
    privacyMode: true,
);

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

### Response

The response follows the same documented binary or Base64 shapes as
`generatePdf()`, selected by `responseType`. Use the binary PDF handling or
Base64 JSON handling above; do not Base64-encode the HTML yourself before
calling this convenience method.

## Handle Utility errors

All Utility methods throw typed SDK exceptions for non-success responses. Keep
the request ID when available, avoid placing generated customer data into logs,
and use the shared pattern in [Laravel Overview and setup](/sdk/laravel/overview-and-setup#handle-errors-safely).


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