The builder

AvatarBuilder collects configuration through chained method calls and produces a GeneratedAvatar when generate() is called. Every setter returns the builder instance.

Entry points

use Renfordt\AvatarSmithy\Avatar;

Avatar::engine('initials');   // builder with a named primary engine
Avatar::for($userOrArray);    // builder with seed/name pre-filled

You can also construct the builder directly. Its constructor accepts an optional engine name and an optional PSR-3 logger:

use Renfordt\AvatarSmithy\AvatarBuilder;

$builder = new AvatarBuilder('initials', $logger);

Core inputs

Method	Description
seed(string)	Value used to derive the avatar (typically an email).
name(string)	Display name; used by the initials engine and for alt text.
size(int)	Output size in pixels. Must be between 8 and 2048. Default 200.

size() throws a ValidationException when the value is outside the allowed range.

When an engine runs, the seed passed to it is seed ?? name ?? ''.

Engine selection

Method	Description
try(string)	Sets the primary engine if none is set yet, otherwise appends a fallback.
fallbackTo(string)	Appends a fallback engine.

Engine names are case-insensitive. See Fallback chains.

Option setters

These methods write into a shared option bag. Each engine reads only the options it understands and ignores the rest, so it is safe to set options across a fallback chain that mixes engines.

Method	Applies to	Notes
shape(string)	initials, gradient	circle, square, hexagon.
style(string)	dicebear	DiceBear style name ([a-z0-9-]).
variant(string)	reserved	Stored as variant.
backgroundColor(array|string)	dicebear	One color or a palette.
background(string)	pixel (toggle via bool elsewhere)	Stored as background.
color(string)	reserved	Stored as color.
radius(int)	dicebear	Must be >= 0.
bold(bool)	reserved	Stored as bold.
defaultImage(string)	gravatar	Gravatar d parameter.
rating(string)	gravatar	Gravatar r parameter.
fontSize(int)	initials	Must be > 0.
fontWeight(string)	initials	e.g. normal, bold.
pixels(int)	pixel, multicolor-pixel	Grid size. Must be > 0.
symmetry(bool)	pixel, multicolor-pixel	Mirror horizontally.
foregroundLightness(float)	initials, pixel	0.0–1.0.
backgroundLightness(float)	initials, pixel	0.0–1.0.
gradientType(string)	gradient	See the gradient engine page.
numColors(int)	multicolor-pixel	Palette size. Must be > 0.
numShapes(int)	bauhaus	Must be > 0.
colorStops(int)	gradient	Must be > 0.
fillAll(bool)	multicolor-pixel	Fill every cell instead of the matrix pattern.

Setters that validate (radius, fontSize, pixels, numColors, numShapes, colorStops, foregroundLightness, backgroundLightness) throw a ValidationException on out-of-range input. Engine-specific defaults are listed on each engine page.

Diagnostics

Method	Description
setLogger(LoggerInterface)	Sets a PSR-3 logger. Defaults to NullLogger.
debugMode(bool)	When enabled, the first engine failure is rethrown immediately as EngineFailedException instead of falling through.
getLastErrors()	Returns the per-engine failures recorded during the last generate() call.

During generation, engine failures are logged at warning level and a null return (an engine declining to produce output) at debug level.

See Error handling for the failure model.