Laravolt Avatar

https://github.com/laravolt/avatar
Admin
A Laravel package that generates unique avatars based on user initials, supporting multiple output...
Tokens:39,431
Snippets:319
Trust Score:9.1
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Usage Examples

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/generators.md

Examples of using the default generator directly and creating a custom generator via the interface.

```APIDOC
## Usage Examples

### Default Generator

```php
use Laravolt\Avatar\Generator\DefaultGenerator;

$generator = new DefaultGenerator();

echo $generator->make('Joko Widodo');            // "JW"
echo $generator->make('Joko Widodo', 2, true);   // "JW"
echo $generator->make('Laravolt', 3);            // "Lar"
echo $generator->make('bayu.hendra@gmail.com');  // "BH"
echo $generator->make('Ali', 2, false, false, true); // reversed if rtl
```

### Custom Generator via Interface

```php
use Laravolt\Avatar\Generator\GeneratorInterface;

class MyGenerator implements GeneratorInterface
{
    public function make(?string $name, int $length, bool $uppercase, bool $ascii, bool $rtl): string
    {
        $initials = strtoupper(substr((string) $name, 0, $length));
        return $initials;
    }
}

use Laravolt\Avatar\Avatar;
$avatar = new Avatar();
$avatar->setGenerator(new MyGenerator());
```

### Via Configuration

```php
$config = [
    'generator' => \App\Avatar\MyGenerator::class,
];
$avatar = new Avatar($config);
```
```

--------------------------------

### Usage Examples

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar-response.md

Examples demonstrating usage of the HDAvatarResponse class.

```APIDOC
## Usage Examples

### Basic Usage
```php
use Laravolt\Avatar\HDAvatarResponse;

$avatar = new HDAvatarResponse([
    'hd' => ['enabled' => true, 'width' => 1024, 'height' => 1024, 'fontSize' => 384],
    'export' => ['path' => 'avatars'],
    'responsive_sizes' => [
        'small'  => ['width' => 128, 'height' => 128, 'fontSize' => 48],
        'large'  => ['width' => 512, 'height' => 512, 'fontSize' => 192],
    ],
]);

$avatar->createHD('Michael Chen');

$pngPath = $avatar->export('png');                       // avatars/<hash>_<ts>.png
$files   = $avatar->exportMultiple(['png', 'jpg', 'webp']);
$sizes   = $avatar->exportResponsive('webp');
$placeholder = $avatar->toPlaceholder(32, 32);           // data URI
```

### Error Handling for Unsupported Format
```php
try {
    $avatar->export('bmp');
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // "Unsupported format: bmp"
}
```

### Serving as HTTP Response in Laravel Controller
```php
return $avatar->createHD('Jane Doe')->toResponse('png');
```
```

--------------------------------

### Quick start: Create avatar instance and generate image

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/README.md

Shows how to instantiate the Avatar class with a config array, create an avatar from a name, and output it as Base64, SVG, or save to a file. This is plain PHP usage outside Laravel.

```php
use Laravolt\Avatar\Avatar;

$avatar = new Avatar($config);           // plain PHP
$avatar->create('Joko Widodo');

echo $avatar->toBase64();                 // data:image/png;base64,...
echo $avatar->toSvg();                    // <svg ...>
$avatar->save('sample.png', 90);
```

--------------------------------

### Usage example for HDAvatarResponse

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar-response.md

Shows how to instantiate HDAvatarResponse with HD, export, and responsive size configuration, then create an HD avatar and export it in various formats. The export path is `avatars/<hash>_<ts>.png` and `toPlaceholder` returns a data URI.

```php
use Laravolt\Avatar\HDAvatarResponse;

$avatar = new HDAvatarResponse([
    'hd' => ['enabled' => true, 'width' => 1024, 'height' => 1024, 'fontSize' => 384],
    'export' => ['path' => 'avatars'],
    'responsive_sizes' => [
        'small'  => ['width' => 128, 'height' => 128, 'fontSize' => 48],
        'large'  => ['width' => 512, 'height' => 512, 'fontSize' => 192],
    ],
]);

$avatar->createHD('Michael Chen');

$pngPath = $avatar->export('png');                       // avatars/<hash>_<ts>.png
$files   = $avatar->exportMultiple(['png', 'jpg', 'webp']);
$sizes   = $avatar->exportResponsive('webp');
$placeholder = $avatar->toPlaceholder(32, 32);           // data URI
```

--------------------------------

### Install laravolt/avatar with Composer

Source: https://github.com/laravolt/avatar/blob/master/README.md

Install the laravolt/avatar package via Composer. The service provider and Avatar facade are registered automatically via package auto-discovery.

```bash
composer require laravolt/avatar
```

--------------------------------

### Facade usage example

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/providers-facade.md

Shows how to use the Avatar facade inside a Laravel application. Creates an avatar for 'Joko Widodo' and outputs it as base64.

```php
// Controller / view
$avatar = Avatar::create('Joko Widodo');   // resolves 'avatar' from container
echo $avatar->toBase64();
```

--------------------------------

