NextPDF Gotenberg boot and discovery

At a glance

The bridge has no auto-discovery mechanism. You construct it as a plain service with explicit constructor injection: a configuration value object and Hypertext Transfer Protocol (HTTP) collaborators defined by PHP Standard Recommendation (PSR). This package ships no service provider, bundle, or container extension, and it does not read any environment variable itself. Here, “discovery” means how a host framework supplies those collaborators. That responsibility belongs to the framework, not this package.

How the bridge is discovered

It is not discovered automatically. You construct it. GotenbergBridge requires four arguments and accepts three optional ones:

Required: a GotenbergConfig, a PSR-18 client, a PSR-17 request factory, and a PSR-17 stream factory.
Optional: a PSR-3 logger, a Hypertext Markup Language (HTML) security policy (defaults to the NextPDF core default policy), and a PSR-17 response factory.

The response factory activates the cURL-pinned transport. Supply it, and when the bridge has something to pin (resolved addresses or configured SubjectPublicKeyInfo (SPKI) pins), it uses the pinning transport. Omit it, and the injected PSR-18 client is always used. The full argument contract is in /integrations/gotenberg/configuration/.

Boot sequence

There is no registration step. The lifecycle is:

The host resolves a PSR-18 client and PSR-17 factories. The host container does this; the package does not.
The application builds a GotenbergConfig from its configuration source. GotenbergConfig::fromArray() accepts a snake_case array and substitutes defaults for malformed values. Validate the source in your boot path, so a missing Uniform Resource Locator (URL) value fails at boot, not per conversion.
The application constructs GotenbergBridge with the config and collaborators.
The first conversion call runs URL validation, server-side request forgery (SSRF) screening, filename screening, and the request. No work happens at construction time; the bridge stays inert until you call it.

Container bindings

This package ships no container bindings. To make the bridge injectable, register it in your host application’s container as follows:

Bind GotenbergConfig from your configuration source.
Bind the PSR-18 client and PSR-17 factories to your chosen implementations.
Bind GotenbergBridge as a service that receives those dependencies.

Framework-native auto-wiring, configuration publishing, and service-provider or bundle registration belong in the dedicated framework integration packages, not here. This package is framework-agnostic by design. It depends only on PSR interfaces, so it works under any container.

Configuration resolution order

The package reads no configuration on its own. The resolution order is whatever your application implements before it calls GotenbergConfig::fromArray() or the constructor. A common order is environment variables, then a published config file, then code defaults. That order is your application’s contract, not this package’s. What the package does define is the default value for each field that the array passed to fromArray() leaves out: empty application programming interface (API) URL, 30-second timeout, 50 MiB size cap, empty API key, and empty pin lists.

Diagnostics

Two built-in signals confirm wiring:

isAvailable() validates the URL without network traffic, then sends a HEAD request to <apiUrl>/health and reports availability when the status is below 500. It returns false rather than throwing on any failure. Call it from a readiness check.
A smoke conversion of a known-good small document confirms the full path end to end. This includes the multipart request to <apiUrl>/forms/libreoffice/convert and response validation.