ApiSutra PHP 0.4.0

• Add opt-in upload/download progress for sync and async HTTP transfers, with execution trace, attempt numbers and byte counters.
• Isolate callback failures and preserve protected external URL handling. Built-in mocks, playback and Laravel fake accept the option without transfer notifications.
• Add per-call withRetryDelay() / withoutRetryDelay() overrides for backoff settings without changing retry safety or server Retry-After handling.
• Document response provenance after retry failures; execution result semantics are unchanged.

Both additions are optional. Existing calls need no changes. Transfer progress is supported by the built-in Guzzle/cURL adapter; custom transports must declare support. Callbacks must not perform I/O or suspend a Fiber.

Run the local HTTP example (requires Guzzle, ext-curl and proc_open):

php vendor/apisutra/php/docs/example/transfer-progress/run.php

For Laravel applications, use apisutra/laravel 0.1.3 or later to allow the core 0.4 series.

ApiSutra PHP 0.3.1

• Update the runnable Records SDK to use a shared DtoVariants declaration for list,
  single-field and root inputs, with a typed fallback preserving unknown attachments.
• Demonstrate webhook hydration from original JSON with the HTTP client's configuration,
  and dictionary shape validation before a custom cast. Compare diagnostics for seventeen
  invalid bodies through HTTP and the JSON entry point.
• Expand the English and Russian DTO catalog, SDK walkthrough and quickstart;
  improve attributed-property spacing in the DTO examples. No core runtime API changes.

Run the example after updating the package:

php vendor/apisutra/php/docs/example/sdk/run.php

0.3.0

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.

ApiSutra PHP 0.2.0

JSON object/array identity now survives decoding and is checked against the existing DTO and Shape declarations, including nested values, cached and async responses, pagination items and built-in continuation.

Compatibility

• JSON objects, including {} and objects with consecutive numeric keys, no longer satisfy a strict list declaration.
• JSON arrays no longer satisfy a DTO object input by default.
• Nonempty lists such as ["a"] are rejected as DTO input instead of silently producing a default-valued DTO and losing the supplied values. This check remains active in every configuration; no setting fully reproduces 0.1.1 behavior.
• Use emptyListAsObject: true on the relevant DtoShape, ValueShape::dto or Returns declaration for providers that send [] for an empty object. Required fields still apply. normalizeKeys: true remains the explicit map-to-list conversion option.

Configuration and cost

HydrationConfig::jsonShapeValidation is enabled by default. Setting it to false for a client skips additional JSON shape metadata processing, including built-in continuation. DTO and field declarations do not override the switch; ordinary hydration and input checks remain active.

The decoder uses native JSON parsing with progressive normalization and sparse metadata. Many empty or numeric-key objects can still require substantial memory. Measure peak memory with representative payloads and concurrency; smaller pagination pages and lower concurrency reduce the peak.

Public decoded values remain PHP arrays. Custom transformation boundaries, diagnostics and local normalization permissions are documented in the configuration reference and shape reference.

Validated with 3,286 core tests, Laravel integration, static analysis, documentation checks and no-dev distribution installs. See the changelog.

ApiSutra PHP 0.1.2

• Expanded the runnable Records SDK with six related DTOs, typed collections, enum and
  discriminator variants, a bidirectional cast, inline Base64 and nested extra fields.
• Demonstrated recursive serialization, immutable copies, standalone hydration,
  missing/null/default rules and twelve invalid responses with field-level diagnostics.
• Updated the English and Russian walkthroughs and installation checks. No core runtime API changes.

ApiSutra PHP 0.1.1

• Expanded the English and Russian capability maps with grouped features and reference links.
• Added client configuration and result selection examples, clarified async and pagination,
  and linked the detailed DTO example.
• Refined overview navigation, badges and declarative SDK positioning. No runtime changes.

ApiSutra PHP 0.1.0

Initial release of the framework-independent PHP 8.4+ SDK toolkit.

• Declarative clients and requests, validation, resources and extension hooks.
• DTO hydration and serialization: attributes, external rules, nested models, collections,
  custom hydrators and explicit handling of unknown fields.
• Synchronous calls and concurrent async execution with typed promises, cancellation,
  batch/pool and incremental consumption with bounded result storage.
• Page/offset/cursor pagination, lazy item iteration and concurrent collection of
  independent pages with a shared deadline.
• Authentication strategies and OAuth2 Client Credentials / Authorization Code with
  PKCE S256, automatic refresh and persistable token/authorization-attempt snapshots.
• Safe retries, timeouts, execution budgets, response caching, quotas and Retry-After
  cooldown; optional atomic Redis backends for shared quotas and cooldown.
• File uploads/downloads, streamed payloads, composite requests and continuation polling.
• Structured results and errors, correlated traces, debug snapshots, secret masking,
  execution observation and English/Russian messages.
• Mock transports, strict fake sessions, recording/playback, client/request/DTO generation,
  and runnable examples including one Records SDK for PHP and Laravel.

Laravel integration is provided by apisutra/laravel.
See the capability map and documentation.