### Container resolution example

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/providers-facade.md

Resolves the 'avatar' and 'avatar.generator' bindings from the container.

```php
$avatar = app('avatar');                    // instanceof Laravolt\Avatar\Avatar
$generator = app('avatar.generator');       // instanceof GeneratorInterface
```

--------------------------------

### Save Avatar as File

Source: https://github.com/laravolt/avatar/blob/master/README.md

Saves the generated avatar to a file. The second example saves as JPEG with a quality parameter of 100.

```php
Avatar::create('Susilo Bambang Yudhoyono')->save('sample.png');
Avatar::create('Susilo Bambang Yudhoyono')->save('sample.jpg', 100); // quality = 100
```

--------------------------------

### ServiceProvider::boot() method

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/providers-facade.md

Calls registerConfigurations() during boot.

```php
public function boot()
```

--------------------------------

### configureStorage

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/concerns.md

Sets storage settings and re-initializes storage.

```APIDOC
## configureStorage(string $disk, string $directory, int $maxSizeMB = 500): static

### Description
Sets storage settings and re-initializes storage.

### Parameters
- **$disk** (string) - Required - Storage disk name.
- **$directory** (string) - Required - Storage directory.
- **$maxSizeMB** (int) - Optional - Max storage in MB. Default: 500.

### Return Value
- **static** - Returns `$this`.

### Source
`src/Concerns/StorageOptimization.php:469`
```

--------------------------------

### create

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/avatar.md

Sets the active name and re-initializes the theme based on the name hash, returning the instance for chaining.

```APIDOC
## `create`

### Description
Sets the active name and re-initializes the theme, randomly picking background, foreground, and font from configured pools based on the name hash. Returns the instance for chaining.

### Method
`create`

### Signature
`public function create(string $name): static`

### Parameters
#### Required Parameters
- **$name** (`string`) - Required - The name, email, or arbitrary string to base the avatar on.

### Return Value
- `static` - The current instance for chaining.

### Source
`src/Avatar.php:131`

```

--------------------------------

### Constructor

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/avatar.md

Creates a new Avatar instance with optional configuration and cache repository. Merges user config over defaults, resolves a named theme, and derives effective rendering settings.

```APIDOC
## Constructor

### Description
Creates a new Avatar instance with optional configuration and cache repository. Merges user config over defaults, resolves a named theme, and derives effective rendering settings.

### Method
__construct

### Signature
```php
public function __construct(array $config = [], ?Repository $cache = null)
```

### Parameters
- **$config** (array) - Optional - Configuration array (same shape as `config/config.php`). Keys consumed directly: `driver`, `theme`, `cache`, `themes`.
- **$cache** (\Illuminate\Contracts\Cache\Repository) - Optional - Cache repository used to memoize base64 output. Defaults to `null` (falls back to `new ArrayStore`).

### Behavior
- Sets `cache` (falls back to `ArrayStore`), `driver` (default `'gd'`), `theme`.
- Builds `defaultTheme` via `validateConfig()` and applies it.
- Instantiates `DefaultGenerator`.
- Reads the `cache` sub-array (`enabled`, `key_prefix`, `duration`).
- Registers any themes resolved from the `'*'` wildcard over `config['themes']`.
- Calls `initTheme()`.

### Source
`src/Avatar.php:93`
```

--------------------------------

### Catch InvalidArgumentException for unsupported export format

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/errors.md

Catches \InvalidArgumentException when exporting an unsupported format. The example uses 'bmp' and outputs "Unsupported format: bmp".

```php
use Laravolt\Avatar\HDAvatarResponse;

$avatar = new HDAvatarResponse();
$avatar->createHD('Jane Smith');

try {
    $avatar->export('bmp');
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // "Unsupported format: bmp"
}
```

--------------------------------

### Catch InvalidArgumentException for unsupported shape

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/errors.md

Catches the \InvalidArgumentException thrown when an unsupported shape is configured. The example uses 'triangle' and outputs the message "Shape [triangle] currently not supported."

```php
use Laravolt\Avatar\Avatar;

try {
    $avatar = new Avatar(['shape' => 'triangle']);
    $avatar->create('John Doe')->toBase64();
} catch (\InvalidArgumentException $e) {
    // "Shape [triangle] currently not supported."
    echo $e->getMessage();
}
```

--------------------------------

### ServiceProvider::provides() method

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/providers-facade.md

Returns the list of container bindings provided by the service provider: 'avatar' and 'avatar.generator'.

```php
public function provides()
```

--------------------------------

### Get Intervention image object with Avatar::create()->getImageObject()

Source: https://github.com/laravolt/avatar/blob/master/README.md

Retrieves the underlying Intervention image object from an avatar instance for further processing. The returned object is an instance of the Intervention image object (v4).

```php
Avatar::create('Abdul Somad')->getImageObject();
```

--------------------------------

### Constructor

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar.md

Initializes the HDAvatar instance with optional configuration and cache repository. It ensures storage directory exists and configures storage settings if provided.

