README

This package provides a way to add "Download" buttons to your Backpack CRUDs. By default:

the file format will be a PDF;
the file will show a list of CRUD fields, similar to the Show Operation;

Demo

Requirements

This package uses Backpack for Laravel (of course) but also spatie/browsershot, which itself uses Puppeteer, which itself uses a headless Chrome browser to generate the PDFs. Because of that:

PRO: you don't need to code special views for them to look good in PDF form; if it looks good in the browser, it'll probably look good in the PDF;
CON: you need to install a bunch of stuff on your server (Puppeteer and Chrome); so you probably can't use this on shared hosting;

Installation

Step 0. Install Puppeteer and spatie/browsershot, as instructed by Browsershot documentation. Then test your installation by runnning a tinker session (php artisan tinker) with the following code: \Spatie\Browsershot\Browsershot::url('https://google.com')->ignoreHttpsErrors()->save('example.pdf');. If that simple code triggers errors, please fix your Browsershot / Puppeteer installation before going any further. We've provided a few troubleshooting tips & tricks at the bottom of this page.

Step 1. Install this package via Composer

composer require backpack/download-operation

Step 2. To add a "Download" button next to each entry inside your EntityCrudController and a bulk button at the bottom of the table, use these operations on your EntityCrudController:

class InvoiceCrudController extends CrudController
{
    use \Backpack\CRUD\app\Http\Controllers\Operations\ListOperation;
    use \Backpack\CRUD\app\Http\Controllers\Operations\DeleteOperation;
+    use \Backpack\DownloadOperation\DownloadOperation;
+    use \Backpack\DownloadOperation\BulkDownloadOperation;

Please note that BulkDownload is not a "real" operation. It's just a button that points to the normal "Download" operation. So you cannot use BulkDeleteOperation without DeleteOperation.

Step 3. Configure your download operation by defining your fields and settings in setupDownloadOperation()

    /**
     * Configure what the Download button actually downloads.
     */
    public function setupDownloadOperation()
    {
        // you can of course manually add your columns:
        CRUD::column('title');
        
        // but since you've probably already defined columns in your List or Show operation, you could do:
        $this->setupListOperation();
        
        // in addition, in case you want to change settings:
        CRUD::set('download.view', 'user.invoice.wrapper'); // default is 'crud::show'
        CRUD::set('download.format', 'A4'); // default is 'A4'
        CRUD::set('download.headers', ['Content-Type' => 'application/pdf']); // default is 'A4'
    }

Overriding

If you need to change anything else about the generated file (like changing from PDF to something else), you can create a downloadFile() method in your EntityCrudController. That will give you the freedom to change anything you want:

    protected function downloadFile($data)
    {
        return response()->streamDownload(function () use ($data) {
            echo Browsershot::html(view($data['view'], $data))
                ->format($data['format'])
                ->pdf();
        }, $data['filename'], $data['headers']);
    }

Changelog

Changes are documented here on Github. Please see the Releases tab.

Contributing

Please see contributing.md for a todolist and howtos.

Security

If you discover any security related issues, please email cristian.tabacitu@backpackforlaravel.com instead of using the issue tracker.

Credits

License

This project was released under MIT, so you can install it on top of any Backpack & Laravel project. Please see the license file for more information.

Troubleshooting

This package uses spatie/browsershot, which uses Puppetteer, which itself uses a headless Chrome. So... a lot can go wrong during the installation phase. It can either go silky-smooth or be a nightmare. To help you out, here are a few issues we've encountered, and their solutions.

How to test if the Puppeteer installation is working

We recommend you run a tinker (php artisan tinker) and try the following:

use Spatie\Browsershot\Browsershot;

Browsershot::url('https://google.com')->ignoreHttpsErrors()->save('example.pdf');

If that triggers errors... the problem is with your Puppeteer installation. Take a hard look at the error message, it might provide steps to fix or clues.

Could not find Chromium (rev. 1095492)

We've gotten this error, along the years, for multiple reasons:

we had to upgrade the node version
we were not using that node version
the chache path was indeed incorrect (see below)

Cache path is wrong (eg. on MacOS when using Laravel Valet)

In your error message, see what cache path is being used. Most likely it's trying to use .cache/puppeteer inside the PROJECT DIRECTORY. Which is wrong, because it definitely won't find Chrome there. You want it to use the GLOBAL DIRECTORY. To define a cache path for a particular project, you can define a new .ENV variable:

PUPPETEER_CACHE_DIR="/Users/tabacitu/.cache/puppeteer"

You might also need to create that directory and restart your server. After that, it should work.

Does not work on M1 Mac (aka. chromium arm64 bug)

If you're running an M1 or M2 Mac, you might need to follow this tutorial.

backpack / download-operation

Maintainers

Details