sensiolabs / gotenberg-bundle
Gotenberg support for Symfony
Installs: 4 570
Dependents: 1
Suggesters: 0
Security: 0
Stars: 60
Watchers: 6
Forks: 12
Open Issues: 18
Type:symfony-bundle
Requires
- php: >=8.1
- psr/container: ^2.0
- psr/log: ^3.0
- symfony/config: ^6.4 || ^7.0
- symfony/dependency-injection: ^6.4 || ^7.0
- symfony/filesystem: ^6.4 || ^7.0
- symfony/http-client-contracts: ^3.5
- symfony/http-foundation: ^6.4 || ^7.0
- symfony/http-kernel: ^6.4 || ^7.0
- symfony/mime: ^6.4 || ^7.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.41
- phpstan/extension-installer: ^1.3
- phpstan/phpstan: ^1.10
- phpstan/phpstan-symfony: ^1.3
- phpunit/phpunit: ^10.4
- shipmonk/composer-dependency-analyser: ^1.7
- symfony/framework-bundle: ^6.4 || ^7.0
- symfony/http-client: ^6.4 || ^7.0
- symfony/monolog-bundle: ^3.10
- symfony/routing: ^6.4 || ^7.0
- symfony/stopwatch: ^6.4 || ^7.0
- symfony/twig-bundle: ^6.4 || ^7.0
- symfony/var-dumper: ^6.4 || ^7.0
- twig/twig: ^3.14
Suggests
- monolog/monolog: Enables logging througout the generating process.
- symfony/monolog-bundle: Enables logging througout the generating process.
- symfony/twig-bundle: Allows you to use Twig to render templates into PDF
README
Warning
This Bundle is experimental and subject to change in a future release.
What is it ?
This bundle allows you to generate, stream and save PDF locally from URL, HTML, Markdown or any Office file. Different options are available depending on the source.
It also helps you to generate, stream and save images locally from URL, HTML and Markdown using a screenshot.
How to install
Install the bundle using composer :
composer require sensiolabs/gotenberg-bundle
With Symfony Flex
If you accept the Symfony Flex recipe during installation, the bundle is registered, the configuration
skeleton file is created, the .env file is updated with GOTENBERG_DSN and dockerfile is also created
to get the gotenberg image, you need to configure the ports
related to GOTENBERG_DSN in your .env file.
The host could be updated too since it's localhost by default.
If your script is run in a container, the host will be gotenberg.
You can now adapt the configuration file to your needs.
Without Symfony Flex
Caution
To use this bundle, you first need to install and configure Gotenberg 8.x.
Enable the bundle by adding it to the list of registered bundles in the config/bundles.php file of your project:
// config/bundles.php return [ // ... SensioLabs\GotenbergBundle\SensioLabsGotenbergBundle::class => ['all' => true], ];
Basic Usage
You can generate a PDF locally from URL, HTML, Markdown or any Office files.
URL
After injecting GotenbergPdfInterface you simply need to call the method url,
which will return a UrlPdfBuilder instance.
UrlPdfBuilder lets you pass the URL of the page you want to convert into PDF
to the method url.
namespace App\Controller; use Sensiolabs\GotenbergBundle\GotenbergPdfInterface; class YourController { public function yourControllerMethod(GotenbergPdfInterface $gotenberg): Response { return $gotenberg->url() ->url('https://sensiolabs.com/fr/') ->generate() ->stream() // will return directly a stream response ; } }
Tip
For more information go to Gotenberg documentations.
Twig
Warning
Every twig templates you pass to Gotenberg need to have the following structure.
Even Header or Footer parts.
<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8" /> <title>My PDF</title> </head> <body> <!-- Your code goes here --> </body> </html>
namespace App\Controller; use Sensiolabs\GotenbergBundle\GotenbergPdfInterface; class YourController { public function yourControllerMethod(GotenbergPdfInterface $gotenberg): Response { return $gotenberg->html() ->content('twig_simple_pdf.html.twig', [ 'my_var' => 'value' ]) ->generate() ->stream() // will return directly a stream response ; } }
If a template needs to link to a static asset (e.g. an image), this bundle provides a {{ gotenberg_asset() }}
Twig function to generate the correct path AND add it to the builder automatically.
This function work as asset() Twig function
and fetch your assets in the assets folder of your application
If your files are in another folder, you can override the default value of assets_directory in your
configuration file config/sensiolabs_gotenberg.yml.
The path provided can be relative as well as absolute.
<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8" /> <title>PDF body</title> </head> <body> <main> <h1>Hello world!</h1> <img src="{{ gotenberg_asset('public/img/ceo.jpeg') }}" alt="CEO"/> <img src="{{ gotenberg_asset('public/img/admin.jpeg') }}" alt="Admin"/> </main> </body> </html>
Tip
For more information go to Gotenberg documentations.
Screenshot
You can generate a screenshot locally from URL, HTML and Markdown.
URL
After injecting GotenbergScreenshotInterface you simply need to call the method url,
which will return a UrlScreenshotBuilder instance.
UrlScreenshotBuilder lets you pass the URL of the page you want to convert into screenshot
to the method url.
namespace App\Controller; use Sensiolabs\GotenbergBundle\GotenbergScreenshotInterface; class YourController { public function yourControllerMethod(GotenbergScreenshotInterface $gotenberg): Response { return $gotenberg->url() ->url('https://sensiolabs.com/fr/') ->generate() ->stream() ; } }
Twig
After injecting GotenbergScreenshotInterface you simply need to call the method html,
which will return a HtmlScreenshotBuilder instance.
HtmlScreenshotBuilder lets you pass the content of the page you want to convert into screenshot
to the method content.
namespace App\Controller; use Sensiolabs\GotenbergBundle\GotenbergScreenshotInterface; class YourController { public function yourControllerMethod(GotenbergScreenshotInterface $gotenberg): Response { return $gotenberg->html() ->content('twig_simple_pdf.html.twig', [ 'my_var' => 'value' ]) ->generate() ->stream() ; } }
Tip
For more information go to Gotenberg documentations.
Advanced Usage
- Add header / footer
- HTML Builder
- Markdown Builder
- Url Builder
- Office Builder (available extensions for conversion below)
123,602,abw,bib,bmp,cdr,cgm,cmx,csv,cwk,dbf,dif,doc,docm,docx,dot,dotm,dotx,dxf,emf,eps,epub,fodg,fodp,fods,fodt,fopd,gif,htm,html,hwp,jpeg,jpg,key,ltx,lwp,mcw,met,mml,mw,numbers,odd,odg,odm,odp,ods,odt,otg,oth,otp,ots,ott,pages,pbm,pcd,pct,pcx,pdb,pdf,pgm,png,pot,potm,potx,ppm,pps,ppt,pptm,pptx,psd,psw,pub,pwp,pxl,ras,rtf,sda,sdc,sdd,sdp,sdw,sgl,slk,smf,stc,std,sti,stw,svg,svm,swf,sxc,sxd,sxg,sxi,sxm,sxw,tga,tif,tiff,txt,uof,uop,uos,uot,vdx,vor,vsd,vsdm,vsdx,wb2,wk1,wks,wmf,wpd,wpg,wps,xbm,xhtml,xls,xlsb,xlsm,xlsx,xlt,xltm,xltx,xlw,xml,xpm,zabw - Merge Builder
- Convert Builder
- PDF customization (available for every builder except LibreOffice and Merge)
Screenshot
Profiler
Comes with a built-in profiler panel to help you during your development.
Credits
This bundle was inspired by Gotenberg PHP.
Licence
MIT License (MIT): see the License File for more details.
FAQ
My PDF / Screenshot is blank but I have no errors !
It may be because Gotenberg is trying to access an invalid URL (when using the `->url()` or `->route()` modes). For example if Gotenberg tries to access a page on `https://localhost:8001` but the SSL is a local provided one. Then Chromium won't be able to authorize access to the website. To fix this you can update your Gotenberg docker service as followed :--- a/compose.yaml +++ b/compose.yaml @@ -1,6 +1,9 @@ services: gotenberg: image: 'gotenberg/gotenberg:8' + command: + - 'gotenberg' + - '--chromium-ignore-certificate-errors'
It can also be because from Gotenberg PoV the URL of your Symfony app is not reachable. Let's say you are using symfony CLI to run your project locally with Gotenberg running in Docker. You need to configure the request_context like so :
--- a/config/packages/gotenberg.yaml +++ b/config/packages/gotenberg.yaml @@ -6,5 +6,5 @@ framework: sensiolabs_gotenberg: http_client: 'gotenberg.client' + request_context: + base_uri: 'http://host.docker.internal:8000' # 8000 is the port Symfony CLI is running my app on.