```APIDOC
## Constructor

### Description
Initializes the HDAvatar instance with optional configuration and cache repository. It ensures storage directory exists and configures storage settings if provided.

### Method
Constructor

### Signature
```php
public function __construct(array $config = [], ?Repository $cache = null)
```

### Parameters
- **$config** (array) - Optional - Configuration array. Consumes the `storage` key in addition to all parent config keys.
- **$cache** (\Illuminate\Contracts\Cache\Repository) - Optional - Cache repository, passed to the parent.

### Behavior
- Calls `initializeStorage()` to ensure the storage directory exists and load metrics.
- If `config['storage']` is present, calls `configureStorage()` with `disk` (default `'local'`), `directory` (default `'avatars'`), and `max_storage_mb` (default `500`); then sets `max_age_days` (default `30`) and `compression` (default `true`).

### Source
`src/HDAvatar.php:19`
```

--------------------------------

### Using DefaultGenerator directly

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/generators.md

Shows how to use the default generator directly. The comments indicate expected outputs for each call.

```php
use Laravolt\Avatar\Generator\DefaultGenerator;

$generator = new DefaultGenerator();

echo $generator->make('Joko Widodo');            // "JW"
echo $generator->make('Joko Widodo', 2, true);   // "JW"
echo $generator->make('Laravolt', 3);            // "Lar"
echo $generator->make('bayu.hendra@gmail.com');  // "BH"
echo $generator->make('Ali', 2, false, false, true); // reversed if rtl
```

--------------------------------

### ServiceProvider::registerConfigurations() method

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/providers-facade.md

Merges and publishes configuration files. Merges config/config.php into 'laravolt.avatar' and publishes it to config/laravolt/avatar.php. Also merges config/config-hd.php into 'laravolt.avatar.hd' and publishes it to config/laravolt/avatar-hd.php, both under the 'config' tag.

```php
protected function registerConfigurations()
```

--------------------------------

### optimizeStorage(): array

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar.md

Runs performCleanup() and returns before/after storage statistics plus an optimization summary, including files removed, space saved, and optimization percentage.

```APIDOC
## optimizeStorage

### Description
Runs cleanup and returns storage statistics and optimization summary.

### Method
PHP

### Signature
public function optimizeStorage(): array

### Parameters
None.

### Returns
Returns an array with the following structure:

```php
[
    'before' => array,   // getStorageStatistics()
    'after'  => array,
    'cleaned' => [ 'old_files' => array, 'large_files' => array, 'duplicate_files' => array ],
    'optimization_summary' => [
        'files_removed' => int,
        'space_saved_mb' => float,
        'optimization_percentage' => float,
    ],
]
```
```

--------------------------------

### toPlaceholder

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar-response.md

Builds a small blurred PNG placeholder and returns it as a data-URI string.

```APIDOC
## `toPlaceholder`

```php
public function toPlaceholder(int $width = 64, int $height = 64): string
```

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$width` | `int` | No | `64` | Placeholder width. |
| `$height` | `int` | No | `64` | Placeholder height. |

Builds a small blurred PNG placeholder (blur radius 5), returned as a **data-URI** string. Original dimensions and font size are restored afterward.

**Source:** `src/HDAvatarResponse.php:303`
```

--------------------------------

### Configure custom generator via config

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/generators.md

Shows how to configure a custom generator by passing a configuration array with the 'generator' key pointing to the class name.

```php
$config = [
    'generator' => \App\Avatar\MyGenerator::class,
];
$avatar = new Avatar($config);
```

--------------------------------

### Constructor

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar-response.md

Constructor for the HDAvatarResponse class, initializing configuration and cache.

```APIDOC
## Constructor

### Description
Initializes a new HDAvatarResponse instance with optional configuration and cache repository.

### Method
Constructor

### Signature
`public function __construct(array $config = [], ?Repository $cache = null)`

### Parameters
- **$config** (array) - Optional - Configuration array. Consumes the `hd`, `responsive_sizes`, and `export` keys.
- **$cache** (?\Illuminate\Contracts\Cache\Repository) - Optional - Cache repository, passed to the parent `Avatar`.

### Behavior
- Reads `hd` config into `$this->hdConfig` and `$this->hdEnabled` (default `true`).
- Reads `responsive_sizes` into `$this->responsiveSizes` (default `[]`).
- Reads `export.path` into `$this->exportPath` (default `'avatars'`).
- If HD is enabled, applies HD defaults (`width` 512, `height` 512, `fontSize` 192, `driver` `'imagick'` — each overridable via `hd.*`).
- Delegates to the parent constructor.

### Source
`src/HDAvatarResponse.php:27`
```

--------------------------------

### HD avatar creation method

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar-response.md

Sets the avatar name and re-initializes the theme. Returns the current instance for chaining.

```php
public function createHD(string $name): static
```

--------------------------------

### applyTheme

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/avatar.md

Applies all visual attributes from a configuration array onto the avatar instance.

```APIDOC
## `applyTheme`

### Description
Applies all visual attributes from a config array onto the instance, including shape, chars, backgrounds, foregrounds, fonts, fontSize, width, height, responsive, ascii, uppercase, rtl, and border settings.

