Skip to main content

Error handling

Exceptions​

All exceptions live under Renfordt\AvatarSmithy\Exceptions.

ValidationException​

Extends InvalidArgumentException. Thrown by builder setters on invalid input, with named factory methods:

FactoryTriggered by
invalidSize(int, int $min=8, int $max=2048)size() outside 8–2048.
invalidLightness(float, string $field)lightness outside 0.0–1.0.
invalidPositiveInteger(int, string $field)a value that must be > 0.
invalidNonNegativeInteger(int, string $field)a value that must be >= 0.

EngineFailedException​

Extends RuntimeException. Thrown from generate() in debug mode when an engine throws. Carries the engine class name (getEngineName()) and wraps the original exception as previous.

AllEnginesFailedException​

Extends RuntimeException. Thrown from generate() when every engine in the chain has failed or declined.

MemberDescription
$failures (readonly)Array of per-engine failure records.
getFailures()Same array.
getFailureSummary()A human-readable, multi-line summary of the failures.

Each failure record has the shape:

['engine' => string, 'error' => string, 'exception' => ?Throwable]

RuntimeException​

A plain RuntimeException is thrown by generate() when no engine has been set, and by the builder when an unknown engine name is requested.

Patterns​

Guaranteed success​

End the chain with a local engine so generate() does not throw. The initials engine declines on an empty name, so include a generative local engine when names may be missing:

$avatar = Avatar::for($user)
    ->try('gravatar')
    ->fallbackTo('initials')
    ->fallbackTo('gradient')   // always produces output
    ->generate();

Handling total failure​

use Renfordt\AvatarSmithy\Exceptions\AllEnginesFailedException;

try {
    $avatar = Avatar::engine('dicebear')->seed($email)->generate();
} catch (AllEnginesFailedException $e) {
    error_log($e->getFailureSummary());
    // serve a static placeholder
}

Inspecting without catching​

getLastErrors() returns the failures recorded during the last generate() call, cleared at the start of each call. Combined with a logger, this is useful for observing which engines declined in a chain that ultimately succeeded.

Logging​

The builder accepts a PSR-3 logger via the constructor or setLogger(); it defaults to Psr\Log\NullLogger. Engine failures are logged at warning level (with the exception attached) and null returns at debug level.