API stability

Abzar follows Semantic Versioning. This page spells out which parts of the surface area are covered by the BC promise and which are explicitly not.

Current status: 0.x

Release 0.8.1 has no prerelease suffix. While Abzar is in 0.x, breaking changes can happen in any minor release. Use ^0.8.1 and review the CHANGELOG before upgrading.

From 1.0.0 onward, the commitments below apply.

Result-vs-throw policy

Validators expose validate() for a result, tryFrom() for an object or null, and from() for an object or ValidationException. Lookup warnings do not prevent construction. BillId constructors require both bill and payment IDs; see validation for signatures and acceptance rules.

The exception hierarchy and result shape below are public API. For handling examples, warning semantics, formatter failures and native PHP errors, use the error-handling guide. The error-code reference lists exact codes and messages.

Protected surface (full BC promise from 1.0)

• Public class names and namespaces (Eram\Abzar\...).
• Public method signatures: parameter types, return types, and method names.
• ValidationResult public shape:
  • isValid(): bool
  • isStrictlyValid(): bool — valid AND no warnings (every optional lookup resolved). Value-object constructors accept warning-bearing results; use this for strict acceptance.
  • errors(): list<string>
  • errorCodes(): list<ErrorCode>
  • warnings(): list<string>
  • warningCodes(): list<ErrorCode>
  • detail(): ?ValidationDetail — typed per-validator DTO (Eram\Abzar\Validation\Details\*; ValidationDetail extends JsonSerializable)
  • jsonSerialize() output shape.
• Value-object accessors (->value(), ->city(), ->bin(), etc.) on each validator class.
• Detail DTO property names ($cityCode, $bin, $bankCode, $normalizedLocal, …). These are public readonly properties under Eram\Abzar\Validation\Details\.
• Eram\Abzar\Validation\ErrorCode — the backing string value for each case is API surface from 0.3 onward. Renaming or dropping a case is a breaking change. New cases may be added in minor releases.
• Eram\Abzar\Exception\AbzarException hierarchy: the abstract root and the four concrete classes are stable — ValidationException (thrown by validator ::from() constructors and by ::fake() on a bad pinned argument), FormatException (thrown by formatters), MoneyException (thrown by Money\Amount), and EnvironmentException (thrown when an optional runtime prerequisite such as ext-intl is missing).
• Input-accepting conventions: Validators accept Persian / Arabic / English digit strings. NumberFormatter and Currency::format() also normalize numeric strings. Amount factories and ordinals take integers; NumberToWords takes int|float. These signatures do not promise Persian digit-string coercion.

Explicitly unstable

• Persian error message text. ValidationResult::errors() returns human-facing Persian strings. They may be reworded for clarity, punctuation, or tone between minor releases. Do not pattern-match on them; use error codes (when available) or the overall isValid() boolean.
• Detail DTO lookup strings that come from bundled tables: bank names, city names, province names, operator names. These reflect real-world data that changes (mergers, renames, splits). The DTO property names are stable; the string values are not.
• Lookup-table contents: entries are added, removed, and corrected as upstream data is updated. Consumers relying on a specific BIN or city-code mapping should snapshot the value in their own code if they need exact reproducibility.
• Internal classes and methods. Anything marked @internal, anything under a namespace not explicitly documented, and private / protected members.

Deprecation policy (from 1.0.0)

1. A deprecation is announced in a minor release with @deprecated on the source and an entry in CHANGELOG.md.
2. The deprecated surface keeps working for the remainder of that major.
3. Removal happens only in the next major release.

Data-file changes

Lookup-table changes (city codes, bank BINs, operator prefixes, IBAN issuers) ship in minor or patch releases without a deprecation cycle because they reflect external reality, not API surface. If a change would flip a previously-valid input to invalid (or vice versa), it is called out in the changelog.

Reading released documentation

The public website imports only published releases at the exact commit resolved from the release tag. Documentation on the default branch can be newer than your installed package. Match the documentation version to your installed release and read the upgrade guide. Publication does not add the full API compatibility guarantees planned for 1.0.

Related: installation, error handling.