Statamic Asset Usage Laravel Package

Getting Started

Start with the config file and the PDF export route/controller — those two files explain most of the package's behaviour. Publish config and migrations, run migrate, then seed or upload a handful of assets so the Overview page has something to show.

Key config keys to locate first:

• The PDF chunk size (defaults to 500 assets per part) and the hard cap (10,000 assets per PDF as of v1.7.0).
• The thumbnail dimensions/quality used when embedding images into PDFs — this is the setting that gave the ~40% size reduction in v1.7.0.
• The storage disk used for temporary PDF parts.

First practical use case: open the Overview page, apply a filter, and export the filtered set to PDF. That single flow exercises filtering, thumbnail generation, chunked export, and the browser-side merge — if it works end to end, the rest of the package will behave predictably.

For a first integration, call the export from your own controller with a filter payload rather than building a bespoke export route; reusing the package's filter object is what keeps the PDF and the on-screen list in sync.

Implementation Patterns

Reuse one filter definition for list and PDF. The most common source of "the PDF doesn't match the screen" bugs is duplicating filter logic. Build the filter once (query scope, form request, or filter object) and pass it to both the Overview listing and the PDF export endpoint.

Treat the PDF export as a chunked protocol, not a single call. With parts of 500, a 10,000-asset export is ~20 sequential requests that the browser stitches into one file. Design around that:

• Expose a deterministic "part N" endpoint (?page=N&per_page=500) with a stable orderBy so parts never overlap or skip rows.
• Return a small manifest (total parts, part index, filename) so the front end can drive the loop and show real progress.
• Keep each part request stateless and authorization-checked — it will be hit many times per export.

Queue the heavy parts when exports are user-triggered. If your asset records are large or thumbnails are generated on demand, the first part of an export is much slower than the rest (cold thumbnail cache). Warming thumbnails for the filtered set before starting the export keeps the browser loop snappy and avoids per-part timeouts.

Lean on the smaller thumbnails. The reduced thumbnail footprint means you can afford a slightly higher thumbnail quality setting than before at the same PDF size. If your PDFs are image-heavy, tune quality up rather than dimensions up — dimension changes alter the print layout.

Wire the export into both Overview and Compression pages using the same endpoint; only the filter payload differs. This is the pattern the v1.7.0 filter-width fix implies the package expects.

Test at the seams. Assert part counts for a known dataset, assert parts are disjoint (no duplicated IDs across pages), and assert an unauthorized part request is rejected — those three tests catch most regressions in a chunked exporter.

Gotchas and Tips

• Deterministic ordering is mandatory. Without a tie-breaker in the orderBy, chunks can duplicate or drop rows when the underlying data changes mid-export. Always sort by a unique column last.
• Partial failure leaves a silently truncated PDF. If part 7 of 20 fails, the browser may still merge 19 parts. Add a manifest check and a visible error state; retry individual parts rather than restarting the whole export.
• Browser memory is the real ceiling, not the 10,000 cap. Merging 20 blobs client-side works on desktop but can fail on low-memory mobile or with very image-dense PDFs. For large exports, consider a server-side merge fallback behind a flag.
• Blob joining is subject to CSP and sandboxing. If you serve the app with a strict Content-Security-Policy or inside an iframe, verify blob: URLs and any worker usage are permitted — this fails only in production configurations.
• Long exports outlive sessions. Twenty sequential requests can cross a session/CSRF token rotation or a signed-URL expiry. Use a longer-lived signed URL for part requests, or refresh the token mid-loop.
• Temporary parts need cleanup. Parts written to disk accumulate on failed or abandoned exports. Add a scheduled prune for the temp directory, and cap concurrent exports per user.
• Changing the chunk size requires config:cache refresh and a hard refresh on the front end if the chunk size is also embedded in JS.
• Thumbnail size reduction can hurt print legibility. Check embedded images at actual print DPI rather than on-screen; the 40% saving is not free if you also shrank dimensions.
• Image driver matters for export time. Imagick typically beats GD on thumbnail throughput for large parts; if exports feel slow, check the driver before touching chunk size. Lowering chunk size increases total overhead — it rarely helps.
• The filter-width fix is cosmetic but reveals a layout assumption. Filters now size to their longest option; test with long translated labels and narrow viewports, since a very long option can push the layout rather than truncate it.
• Extension point: the PDF part endpoint and thumbnail renderer are the two places worth wrapping in your own service class. Everything else in the export pipeline is best left to the package.