### Method
`applyTheme`

### Signature
`public function applyTheme(array $config): void`

### Parameters
#### Required Parameters
- **$config** (`array`) - Required - Theme/config array; validated via `validateConfig()`.

### Return Value
- `void`

### Source
`src/Avatar.php:140`

```

--------------------------------

### Custom generator via interface and setGenerator

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/generators.md

Demonstrates creating a custom generator by implementing GeneratorInterface and setting it on an Avatar instance via setGenerator().

```php
use Laravolt\Avatar\Generator\GeneratorInterface;

class MyGenerator implements GeneratorInterface
{
    public function make(?string $name, int $length, bool $uppercase, bool $ascii, bool $rtl): string
    {
        $initials = strtoupper(substr((string) $name, 0, $length));
        return $initials;
    }
}

use Laravolt\Avatar\Avatar;
$avatar = new Avatar();
$avatar->setGenerator(new MyGenerator());
```

--------------------------------

### storeOptimized

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/concerns.md

Builds and saves an optimized avatar to storage, returning the storage URL.

```APIDOC
## storeOptimized(string $name, string $format = 'png', array $options = []): string

### Description
Builds, compresses (if enabled), saves to storage, updates metrics, and checks storage limits. Returns the storage URL.

### Parameters
- **$name** (string) - Required - Name to render.
- **$format** (string) - Optional - Export format. Default: 'png'.
- **$options** (array) - Optional - Format options (`interlaced`, `quality`, `progressive`, `strip`). Default: [].

### Return Value
- **string** - The storage URL.

### Source
`src/Concerns/StorageOptimization.php:54`
```

--------------------------------

### optimizeStorage method signature and return array

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar.md

Method signature and return structure for optimizeStorage. Runs performCleanup() and returns before/after storage statistics plus an optimization summary.

```php
public function optimizeStorage(): array
```

```php
[
    'before' => array,   // getStorageStatistics()
    'after'  => array,
    'cleaned' => [ 'old_files' => array, 'large_files' => array, 'duplicate_files' => array ],
    'optimization_summary' => [
        'files_removed' => int,
        'space_saved_mb' => float,
        'optimization_percentage' => float,
    ],
]
```

--------------------------------

### HDAvatar storage configuration and optimization

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar.md

Configures storage with a local disk, enables compression, sets a maximum file age of 14 days, and retrieves storage statistics. If usage exceeds 80%, it optimizes storage and prints the number of removed files from the optimization summary.

```php
$hd->configureStorage('local', 'optimized-avatars', 1000);
$hd->setCompressionEnabled(true);
$hd->setMaxFileAge(14);

$stats = $hd->getStorageStatistics();
if ($stats['usage_percentage'] > 80) {
    $optimization = $hd->optimizeStorage();
    echo 'Removed '.$optimization['optimization_summary']['files_removed'].' files';
}
```

--------------------------------

### Publishing config command

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/providers-facade.md

Publishes the package configuration using the artisan vendor:publish command with the provider specified.

```bash
php artisan vendor:publish --provider="Laravolt\Avatar\ServiceProvider"
```

--------------------------------

### getForeground method signature

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/concerns.md

Returns the current foreground color as a hex string.

```php
public function getForeground(): string
```

--------------------------------

### HDAvatar usage: fluent setters, image export, and storage optimization

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/concerns.md

Shows how to instantiate HDAvatar, use fluent setters to customize the avatar (dimensions, colors, font size, shape, border, and character count), export images in various formats with options, and leverage storage optimization methods like configureStorage, storeOptimized, and getStorageStatistics.

```php
use Laravolt\Avatar\HDAvatar;

$avatar = new HDAvatar();

// Fluent setters (from AttributeSetter)
$avatar->create('Soekarno')
    ->setDimension(100, 200)
    ->setBackground('#001122')
    ->setForeground('#999999')
    ->setFontSize(72)
    ->setShape('square')
    ->setBorder(2, '#aabbcc', 10)
    ->setChars(3);

// Image export
$avatar->exportImage('/tmp/a.png', 'png', ['interlaced' => true]);
$avatar->exportWithWatermark('/tmp/wm.jpg', 'Copyright', 'jpg', ['watermark' => ['position' => 'center']]);
$sizes = $avatar->exportResponsiveSizes('/tmp/base', [
    'thumb' => ['width' => 64, 'height' => 64],
    'large' => ['width' => 512, 'height' => 512, 'fontSize' => 192],
]);

// Storage optimization
$avatar->configureStorage('local', 'my-avatars', 200);
$url = $avatar->storeOptimized('Jane Doe', 'webp', ['quality' => 80]);
$stats = $avatar->getStorageStatistics();
```

--------------------------------

### exportAllFormats

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar.md

Creates an HD avatar and exports it in png, jpg, and webp formats, returning URLs for each format.

```APIDOC
## exportAllFormats

### Description
Creates an HD avatar and exports it in `png`, `jpg`, and `webp`. Returns an array with URLs for each format.

