wnx / sidecar-browsershot
A Sidecar function to run Browsershot on Lambda.
Fund package maintenance!
stefanzweifel
Installs: 541 542
Dependents: 4
Suggesters: 0
Security: 0
Stars: 196
Watchers: 6
Forks: 26
Open Issues: 7
Requires
- php: ^8.2
- hammerstone/sidecar: ^0.4 || ^0.5 || ^0.6
- illuminate/contracts: ^10.0 || ^11.0
- spatie/browsershot: ^4.0
- spatie/laravel-package-tools: ^1.9.2
Requires (Dev)
- ext-imagick: *
- larastan/larastan: ^1.0|^2.0
- laravel/pint: ^1.13
- league/flysystem-aws-s3-v3: ^1.0|^2.0|^3.0
- nunomaduro/collision: ^7.0|^8.0
- orchestra/testbench: ^8.0|^9.0
- pestphp/pest: ^2.0
- pestphp/pest-plugin-laravel: ^2.0
- phpstan/extension-installer: ^1.1
- phpstan/phpstan-deprecation-rules: ^1.0
- phpstan/phpstan-phpunit: ^1.0
- phpunit/phpunit: ^10 | ^11.0
- spatie/image: ^3.3
- spatie/pixelmatch-php: dev-main
- dev-main
- v2.3.3
- v2.3.2
- v2.3.1
- v2.3.0
- v2.2.0
- v2.1.0
- v2.0.0
- v1.13.1
- v1.13.0
- v1.12.0
- v1.11.1
- v1.11.0
- v1.10.0
- v1.9.1
- v1.9.0
- v1.8.1
- v1.8.0
- v1.7.0
- v1.6.4
- v1.6.3
- v1.6.2
- v1.6.1
- v1.6.0
- v1.5.0
- v1.4.1
- v1.4.0
- v1.3.0
- v1.2.1
- v1.2.0
- v1.1.0
- v1.0.1
- v1.0.0
- v0.2.0
- v0.1.0
- dev-upgrade-layers
- dev-fix/deprecated-node-methods
This package is auto-updated.
Last update: 2024-11-03 10:04:51 UTC
README
This package allows you to run Browsershot on AWS Lambda through Sidecar.
You won't need to install Node, Puppeteer or Google Chrome on your server. The heavy lifting of booting a headless Google Chrome instance is happening on AWS Lambda.
Requirements
This package requires that spatie/browsershot
and hammerstone/sidecar
have been installed in your Laravel application.
Follow their installation and configuration instructions. (You can skip the installation of puppeteer and Google Chrome for Browsershot though.)
Installation
You can install the package via composer:
composer require wnx/sidecar-browsershot
You can publish the config file with:
php artisan vendor:publish --tag="sidecar-browsershot-config"
Register the BrowsershotFunction::class
in your sidecar.php
config file.
/* * All of your function classes that you'd like to deploy go here. */ 'functions' => [ \Wnx\SidecarBrowsershot\Functions\BrowsershotFunction::class, ],
Deploy the Lambda function by running:
php artisan sidecar:deploy --activate
See Sidecar documentation for details.
Note
You should redeploy the Lambda function, whenever you upgrade spatie/browsershot
.
Usage
You can use BrowsershotLambda
like the default Browsershot
-class coming from the Spatie package.
All you need to do is replace Browsershot
with BrowsershotLambda
.
use Wnx\SidecarBrowsershot\BrowsershotLambda; // an image will be saved BrowsershotLambda::url('https://example.com')->save($pathToImage); // a pdf will be saved BrowsershotLambda::url('https://example.com')->save('example.pdf'); // save your own HTML to a PDF BrowsershotLambda::html('<h1>Hello world!!</h1>')->save('example.pdf'); // Get HTML of a URL and store it on a given disk $html = BrowsershotLambda::url('https://example.com')->bodyHtml(); Storage::disk('s3')->put('example.html', $html);
Warming
sidecar-browsershot supports warming for faster execution.
To enable this feature set the SIDECAR_BROWSERSHOT_WARMING_INSTANCES
variable in your .env
to the desired number of instances Sidecar should warm for you.
SIDECAR_BROWSERSHOT_WARMING_INSTANCES=5
Alternatively you can publish the sidecar-browsershot.php
config file and change the warming
setting yourself.
Reading source from S3
You can store an HTML file on AWS S3 and pass the path to Lambda for it to create the PDF or image from. This is necessary for large source files in order to avoid restrictions on the size of Lambda requests.
use Wnx\SidecarBrowsershot\BrowsershotLambda; // Use an HTML file from S3 to generate a PDF BrowsershotLambda::readHtmlFromS3('html/example.html')->save('example.pdf'); // You can also pass a disk name if required (default: 's3') BrowsershotLambda::readHtmlFromS3('html/example.html', 's3files')->save('example.pdf');
Saving directly to S3
You can store your file directly on AWS S3 if you want to keep it there, or to avoid the size limit on Lambda responses.
You just need to pass a path and optional disk name (default: 's3') to the saveToS3
method.
- You must have an S3 disk defined in config/filesystems.php
- You must give S3 write permissions to your sidecar-execution-role
use Wnx\SidecarBrowsershot\BrowsershotLambda; // an image will be saved on S3 BrowsershotLambda::url('https://example.com')->saveToS3('example.jpg'); // a pdf will be saved on S3 BrowsershotLambda::url('https://example.com')->saveToS3('example.pdf'); // save your own html to a PDF on S3 BrowsershotLambda::html('<h1>Hello world!!</h1>')->saveToS3('example.pdf', 'example-store');
Image Manipulation
Like the original Browsershot package, you can manipulate the image size and format.
To perform image manipulations on the screenshot, you need to install the optional dependency spatie/image
. v3 or higher is required.
Note
If you're usingfit()
in combination withsaveToS3
, the image will be downloaded from S3 to your local disc, manipulated and then uploaded back to S3.
// Take screenshot at 1920x1080 and scale it down to fit 200x200 BrowsershotLambda::url('https://example.com') ->windowSize(1920, 1080) ->fit(\Spatie\Image\Enums\Fit::Contain, 200, 200) ->save('example.jpg'); // Take screenshot at 1920x1080 and scale it down to fit 200x200 and save it on S3 // Note: To do the image manipulation, BrowsershotLambda will download the image // from S3 to the local disc of your app, manipulate it and then upload it back to S3. BrowsershotLambda::url('https://example.com') ->windowSize(1920, 1080) ->fit(\Spatie\Image\Enums\Fit::Contain, 200, 200) ->saveToS3('example.jpg');
Register Custom Fonts
By default, sidecar-browsershot includes the "Noto Color Emoji"-font, to ensure that emojis are rendered correctly.
If you want to use custom fonts, you can put them all into a resources/sidecar-browsershot/fonts
-folder. (You can customize the location of that folder in the sidecar-browsershot.fonts
config)
sidecar-browsershot will include all files in that folder when deploying the Lambda function and will register them automatically in Chromium for you.
Testing
The testsuite makes connections to AWS and runs the deployed Lambda function. In order to run the testsuite, you will need an active AWS account.
We can use the native sidecar:configure
artisan command to create the necessary AWS credentials for Sidecar. First copy the testbench.example.yaml
file to testbench.yaml
.
Then run ./vendor/bin/testbench sidecar:configure
to start the Sidecar setup process. (You only have to do the setup once)
cp testbench.example.yaml testbench.yaml cp .env.example .env ./vendor/bin/testbench sidecar:configure
After finishing the Sidecar setup process, you will have received a couple of SIDECAR_*
environment variables. Add these credentials to .env
.
Now we can deploy our local BrowsershotFunction
to AWS Lambda. Run the following command in your terminal, before executing the testsuite.
./vendor/bin/testbench sidecar-browsershot:setup
After the successful deployment, you can run the testsuite.
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
License
The MIT License (MIT). Please see License File for more information.