Skip to content
Poli Page PHP SDK

Migration

This page tracks breaking changes between versions of poli-page/sdk. For the full per-release diff, see the changelog.

From 0.11.0 to 0.13.0

Section titled “From 0.11.0 to 0.13.0”

The SDK now shares its major.minor with the Poli Page API, so there is no 0.12. This release follows the Poli Page API contract v0.13.0. The full guide is in MIGRATION.md in the repo.

  • A 2xx whose body is not JSON raises InvalidResponseException (invalid_response, the real 2xx as status, never retried) instead of INTERNAL_ERROR. toPayload() answers 502 for it.
  • renderToFile() raises io_error (Failed to write PDF: <reason>) instead of invalid_options when it cannot write the file, and leaves the target untouched on any failure.
  • The presigned-URL download is bounded by the client’s timeout when the call sets none: the whole download for render->pdf() and downloadPdf(), an idle timeout for render->pdfStream(). Past it, DOWNLOAD_FAILED says Failed to download PDF: timeout.
  • With Guzzle, the download of render->pdfStream() and renderToFile() goes through Guzzle’s stream handler instead of cURL: cURL options on your Guzzle client do not apply to it, and it needs allow_url_fopen.

From 0.10.0 to 0.11.0

Section titled “From 0.10.0 to 0.11.0”

The SDK now follows the retry policy and the error messages of the Poli Page API contract. The full guide is in MIGRATION.md in the repo.

  • QUOTA_EXCEEDED and OVERAGE_CAP_EXCEEDED (429) and STORAGE_ACCESS_DENIED (502) are no longer retried, and isRetryable() returns false for them. A queue that requeues on isRetryable() now drops these errors at once: handle them by code. See Retries and idempotency.
  • The predicates read status and errorCode: a DOWNLOAD_FAILED with the storage’s 403 is an auth error.
  • DOWNLOAD_FAILED is never retryable: isRetryable() is false for it whatever the storage status (it was true for a storage 5xx or 429). Call documents->get($id) for a fresh URL and download again.
  • A timeout of the presigned-URL download raises DOWNLOAD_FAILED, not TimeoutException.
  • Retry-After is read as integer seconds or an HTTP-date only; Retry-After-Ms is ignored.
  • The package conflicts with symfony/http-client older than 6.2; with Symfony HTTP Client the SDK’s timeout now bounds each attempt.
  • The SDK-side messages are the specification’s exact texts (Network request failed, Request timed out after <ms>ms, Failed to download PDF: HTTP <status>, Failed to download PDF: network error, HTTP <status> for an error body that is not JSON, project is required). Match errorCode, not the message. See Errors.

From 0.9.x

Section titled “From 0.9.x”

An API key now belongs to one environment (pp_sandbox_…, pp_live_…, pp_staging_…) and every render uses the project’s copy published in that environment. The release removes, with no deprecation window:

  • ProjectModeInput — renamed RenderInput, now the only render input, without version.
  • The template preview method and the raw-HTML input — try templates in the playground at play.poli.page. $client->documents->preview($id) stays.
  • DocumentDescriptor::$version and the version error codes.

The step-by-step guide is in MIGRATION.md in the repo.

See also

Section titled “See also”