### Method
exportAllFormats

### Endpoint
`public function exportAllFormats(string $name, array $options = []): array`

### Parameters
- **$name** (string) - Required - Name to render.
- **$options** (array) - Optional - Options forwarded to `storeOptimized()`. Default: `[]`.

### Response
#### Success Response
Returns an array with the following structure:
```php
[
    'png'  => ['url' => string, 'cached_url' => string],
    'jpg'  => ['url' => string, 'cached_url' => string],
    'webp' => ['url' => string, 'cached_url' => string],
]
```
```

--------------------------------

### getAvatarInfo(string $name): array

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar.md

Creates an avatar from the provided name and returns a comprehensive info array containing initials, dimensions, styling, configuration, performance, hash, and estimated file sizes.

```APIDOC
## getAvatarInfo

### Description
Creates the avatar and returns a comprehensive info array.

### Method
PHP

### Signature
public function getAvatarInfo(string $name): array

### Parameters
- **$name** (string) - Required - Name to render.

### Returns
Returns an array with the following structure:

```php
[
    'name' => string,
    'initials' => string,
    'dimensions' => ['width' => int, 'height' => int],
    'styling' => [
        'background' => string, 'foreground' => string,
        'font_size' => float, 'shape' => string,
        'border' => ['size' => int, 'color' => string, 'radius' => int],
    ],
    'configuration' => [
        'hd_enabled' => bool, 'responsive_sizes' => array,
        'export_path' => string,
    ],
    'performance' => [
        'cache_enabled' => bool, 'compression_enabled' => bool,
        'storage_disk' => string,
    ],
    'hash' => string,
    'estimated_file_sizes' => [ 'png' => string, 'jpg' => string, 'webp' => string ],
]
```
```

--------------------------------

### createAndExport

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar.md

Creates an HD avatar, stores it optimized, and returns an array containing the name, format, storage URL, responsive URLs (if configured), and metadata including dimensions, font size, colors, and hash.

```APIDOC
## createAndExport

### Description
Creates an HD avatar, stores it optimized, and returns an array containing the name, format, storage URL, responsive URLs (if configured), and metadata including dimensions, font size, colors, and hash.

### Method
createAndExport

### Signature
```php
public function createAndExport(string $name, string $format = 'png', array $options = []): array
```

### Parameters
- **$name** (string) - Required - Name to render.
- **$format** (string) - Optional - Export format. Default: `'png'`.
- **$options** (array) - Optional - Options forwarded to `storeOptimized()`.

### Return Value
Returns an array with the following structure:
```php
[
    'name' => string,
    'format' => string,
    'url' => string,                    // storage URL
    'responsive_urls' => [ size => url, ... ], // only if responsiveSizes configured
    'metadata' => [
        'width' => int, 'height' => int,
        'font_size' => float, 'background' => string,
        'foreground' => string, 'hash' => string,
    ],
]
```

### Source
`src/HDAvatar.php:43`
```

--------------------------------

### setTheme

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/concerns.md

Sets the active theme(s) and re-initializes. Accepts a string or array of theme names. Returns $this for chaining.

```APIDOC
## setTheme

### Description
Sets the active theme(s) and re-initializes. If a string is given but is not a registered theme key, it is ignored. For arrays, every string entry is used; non-strings are skipped. Then `initTheme()` runs. Returns `$this`.

### Method
`setTheme`

### Signature
```php
public function setTheme($theme): static
```

### Parameters
- `$theme` (string|array) - Required - A theme name or array of theme names.

### Return Value
`static` - Returns `$this` for chaining.

### Source
`src/Concerns/AttributeSetter.php:9`
```

--------------------------------

### Avatar constructor signature

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/avatar.md

The constructor accepts an optional configuration array and an optional cache repository. It merges user config over defaults, resolves a theme, and initializes the generator.

```php
public function __construct(array $config = [], ?Repository $cache = null)
```

--------------------------------

### createAndExport return array structure

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar.md

Return array structure for createAndExport. Includes name, format, storage URL, responsive URLs (only if responsiveSizes configured), and metadata with dimensions, font size, colors, and hash.

```php
[
    'name' => string,
    'format' => string,
    'url' => string,                    // storage URL
    'responsive_urls' => [ size => url, ... ], // only if responsiveSizes configured
    'metadata' => [
        'width' => int, 'height' => int,
        'font_size' => float, 'background' => string,
        'foreground' => string, 'hash' => string,
    ],
]
```

--------------------------------

### getInitial

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/avatar.md

Returns the current initials string that was populated by `buildInitial()`.

```APIDOC
## getInitial

### Description
Returns the current initials string that was populated by `buildInitial()`.

### Method
PHP method

### Endpoint
`public function getInitial(): string`

### Returns
- string - The current initials string.

### Source
`src/Avatar.php:315`
```

--------------------------------

### setMaxFileAge

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/concerns.md

Sets the cleanup age threshold in days.

```APIDOC
## setMaxFileAge(int $days): static

### Description
Sets the cleanup age threshold in days.

