Engine overview

Seven engines ship with the library. Each is selected by a lowercase name passed to engine(), try(), or fallbackTo().

Name	Output	Network	Page
initials	SVG	No	Initials
gravatar	URL (PNG)	Yes	Gravatar
dicebear	SVG (fetched)	Yes	DiceBear
pixel	SVG	No	Pixel
multicolor-pixel	SVG	No	Multicolor pixel
bauhaus	SVG	No	Bauhaus
gradient	SVG	No	Gradient

An unknown name passed to the builder throws a RuntimeException.

Common behavior

All engines implement Engines\EngineInterface:

public function generate(string $seed, ?string $name, int $size, array $options): ?string;
public function getContentType(): string;

• generate() returns the avatar content, or null to decline and let the fallback chain continue.
• Local engines extend Engines\AbstractEngine, which provides getContentType() (default image/svg+xml) and a fetchUrl() helper for remote engines.

Local vs. remote

Local engines (initials, pixel, multicolor-pixel, bauhaus, gradient) build SVG in-process with no network access. They are deterministic and fast and make good final fallbacks.

Remote engines (gravatar, dicebear) depend on an external service:

• gravatar returns a URL string; no request is made by the engine itself.
• dicebear fetches the SVG over HTTP through AbstractEngine::fetchUrl().

fetchUrl() uses a 5-second timeout, follows at most one redirect, and caps the response at 5 MiB. These bounds limit redirect-based SSRF and memory exhaustion. A failed fetch returns null, triggering the fallback chain.

Determinism

Local engines derive colors and layout from an MD5 hash of the seed (via the Support\Name helper). The same seed and options always produce the same SVG.