Skip to content

exceptions.md

Latest commit

 

History

History
65 lines (39 loc) · 2.55 KB

exceptions.md

File metadata and controls

65 lines (39 loc) · 2.55 KB

Exception Reference

All custom exceptions extend JOOservices\UserAgent\Exceptions\UserAgentException.

Exception types

  • UserAgentException — base for all library exceptions.
  • InvalidSpecException — invalid spec data (version, channel, arch, locale, combination, etc.).
  • NoCandidateException — no browser template matches the spec after filtering.
  • GenerationPolicyException — policy violations (e.g. unique retries exhausted, invalid recent() age).
  • InvalidDatasetException — invalid dataset or catalog data.
  • ProviderException — provider/backend errors.

InvalidSpecException

Source: src/Exceptions/InvalidSpecException.php

Raised by SpecValidator and SpecCapabilities for invalid spec data, including:

  • invalid version ranges and bounds
  • invalid channel/arch/locale/tag
  • invalid randomSpec values
  • invalid (browser, device, OS) combination (e.g. Safari + Windows): use invalidCombination() with optional requestedSpec, reason, and closestValidAlternatives from the validity matrix

Optional structured fields (when using invalidCombination() or extended factories): getRequestedSpec(), getReason(), getClosestValidAlternatives().

NoCandidateException

Source: src/Exceptions/NoCandidateException.php

Raised when no browser template candidate can satisfy filters (e.g. from UserAgentBuilder::resolveSpec()).

Optional: getClosestValidAlternatives() returns up to 3 suggested valid (browser, device, OS) combinations when provided via fromFilters($reason, $alternatives).

GenerationPolicyException

Source: src/Exceptions/GenerationPolicyException.php

Raised by UserAgentBuilder for policy violations:

  • Unique retries exhausted — unique mode could not produce a new UA within the retry limit (uniqueRetriesExhausted()).
  • Invalid recent age — recent($months) was used with an unsupported value (invalidRecentAge()).

Runtime Exceptions from Facade Builder

Source: src/Facade/UserAgentBuilder.php

  • LogicException when toSpec() is called while bot type is set (use generate() for bot UAs).
  • GenerationPolicyException when unique retries are exhausted or recent age is invalid (see above).

BadMethodCallException

Source: src/UserAgent.php

  • UserAgent::__callStatic() throws when fluent static method does not exist on UserAgentBuilder.

Next

Related