### Parameters
- **$days** (int) - Required - Age threshold in days.

### Return Value
- **static** - Returns `$this`.

### Source
`src/Concerns/StorageOptimization.php:493`
```

--------------------------------

### Basic base64 output in a view

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/avatar.md

Creates an avatar with custom width, height, character count, and uppercase settings, then outputs it as base64 or SVG.

```php
use Laravolt\Avatar\Avatar;

$config = [
    'width' => 100,
    'height' => 100,
    'chars' => 2,
    'uppercase' => true,
];

$avatar = new Avatar($config);
$avatar->create('Joko Widodo');

echo $avatar->toBase64(); // data:image/png;base64,...
echo $avatar->toSvg();    // <svg ...>JW</svg>
```

--------------------------------

### exportResponsiveSizes method signature

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/concerns.md

Exports the avatar at multiple sizes. Returns a map of size name to file path.

```php
public function exportResponsiveSizes(string $basePath, array $sizes, string $format = 'png'): array
```

--------------------------------

### getForeground

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/concerns.md

Returns the current foreground color as a hex string.

```APIDOC
## getForeground

### Description
Returns the current foreground color (hex string).

### Method
`getForeground(): string`

### Returns
- **string** - The current foreground color as a hex string.

### Source
`src/Concerns/AttributeGetter.php:25`
```

--------------------------------

### apiResponse(string $name, string $format = 'png', string $size = 'medium')

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar.md

Renders an avatar based on the provided name and returns an API-shaped array containing avatar and metadata information. The format and size parameters allow customization of the output.

```APIDOC
## `apiResponse`

### Description
Renders an avatar for the given name and returns an API-shaped array that includes avatar URLs, responsive sizes, and metadata such as dimensions and cache key.

### Method
`apiResponse`

### Endpoint
`HDAvatar::apiResponse()` (PHP method)

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$name` | `string` | Yes | — | Name to render. |
| `$format` | `string` | No | `'png'` | Output format. |
| `$size` | `string` | No | `'medium'` | Responsive size name; applied if present in `responsiveSizes`. |

### Returns
Returns an array with the following structure:

```php
[
    'success' => true,
    'data' => [
        'avatar' => [
            'name' => string, 'initials' => string,
            'url' => string, 'placeholder' => string,
            'responsive_urls' => [ size => url, ... ],
        ],
        'metadata' => [
            'size' => string, 'format' => string,
            'dimensions' => ['width' => int, 'height' => int],
            'hash' => string, 'cache_key' => string,
        ],
    ],
    'timestamp' => string, // ISO-8601
]
```

```

--------------------------------

### batchExport method signature

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar-response.md

Exports multiple avatars, optionally applying a named responsive size. Returns an associative array mapping each name to its relative storage path.

```php
public function batchExport(array $names, string $format = 'png', string $size = 'medium'): array
```

--------------------------------

### getExportFormats method signature

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/concerns.md

Returns the list of supported export formats.

```php
public function getExportFormats(): array
```

--------------------------------

### setResponsiveSize

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar-response.md

Method to add or overwrite a responsive size configuration.

```APIDOC
## `setResponsiveSize`

### Description
Adds or overwrites an entry in the `responsiveSizes` array and returns `$this` for chaining.

### Method
`setResponsiveSize`

### Signature
```php
public function setResponsiveSize(string $name, int $width, int $height, int $fontSize): static
```

### Parameters
- **$name** (string) - Required - Size name.
- **$width** (int) - Required - Width.
- **$height** (int) - Required - Height.
- **$fontSize** (int) - Required - Font size.

### Returns
`static` - Returns `$this`.
```

--------------------------------

### batchCreateAndExport return structure

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar.md

Return array structure for batchCreateAndExport. Contains 'avatars' mapping names to createAndExport results, and 'batch_info' with counts, timing, format, and timestamp.

```php
[
    'avatars' => [ name => <createAndExport result>, ... ],
    'batch_info' => [
        'total_count' => int,
        'processing_time_seconds' => float,
        'average_time_per_avatar' => float,
        'format' => string,
        'timestamp' => string, // ISO-8601
    ],
]
```

--------------------------------

### createHD

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar-response.md

Creates a high-definition avatar by setting the name and re-initializing the theme.

```APIDOC
## createHD

### Description
Sets the name for the avatar and re-initializes the theme. Returns the current instance for chaining.

### Method
createHD

### Signature
`public function createHD(string $name): static`

### Parameters
- **$name** (string) - Required - Name/email/string for the avatar.

### Returns
- `static` - The current instance.

### Source
`src/HDAvatarResponse.php:61`
```

--------------------------------

### bulkExport

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/concerns.md

Creates and exports each name into the directory with a sanitized, hash-suffixed filename. Returns a map of name to storage path.

