PHPackages                             eduardoribeirodev/browsershot - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. eduardoribeirodev/browsershot

ActiveLibrary[Utility & Helpers](/categories/utility)

eduardoribeirodev/browsershot
=============================

This is my package browsershot

v2.0.0(2mo ago)122MITPHPPHP ^8.2

Since Feb 13Pushed 2mo agoCompare

[ Source](https://github.com/eduardoribeirodev/browsershot)[ Packagist](https://packagist.org/packages/eduardoribeirodev/browsershot)[ Docs](https://github.com/eduardoribeirodev/browsershot)[ RSS](/packages/eduardoribeirodev-browsershot/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)Dependencies (5)Versions (4)Used By (0)

Laravel Browsershot Service
===========================

[](#laravel-browsershot-service)

A fluent Laravel wrapper for [Spatie's Browsershot](https://github.com/spatie/browsershot) package that simplifies generating screenshots and PDFs from HTML content or Blade views.

Features
--------

[](#features)

- 🎨 Generate PDFs and screenshots from Blade views, HTML strings, or URLs
- 📐 Flexible sizing with unit support (px, mm, cm, in) and aspect ratio helpers
- 📄 Named paper format shortcuts (A0–A6, Letter, Legal, Tabloid, Ledger)
- 🔧 Fluent, chainable API
- 💾 Multiple output options (download, save to storage, base64)
- 🚀 Automatic HTML structure wrapping
- ⚡ High-resolution output with device scale factor support

Installation
------------

[](#installation)

```
composer require eduardoribeirodev/browsershot
```

### Prerequisites

[](#prerequisites)

This package requires Puppeteer/Chromium to be installed. Follow [Spatie's Browsershot installation guide](https://spatie.be/docs/browsershot/v4/requirements) for your environment.

```
npm install puppeteer
```

Configuration
-------------

[](#configuration)

Add the Chrome path to your `config/services.php`:

```
'browsershot' => [
    'chrome_path' => env('BROWSERSHOT_CHROME_PATH', '/usr/bin/chromium-browser'),
],
```

Set the path in your `.env` file:

```
BROWSERSHOT_CHROME_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" # Mac
BROWSERSHOT_CHROME_PATH="/usr/bin/chromium-browser"                                     # Linux
BROWSERSHOT_CHROME_PATH="C:\Program Files (x86)\Google\Chrome\Application\chrome.exe"  # Windows
```

Basic Usage
-----------

[](#basic-usage)

### Generate PDF from Blade View

[](#generate-pdf-from-blade-view)

```
use EduardoRibeiroDev\Browsershot\Facades\Browsershot;

$pdf = Browsershot::make(view('invoice', $data))
    ->pdf()
    ->generate();
```

### Generate Screenshot from HTML

[](#generate-screenshot-from-html)

```
$screenshot = Browsershot::make('Hello World')
    ->png()
    ->generate();
```

### Download PDF in a Controller

[](#download-pdf-in-a-controller)

```
return Browsershot::make(view('report'))
    ->a4()
    ->pdf()
    ->download('monthly-report.pdf');
```

API Reference
-------------

[](#api-reference)

### Initialization

[](#initialization)

#### `make(View|string $content, array $data = []): self`

[](#makeviewstring-content-array-data---self)

Creates a new instance. Accepts a Blade `View` object, a view name string, a URL, or a raw HTML string.

```
// From a View object
Browsershot::make(view('documents.invoice', $data));

// From a view name (with optional data)
Browsershot::make('documents.invoice', $data);

// From a URL
Browsershot::make('https://example.com');

// From a raw HTML string
Browsershot::make('Content here');
```

---

### Size & Viewport

[](#size--viewport)

#### `size(int $width, int $height, string $unit = 'px'): self`

[](#sizeint-width-int-height-string-unit--px-self)

Sets the viewport/paper dimensions. Supported units: `px`, `mm`, `cm`, `in`.

```
Browsershot::make($view)->size(1920, 1080)->generate();
Browsershot::make($view)->size(210, 297, 'mm')->generate(); // A4
```

#### `center(int $x, int $y): self`

[](#centerint-x-int-y-self)

Sets the clip origin. Must be combined with `size()`.

```
Browsershot::make($view)->center(100, 50)->size(800, 600)->generate();
```

#### `clip(int $x, int $y, int $width, int $height): self`

[](#clipint-x-int-y-int-width-int-height-self)

Shorthand for setting both `center` and `size` at once.

```
Browsershot::make($view)->clip(0, 0, 1200, 800)->generate();
```

#### `scale(float $scale): self`

[](#scalefloat-scale-self)

Sets the device scale factor for high-resolution output.

```
// 2× resolution (Retina)
Browsershot::make($view)->scale(2)->generate();
```

#### `aspectRatio(string|float $ratio): self`

[](#aspectratiostringfloat-ratio-self)

Adjusts the current size to match a given aspect ratio. Must call `size()` first.

```
Browsershot::make($view)
    ->size(1920, 1080)
    ->aspectRatio('16:9')   // string form
    ->generate();

Browsershot::make($view)
    ->size(1200, 900)
    ->aspectRatio(4 / 3)    // float form
    ->generate();
```

---

### Paper Format Shortcuts

[](#paper-format-shortcuts)

These methods set the viewport to a standard paper size (in mm). An optional `$scale` multiplier can be passed to `format()`.

#### `format(string $format, float $scale = 1): self`

[](#formatstring-format-float-scale--1-self)

```
Browsershot::make($view)->format('A4')->generate();
Browsershot::make($view)->format('Letter', 2)->generate(); // 2× scale
```

**Named shortcuts** (equivalent to calling `format()` with the matching name):

MethodDimensions (mm)`a0()`841 × 1189`a1()`594 × 841`a2()`420 × 594`a3()`297 × 420`a4()`210 × 297`a5()`148 × 210`a6()`105 × 148`letter()`216 × 279`legal()`216 × 356`tabloid()`279 × 432`ledger()`432 × 279```
Browsershot::make($view)->a4()->pdf()->download('doc.pdf');
Browsershot::make($view)->letter()->landscape()->pdf()->generate();
```

---

### Orientation

[](#orientation)

#### `landscape(bool $landscape = true): self`

[](#landscapebool-landscape--true-self)

#### `portrait(): self`

[](#portrait-self)

```
Browsershot::make($view)->a4()->landscape()->pdf()->generate();
Browsershot::make($view)->a4()->portrait()->pdf()->generate();
```

---

### Margins

[](#margins)

#### `margin(int $size, string $unit = 'mm'): self`

[](#marginint-size-string-unit--mm-self)

Applies a uniform margin to all four sides.

```
Browsershot::make($view)->a4()->margin(10)->pdf()->generate();
```

#### `margins(int $top, int $right, int $bottom, int $left, string $unit = 'mm'): self`

[](#marginsint-top-int-right-int-bottom-int-left-string-unit--mm-self)

Sets each margin individually in one call.

```
Browsershot::make($view)->margins(10, 15, 10, 15)->pdf()->generate();
```

#### `marginTop / marginRight / marginBottom / marginLeft`

[](#margintop--marginright--marginbottom--marginleft)

Fluent per-side setters.

```
Browsershot::make($view)
    ->marginTop(20)
    ->marginBottom(20)
    ->pdf()
    ->generate();
```

---

### Output Format

[](#output-format)

#### `pdf(): self`

[](#pdf-self)

#### `png(): self`

[](#png-self)

#### `jpeg(): self`

[](#jpeg-self)

#### `webp(): self`

[](#webp-self)

#### `extension(string $extension): self`

[](#extensionstring-extension-self)

Sets the output file format. The named helpers are shorthands for `extension()`.

```
Browsershot::make($view)->pdf()->generate();
Browsershot::make($view)->png()->generate();
Browsershot::make($view)->jpeg()->generate();
Browsershot::make($view)->webp()->generate();
Browsershot::make($view)->extension('png')->generate(); // equivalent
```

---

### PDF-Specific Options

[](#pdf-specific-options)

#### `pages(...$pages): self`

[](#pagespages-self)

Selects specific pages (or page ranges) to include in the PDF output.

```
// Single pages
Browsershot::make($view)->pdf()->pages(1, 3, 5)->generate();

// Ranges (passed as arrays)
Browsershot::make($view)->pdf()->pages([1, 3], [5, 7])->generate();

// Mixed
Browsershot::make($view)->pdf()->pages(1, [3, 5], 8)->generate();
```

---

### Sandbox

[](#sandbox)

#### `noSandbox(bool $noSandbox = true): self`

[](#nosandboxbool-nosandbox--true-self)

Disables Chrome's sandbox — required in most Docker/CI environments.

```
Browsershot::make($view)->noSandbox()->generate();

// Re-enable (not usually needed)
Browsershot::make($view)->noSandbox(false)->generate();
```

---

### Advanced Customization

[](#advanced-customization)

#### `modifyBrowsershotUsing(Closure $callback): self`

[](#modifybrowsershotusingclosure-callback-self)

Provides direct access to the underlying `Spatie\Browsershot\Browsershot` instance for options not exposed by this wrapper.

```
use Spatie\Browsershot\Browsershot;

Browsershot::make($view)
    ->modifyBrowsershotUsing(function (Browsershot $browsershot) {
        $browsershot->waitUntilNetworkIdle()->timeout(60);
    })
    ->pdf()
    ->generate();
```

---

### Output Methods

[](#output-methods)

#### `generate(): string`

[](#generate-string)

Returns the raw binary content.

```
$content = Browsershot::make($view)->pdf()->generate();
Storage::put('file.pdf', $content);
```

#### `download(?string $fileName = null): StreamedResponse`

[](#downloadstring-filename--null-streamedresponse)

Streams the file as a browser download. The correct extension is appended automatically if missing.

```
return Browsershot::make($view)->pdf()->download('invoice-2025.pdf');
return Browsershot::make($view)->pdf()->download('invoice'); // → invoice.pdf
return Browsershot::make($view)->pdf()->download();          // → document-{timestamp}.pdf
```

#### `save(string $path, ?string $disk = null): bool`

[](#savestring-path-string-disk--null-bool)

Saves to Laravel's filesystem. Uses the default disk when `$disk` is omitted.

```
// Default disk
Browsershot::make($view)->pdf()->save('invoices/invoice-123.pdf');

// Specific disk
Browsershot::make($view)->pdf()->save('reports/report.pdf', 'public');
```

#### `toBase64(): string`

[](#tobase64-string)

Returns the content as a base64-encoded string.

```
$base64 = Browsershot::make($view)->png()->toBase64();
echo "";
```

---

HTML Structure Handling
-----------------------

[](#html-structure-handling)

The service automatically wraps partial HTML in a complete document structure:

InputOutput`Title` (fragment)Full document: `DOCTYPE` + `` + `` + ```……`Wraps with `DOCTYPE` + ```…`Adds `DOCTYPE`, ``, and ```…`Used as-is---

Advanced Examples
-----------------

[](#advanced-examples)

### A4 Invoice PDF

[](#a4-invoice-pdf)

```
public function generateInvoice(Invoice $invoice)
{
    return Browsershot::make('invoices.template', [
        'invoice'  => $invoice,
        'customer' => $invoice->customer,
        'items'    => $invoice->items,
    ])
        ->a4()
        ->margin(15)
        ->pdf()
        ->download("invoice-{$invoice->number}.pdf");
}
```

### High-Resolution Social Media Image

[](#high-resolution-social-media-image)

```
public function generateSocialImage(Post $post)
{
    Browsershot::make(view('social.og-image', compact('post')))
        ->size(1200, 630) // Open Graph dimensions
        ->scale(2)        // Retina quality
        ->png()
        ->save("social/post-{$post->id}.png");

    return Storage::url("social/post-{$post->id}.png");
}
```

### Certificate with Clip Region

[](#certificate-with-clip-region)

```
public function generateCertificate(User $user, Course $course)
{
    return Browsershot::make('certificates.template', [
        'userName'       => $user->name,
        'courseName'     => $course->title,
        'completionDate' => now()->format('F d, Y'),
    ])
        ->size(1920, 1357)
        ->scale(2)
        ->pdf()
        ->download("certificate-{$user->id}-{$course->id}.pdf");
}
```

### Thumbnail as Base64

[](#thumbnail-as-base64)

```
public function generateThumbnail(string $htmlContent)
{
    $thumbnail = Browsershot::make($htmlContent)
        ->size(800, 600)
        ->jpeg()
        ->toBase64();

    return response()->json([
        'thumbnail' => "data:image/jpeg;base64,{$thumbnail}",
    ]);
}
```

### Batch Report Generation

[](#batch-report-generation)

```
public function generateMonthlyReports(Collection $departments)
{
    $departments->each(function ($department) {
        Browsershot::make('reports.monthly', compact('department'))
            ->a4()
            ->landscape()
            ->pdf()
            ->save("reports/{$department->slug}-" . now()->format('Y-m') . ".pdf");
    });

    return "Generated {$departments->count()} reports";
}
```

### Custom Browsershot Options

[](#custom-browsershot-options)

```
public function captureWithCustomOptions()
{
    return Browsershot::make('https://example.com')
        ->size(1920, 1080)
        ->png()
        ->modifyBrowsershotUsing(function ($b) {
            $b->waitUntilNetworkIdle()->timeout(30);
        })
        ->download('screenshot.png');
}
```

---

Testing
-------

[](#testing)

```
use EduardoRibeiroDev\Browsershot\Facades\Browsershot;
use Illuminate\Support\Facades\Storage;

test('can generate pdf from view', function () {
    Storage::fake('local');

    $result = Browsershot::make('test-view')
        ->a4()
        ->pdf()
        ->save('test.pdf');

    expect($result)->toBeTrue();
    Storage::assertExists('test.pdf');
});

test('can generate high resolution screenshot', function () {
    $content = Browsershot::make('Test')
        ->size(1920, 1080)
        ->scale(2)
        ->png()
        ->generate();

    expect($content)->toBeString()->not->toBeEmpty();
});
```

---

Troubleshooting
---------------

[](#troubleshooting)

### Chrome/Chromium Not Found

[](#chromechromium-not-found)

```
# Ubuntu/Debian
sudo apt-get install chromium-browser

# macOS
brew install chromium

# Update .env accordingly
BROWSERSHOT_CHROME_PATH=/usr/bin/chromium-browser
```

### Permission Issues in Docker

[](#permission-issues-in-docker)

```
Browsershot::make($view)->noSandbox()->generate();
```

### Memory Issues with Large PDFs

[](#memory-issues-with-large-pdfs)

```
ini_set('memory_limit', '512M');

Browsershot::make($largeView)->pdf()->generate();
```

---

Performance Tips
----------------

[](#performance-tips)

1. **Cache generated content** when possible
2. **Use queues** for batch generation
3. **Optimize Blade views** — minimize CSS/JS complexity
4. **Set appropriate sizes** — don't generate larger than needed
5. **Choose the right format** — JPEG is smaller than PNG for photographic content

---

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT license](LICENSE.md).

Credits
-------

[](#credits)

- Built on top of [Spatie Browsershot](https://github.com/spatie/browsershot)
- Developed by Eduardo Ribeiro

Support
-------

[](#support)

For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/eduardoribeirodev/browsershot).

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance85

Actively maintained with recent releases

Popularity10

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~5 days

Total

3

Last Release

79d ago

Major Versions

v1.1.0 → v2.0.02026-02-23

PHP version history (2 changes)v1.0.0PHP ^8.4

v1.1.0PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/7958cfd6d3da8f038f38be32f20b6d17bb30e05d492f3e4edd695afb2584a005?d=identicon)[eduardoribeirodev](/maintainers/eduardoribeirodev)

---

Top Contributors

[![eduardoribeirodev](https://avatars.githubusercontent.com/u/184874831?v=4)](https://github.com/eduardoribeirodev "eduardoribeirodev (11 commits)")

---

Tags

browsershoteduardoribeirodev

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/eduardoribeirodev-browsershot/health.svg)

```
[![Health](https://phpackages.com/badges/eduardoribeirodev-browsershot/health.svg)](https://phpackages.com/packages/eduardoribeirodev-browsershot)
```

###  Alternatives

[wnx/sidecar-browsershot

A Sidecar function to run Browsershot on Lambda.

2331.5M5](/packages/wnx-sidecar-browsershot)[42coders/document-templates

Document template management package.

19939.5k](/packages/42coders-document-templates)[backstage/laravel-seo-scanner

The Laravel tool to boost the SEO score of your web pages.

2603.5k](/packages/backstage-laravel-seo-scanner)[topshelfcraft/environment-label

...so you don't forget where you are.

16231.4k10](/packages/topshelfcraft-environment-label)[aerni/advanced-seo

Comprehensive SEO addon for Statamic with flexibility in mind

1316.6k](/packages/aerni-advanced-seo)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)