Skip to content

0.3.0

Choose a tag to compare

View all tags
@brahmic brahmic released this 27 Sep 10:26
· 2 commits to master since this release
v0.3.0
ebabb85

ApiSutra now supports type-level DTO variants with typed fallbacks and a public JSON-to-DTO entry for incoming webhooks, using the same hydration and JSON-shape policies as HTTP responses.

Added

  • #[DtoVariants] and HydrationRules::withVariants() declare variants once on an interface or base class for nested fields, lists, HTTP responses, pagination and continuation.
  • Unknown variants can hydrate into a compatible fallback DTO. Invalid known variants remain errors.
  • Hydrator::hydrateJson() accepts original JSON without relying on internal APIs.
  • #[InputShape(ContainerShape::Object)] validates a dictionary before a custom cast.
  • A runnable HTTP/polling/webhook example demonstrates these features.

Upgrading from 0.2

Update imports and enum references:

  • ApiSutra\Enums\DataTransfer\NestedDiscriminatorMode → ApiSutra\Enums\DataTransfer\DiscriminatorMode.
  • ApiSutra\Enums\DataTransfer\NestedUnknownVariant → ApiSutra\Enums\DataTransfer\UnknownVariant.
  • ApiSutra\Serialization\Rules\InputShape → ApiSutra\Serialization\Rules\ContainerShape. The new ApiSutra\Attributes\DataTransfer\InputShape is a property attribute.

Value discriminator tags accept only strings and integers. Boolean, float, array and object tags now fail with invalid_discriminator_type instead of being implicitly converted or treated as unknown.

Type-level variants default to Error; existing list defaults remain KeepRaw. For Nested typed collections, known variants continue to work, while unknown raw elements still fail collection validation. Every map/fallback class is checked for compatibility before item selection.

Composite arrays and object sources (stdClass, JsonSerializable) still hydrate. An object already matching the declared response type bypasses rehydration. Invalid continuation final types retain ContinuationConfigurationException.

The current Records SDK example requires apisutra/php:^0.3. Laravel users should upgrade to apisutra/laravel:^0.1.2, which allows the new core line.

Validated with 3,354 passing core tests (28 skipped), static analysis, documentation checks and Git/Composer archive installations without dev dependencies. No new runtime dependencies.

See the changelog.

Assets 2
Loading