```APIDOC
## bulkExport

### Description
Creates and exports each name into the directory with a sanitized, hash-suffixed filename. Returns a map of name to storage path.

### Method
PHP

### Endpoint
`public function bulkExport(array $names, string $directory, string $format = 'png', array $options = []): array`

### Parameters
#### Path Parameters
- **$names** (array) - Required - List of names.
- **$directory** (string) - Required - Storage directory.

#### Query Parameters
- **$format** (string) - Optional - Export format. Default: `'png'`.
- **$options** (array) - Optional - Options for each export. Default: `[]`.

### Request Example
```php
$avatar->bulkExport(['John Doe', 'Jane Smith'], '/path/to/directory', 'png');
```

### Response
#### Success Response (200)
- **array** - Map of name → storage path.

#### Response Example
```php
['John Doe' => '/path/to/directory/john-doe-abc123.png']
```
```

--------------------------------

### batchStoreOptimized

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/concerns.md

Stores each name optimized and logs batch metrics.

```APIDOC
## batchStoreOptimized(array $names, string $format = 'png', array $options = []): array

### Description
Stores each name optimized and logs batch metrics.

### Parameters
- **$names** (array) - Required - Array of names to render.
- **$format** (string) - Optional - Export format. Default: 'png'.
- **$options** (array) - Optional - Format options. Default: [].

### Return Value
- **array** - A map of name → URL.

### Source
`src/Concerns/StorageOptimization.php:176`
```

--------------------------------

### addTheme

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/avatar.md

Registers a named theme for later use with `setTheme()`. Returns `$this`.

```APIDOC
## addTheme

### Description
Registers a named theme for later use with `setTheme()`. Returns `$this`.

### Method
addTheme

### Signature
`public function addTheme(string $name, array $config): static`

### Parameters
- `$name` (string) - Required - Theme name key.
- `$config` (array) - Required - Theme attributes, validated via `validateConfig()`.

### Returns
`static` - Returns `$this` for chaining.

### Source
`src/Avatar.php:161`
```

--------------------------------

### bulkExport method signature

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/concerns.md

Exports multiple avatars for names into a directory. Returns a map of name to storage path.

```php
public function bulkExport(array $names, string $directory, string $format = 'png', array $options = []): array
```

--------------------------------

### batchCreateAndExport

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar.md

Processes a list of names through createAndExport() and returns an array containing the generated avatars and batch processing statistics.

```APIDOC
## batchCreateAndExport

### Description
Processes every name through `createAndExport()` and returns an array with the generated avatars and batch processing statistics.

### Method
batchCreateAndExport

### Endpoint
`public function batchCreateAndExport(array $names, string $format = 'png', array $options = []): array`

### Parameters
- **$names** (array) - Required - List of names.
- **$format** (string) - Optional - Export format. Default: `'png'`.
- **$options** (array) - Optional - Options forwarded per avatar. Default: `[]`.

### Response
#### Success Response
Returns an array with the following structure:
```php
[
    'avatars' => [ name => <createAndExport result>, ... ],
    'batch_info' => [
        'total_count' => int,
        'processing_time_seconds' => float,
        'average_time_per_avatar' => float,
        'format' => string,
        'timestamp' => string, // ISO-8601
    ],
]
```
```

--------------------------------

### Error handling for unsupported export format

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar-response.md

Demonstrates error handling when exporting an unsupported format. The exception message is "Unsupported format: bmp".

```php
try {
    $avatar->export('bmp');
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // "Unsupported format: bmp"
}
```

--------------------------------

### createSpriteSheet

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar.md

Creates a sprite sheet image combining multiple variations of an avatar, saves it to storage, and returns its storage URL.

```APIDOC
## createSpriteSheet

### Description
Creates a sprite sheet image combining each variation, saves it to storage, and returns its storage URL.

### Method
createSpriteSheet

### Endpoint
`public function createSpriteSheet(string $name, array $variations, string $format = 'png'): string`

### Parameters
- **$name** (string) - Required - Name to render.
- **$variations** (array) - Required - List of variation arrays (e.g. `['background' => '#ff6b6b', 'foreground' => '#fff']`).
- **$format** (string) - Optional - Sprite sheet format. Default: `'png'`.

### Response
#### Success Response
Returns a string containing the storage URL of the generated sprite sheet.
```

--------------------------------

### getBackground method signature

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/concerns.md

Returns the current background color as a hex string.

```php
public function getBackground(): string
```

--------------------------------

### exportAllFormats return structure

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar.md

Return array structure for exportAllFormats. Contains keys 'png', 'jpg', 'webp' each with 'url' and 'cached_url'.

```php
[
    'png'  => ['url' => string, 'cached_url' => string],
    'jpg'  => ['url' => string, 'cached_url' => string],
    'webp' => ['url' => string, 'cached_url' => string],
]
```

--------------------------------

### Integrate Avatar with other PHP projects using new Avatar($config)

Source: https://github.com/laravolt/avatar/blob/master/README.md

Integrate Laravolt Avatar into any PHP project by requiring Composer's autoload and importing the Avatar class. Instantiate with a $config array (same format as the Configuration section) and call create() followed by toBase64() or save() with a file path and quality (default 90).

