- How do I install wnx/sidecar-browsershot in a Laravel app?
- Install it with composer require wnx/sidecar-browsershot, then publish the package config using php artisan vendor:publish --tag="sidecar-browsershot-config". You must already have spatie/browsershot and hammerstone/sidecar installed and configured, though you can skip installing Puppeteer and Google Chrome. Register Wnx\SidecarBrowsershot\Functions\BrowsershotFunction::class in your sidecar.php functions array and deploy with php artisan sidecar:deploy --activate.
- What Laravel and PHP versions does wnx/sidecar-browsershot support?
- The package is a Laravel integration for Sidecar and Browsershot, so your Laravel and PHP versions must satisfy those dependencies' constraints. Check the package composer.json and the Sidecar documentation for the current support matrix before installing. Because the package is actively maintained, recent Laravel releases are generally supported, but pin versions and test upgrades in CI.
- How do I switch from Browsershot to BrowsershotLambda?
- Replace Spatie\Browsershot\Browsershot with Wnx\SidecarBrowsershot\BrowsershotLambda in your application code. BrowsershotLambda preserves the familiar fluent Browsershot API, so calls such as screenshot, save, and PDF generation continue to work with minimal rewrites. The rendering work is sent to the deployed Sidecar Lambda function instead of running Chrome locally.
- How do I deploy or redeploy the Browsershot Lambda function?
- Register BrowsershotFunction::class in the functions array of config/sidecar.php, then run php artisan sidecar:deploy --activate. Your environment needs AWS credentials and permissions that allow Sidecar to create and update the Lambda function and related resources. Redeploy the function whenever you upgrade spatie/browsershot so the Lambda runtime matches the package version.
- Why should I use readHtmlFromS3 or saveToS3 with BrowsershotLambda?
- AWS Lambda has request and response payload size limits, so large HTML inputs and generated PDFs or screenshots can exceed what Sidecar can pass directly. The package provides readHtmlFromS3 and saveToS3 to move large payloads through S3, which is the recommended architectural pattern. This makes S3 a first-class dependency: configure an S3 disk in config/filesystems.php and grant the Lambda execution role the necessary S3 permissions.
- Does wnx/sidecar-browsershot support Lambda warming to reduce cold starts?
- Cold starts are possible because the Lambda function must boot a Node, Puppeteer, and Chromium environment before rendering. Sidecar supports warming configuration, and you can also evaluate provisioned concurrency for latency-sensitive PDF or screenshot generation. The package itself does not guarantee latency SLOs, so benchmark your payload sizes and traffic patterns before relying on it in production.
- How can I test wnx/sidecar-browsershot without hitting AWS in every test?
- The package's own test suite runs against real AWS and a deployed Lambda function, which is useful as an integration reference but not a hermetic local test suite. For application tests, mock or fake the boundary where you call BrowsershotLambda, or run a smaller number of integration tests in CI with AWS credentials. Keep fast unit tests for the code that prepares HTML and file paths, and reserve real Lambda calls for pre-release verification.
- Is it safe to render untrusted user-supplied HTML or URLs with Browsershot on Lambda?
- Rendering arbitrary URLs from inside your AWS account can create SSRF and egress risks because the Lambda may be able to reach internal endpoints. Treat untrusted HTML and URLs as a security boundary: apply network egress controls, avoid rendering internal addresses, and sanitize or constrain input where possible. Also keep Chromium and NPM layers patched, since several releases include security fixes.
- How often does wnx/sidecar-browsershot have breaking changes, and how should I manage upgrades?
- The package tracks Browsershot, Puppeteer, Node JS, and Chromium versions, and its changelog shows runtime jumps plus breaking changes such as config key renames and removed methods. Pin the package and its related dependencies, read the changelog before upgrading, and schedule regular upgrade windows. If you override the Chromium layer, test that customization carefully and redeploy the Lambda function after Browsershot upgrades.
- When should I avoid wnx/sidecar-browsershot and what are the alternatives?
- Avoid it if you are not on AWS, if data residency or network egress rules prevent sending rendering inputs to Lambda, or if you cannot operate a second deployment artifact with its own IAM role. In those cases, self-hosted Browsershot with Node, Puppeteer, and Chrome, a containerized rendering service, or a managed screenshot/PDF API may be a better fit. The application call sites stay fairly portable because BrowsershotLambda keeps the Spatie Browsershot API, but moving off Lambda is a re-architecture of the execution layer.