PHP SDK configuration

Configuration is explicit and immutable. The SDK does not read environment variables, framework helpers, or global configuration.

Client options

 1use BladePDF\BladePdf;
 2use BladePDF\Client\ClientOptions;
 3
 4$bladePdf = BladePdf::create(
 5    apiKey: $apiKey,
 6    clientOptions: new ClientOptions(
 7        timeout: 60,
 8        connectTimeout: 10,
 9        retryTimes: 1,
10        retrySleepMilliseconds: 1000,
11        verifySsl: true,
12    ),
13);

retryTimes is the number of retries after the first attempt. Only connection failures and HTTP 429, 502, 503, and 504 are retried. Retry-After takes precedence over exponential delay. Authentication, validation, payload, and plan-limit responses are not retried.

Asset roots

documentRoot maps URL paths such as /images/logo.png. Ordered searchRoots resolve relative references. localHosts lets same-application HTTP URLs map back to the document root instead of being treated as remote.

Every automatically located file is canonicalized with realpath and must remain inside an allowed root. Traversal, absolute paths outside a root, file:// escapes, and symlinks leaving a root throw AssetAccessDeniedException.

Intentional one-file permission

withAsset() is an explicit caller grant and may attach a file outside automatic roots:

 1$result = $bladePdf
 2    ->fromHtml('<img src="asset:///tenant-logo.png">')
 3    ->withAsset($approvedLogoPath, 'tenant-logo.png', 'image/png')
 4    ->render();

Dependency injection

For advanced applications, construct BladePDF\BladePdf with a custom RenderClient and AssetResolver. Alternatively pass any GuzzleHttp\ClientInterface as the fourth argument to BladePdf::create().