```php
// include composer autoload
require 'vendor/autoload.php';

// import the Avatar class
use Laravolt\Avatar\Avatar;

// create your first avatar
$avatar = new Avatar($config);
$avatar->create('John Doe')->toBase64();
$avatar->create('John Doe')->save('path/to/file.png', $quality = 90);
```

--------------------------------

### createAndExport method signature

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar.md

Method signature for createAndExport. Creates an HD avatar, stores it optimized, and returns an array containing name, format, url, responsive_urls (if configured), and metadata with width, height, font_size, background, foreground, and hash.

```php
public function createAndExport(string $name, string $format = 'png', array $options = []): array
```

--------------------------------

### performCleanup

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/concerns.md

Runs old-file, large-file, and duplicate-file cleanup, then rebuilds metrics.

```APIDOC
## performCleanup(): array

### Description
Runs old-file, large-file, and duplicate-file cleanup, then rebuilds metrics.

### Return Value
- **array** - An array with keys `old_files`, `large_files`, and `duplicate_files`.

### Source
`src/Concerns/StorageOptimization.php:197`
```

--------------------------------

### save

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/avatar.md

Builds the avatar and saves it to the specified path, returning the underlying Intervention Image interface.

```APIDOC
## save

### Description
Builds the avatar and saves it to `$path`, returning the underlying Intervention Image interface.

### Method
save

### Signature
`public function save(?string $path, int $quality = 90): \Intervention\Image\Interfaces\ImageInterface`

### Parameters
- `$path` (?string) - Required - Destination file path.
- `$quality` (int) - Optional - Default: `90` - Output quality (0–100).

### Returns
`\Intervention\Image\Interfaces\ImageInterface` - The underlying Intervention Image interface.

### Source
`src/Avatar.php:233`
```

--------------------------------

### export

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/hdavatar-response.md

Builds the avatar, ensures the export directory exists, and saves an encoded file. Returns the relative storage path of the file.

```APIDOC
## export

### Description
Builds the avatar, ensures the export directory exists (`Storage::makeDirectory`), and saves an encoded file. Returns the **relative storage path** of the file (e.g. `avatars/<hash>_<timestamp>.png`). The path is also recorded in `exportedFiles`.

### Method
`export`

### Signature
```php
public function export(string $format = 'png', int $quality = 95): string
```

### Parameters
- **$format** (string) - Optional - Default: `'png'` - Output format: `png`, `jpg`/`jpeg`, or `webp`.
- **$quality** (int) - Optional - Default: `95` - Quality (overridable per-format via `hd.quality.*`).

### Return Value
- **string** - The relative storage path of the exported file.

### Throws
- `\InvalidArgumentException("Unsupported format: {$format}")` for any format other than `png`, `jpg`, `jpeg`, `webp`.

### Source
`src/HDAvatarResponse.php:72`
```

--------------------------------

### buildAvatar

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/avatar.md

Builds or rebuilds the raster avatar into the `$image` property by computing initials, creating a new image, drawing the shape, and rendering text if initials are present.

```APIDOC
## buildAvatar

### Description
Builds or rebuilds the raster avatar into the `$image` property by computing initials, creating a new image, drawing the shape, and rendering text if initials are present.

### Method
PHP method

### Endpoint
`public function buildAvatar(): static`

### Returns
- static - Returns `$this` for chaining.

### Throws
- \InvalidArgumentException - If the configured `shape` is not `circle` or `square`.

### Source
`src/Avatar.php:354`
```

--------------------------------

### getStorageDirectory

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/concerns.md

Returns the configured directory.

```APIDOC
## getStorageDirectory(): string

### Description
Returns the configured directory.

### Return Value
- **string** - The directory.

### Source
`src/Concerns/StorageOptimization.php:511`
```

--------------------------------

### getStorageStatistics

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/concerns.md

Returns storage statistics including file counts, sizes, and usage.

```APIDOC
## getStorageStatistics(): array

### Description
Returns storage statistics including total files, sizes, formats, and usage.

### Return Value
- **array** - Contains `total_files`, `total_size_bytes`, `total_size_mb`, `formats`, `storage_limit_mb`, `usage_percentage`, `last_updated`, `disk`, and `directory`.

### Source
`src/Concerns/StorageOptimization.php:449`
```

--------------------------------

### getExportFormats

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/concerns.md

Returns the list of supported export formats.

```APIDOC
## getExportFormats

### Description
Returns the list of supported export formats.

### Method
PHP

### Endpoint
`public function getExportFormats(): array`

### Parameters
None

### Request Example
```php
$formats = $avatar->getExportFormats();
```

### Response
#### Success Response (200)
- **array** - List of supported formats: `['png', 'jpg', 'jpeg', 'webp']`.

#### Response Example
```php
['png', 'jpg', 'jpeg', 'webp']
```
```

--------------------------------

### getExportOptions

Source: https://github.com/laravolt/avatar/blob/master/_autodocs/api-reference/concerns.md

Returns the current export options array.

```APIDOC
## getExportOptions()

### Description
Returns the current export options array.

### Return Value
- **array** - The export options.

### Source
`src/Concerns/ImageExport.php:367`
```
Tokens:
Raw