Environment options · 6 min read

Configuration

BladePDF's Laravel configuration controls the API endpoint, credentials, request timeout behavior, TLS verification, user agent, and local hostnames used for asset handling.

The config file

Publish the configuration file with:

Terminal

bash

 1php artisan vendor:publish --tag=bladepdf-config

The generated file reads from these environment variables:

Environment variable	Default	Purpose
`BLADEPDF_BASE_URL`	`https://api.bladepdf.com`	Base URL for BladePDF requests.
`BLADEPDF_API_KEY`	none	Bearer token used to authenticate render requests.
`BLADEPDF_TIMEOUT`	`60`	Total HTTP timeout in seconds.
`BLADEPDF_CONNECT_TIMEOUT`	`10`	Connection timeout in seconds.
`BLADEPDF_RETRY_TIMES`	`1`	Number of retries after the first attempt.
`BLADEPDF_RETRY_SLEEP`	`1000`	Sleep between retries in milliseconds.
`BLADEPDF_VERIFY_SSL`	`true`	Whether the HTTP client verifies TLS certificates.
`BLADEPDF_USER_AGENT`	`bladepdf-laravel/2.0 bladepdf-php/1.0`	User agent sent by the package.
`BLADEPDF_AUTO_RESOLVE_ASSETS`	`true`	Whether the Laravel package automatically scans local HTML/CSS assets and rewrites them to `asset:///...` references.

Typical production env

.env

env

 1BLADEPDF_API_KEY=blpdf_xxxxxxxxxxxxxxxxxxxxxxxx
 2BLADEPDF_TIMEOUT=60
 3BLADEPDF_RETRY_TIMES=3
 4BLADEPDF_RETRY_SLEEP=1000

Local host asset detection

The Laravel package can rewrite local asset references in rendered HTML. It treats your APP_URL host plus localhost, 127.0.0.1, and ::1 as local hosts by default.

External http and https URLs are preserved. Local paths such as /images/logo.png, relative CSS references, and allowed absolute filesystem paths are uploaded as request-scoped assets.

To keep HTML and CSS references untouched, set BLADEPDF_AUTO_RESOLVE_ASSETS=false or disable resolution for one render with withoutAssetResolution().

Filesystem roots

Laravel 2.0 allows public_path() and storage_path('app') by default. It does not allow base_path(). Add only intentional directories to the published asset_roots array; traversal and symlink escapes are denied after canonical path resolution.

Timeouts and render limits

BLADEPDF_TIMEOUT controls how long your Laravel app waits for the HTTP response. Your plan also controls maximum render time, concurrency, payload size, PDF size, JavaScript availability, and internet access.

Use a timeout larger than the plan render limit

If your plan allows long renders, make sure your Laravel HTTP timeout and upstream web server timeout do not expire first.

Retry policy

The core retries connection failures and status codes 429, 502, 503, and 504. It honors Retry-After and otherwise uses exponential delay based on BLADEPDF_RETRY_SLEEP. Validation, authentication, payload, and plan-limit errors are not retried.

Changing the base URL

Most applications should use the hosted API. For local platform development or private deployments, point the package at a different API base URL:

.env

env

 1BLADEPDF_BASE_URL=https://render.internal.example.com