Styling PDFs with CSS

Keep on Learning!

If you liked what you've learned so far, dive in!
Subscribe to get access to this tutorial plus
video, code and script downloads.

Start your All-Access Pass
Buy just this tutorial for $12.00

With a Subscription, click any sentence in the script to jump to that part of the video!

Login Subscribe

Our PDF attachment looks terrible. I don't know why, but the CSS is definitely not working.

Debugging this can be tricky because, even though this was originally generated from an HTML page, we can't exactly "Inspect Element" on a PDF to see what went wrong.

So... let's... think about what's happening. The encore_entry_link_tags() function creates one or more link tags to CSS files, which live in the public/build/ directory. But the paths it generates are relative - like href="/build/app.css".

We also know that the getOutputFromHtml() method works by taking the HTML, saving it to a temporary file and then effectively loading that file in a browser... and creating a PDF from what it looks like. If you load a random HTML file on your computer into a browser... and that HTML file has a CSS link tag to /build/app.css, what would happen? Well, it would look for that file on the filesystem - like literally a /build/ directory at the root of your drive.

That is what's happening behind the scenes. So, the CSS never loads... and the PDF looks like it was designed... well... by me. We can do better.

Making Absolute CSS Paths

Once you understand what's going on, the fix is pretty simple. Replace {{ encore_entry_link_tags() }} with {% for path in encore_entry_css_files('app') %}.

... lines 1 - 2
... lines 4 - 9
{% for path in encore_entry_css_files('app') %}
... line 11
{% endfor %}
... lines 14 - 26

Instead of printing all the link tags for all the CSS files we need, this allows us to loop over them. Inside, add <link rel="stylesheet" href=""> and then make the path absolute with absolute_url(path).

... lines 1 - 2
... lines 4 - 9
{% for path in encore_entry_css_files('app') %}
<link rel="stylesheet" href="{{ absolute_url(path) }}">
{% endfor %}
... lines 14 - 26

We saw this earlier: we used it to make sure the path to our logo - before we embedded it - contained the hostname. Now when wkhtmltopdf, more or less, opens the temporary HTML file in a browser, it will download the CSS from our public site and all should be happy with the world.

Let's try it! Run the console command:

php bin/console app:author-weekly-report:send

Move back over and... I'll refresh Mailtrap... great! 2 new emails. Check the attachment on the first one. It looks perfect! I mean, hopefully you're better at styling than I am... and can make this look even better, maybe with a hot-pink background and unicorn Emojis? I'm still working on my vision. The point is: the CSS is being loaded.

Let's check the other email to be sure. What? This one looks terrible! The first PDF is good... and the second one... which was generated the exact same way... has no styling!? What madness is this!?

Encore: Missing CSS after First PDF?

This is a little gotcha that's specific to Encore. For reasons that are... not that interesting right now - you can ask me in the comments - when you call an Encore Twig function the first time, it returns all the CSS files that you need for the app entrypoint. But when we go through the loop the second time, render a second template and call encore_entry_css_files() for a second time, Encore returns an empty array. Basically, you can only call an Encore function for an entrypoint once per request... or once per console command execution. Every time after, the method will return nothing.

There's a good reason for this... but it's totally messing us up! No worries, once you know what's going on, the fix is pretty simple. Find the constructor and add one more argument - I know, it's getting a bit crowded. It's EntrypointLookupInterface $entrypointLookup. I'll do my normal Alt + Enter and select "Initialize fields" to create that property and set it.

... lines 1 - 16
use Symfony\WebpackEncoreBundle\Asset\EntrypointLookupInterface;
... lines 18 - 19
class AuthorWeeklyReportSendCommand extends Command
... lines 22 - 28
private $entrypointLookup;
public function __construct(UserRepository $userRepository, ArticleRepository $articleRepository, MailerInterface $mailer, Environment $twig, Pdf $pdf, EntrypointLookupInterface $entrypointLookup)
... lines 33 - 39
$this->entrypointLookup = $entrypointLookup;
... lines 42 - 88

Down below, right before we render... or right after... it won't matter, say $this->entrypointLookup->reset(). This tells Encore to forget that it rendered anything and forces it to return the same array of CSS files on each call.

... lines 1 - 19
class AuthorWeeklyReportSendCommand extends Command
... lines 22 - 49
protected function execute(InputInterface $input, OutputInterface $output)
... lines 52 - 56
foreach ($authors as $author) {
... lines 58 - 62
if (count($articles) === 0) {
... lines 68 - 83
... lines 85 - 87

This should make our PDF wonderful. Run the command one more time:

php bin/console app:author-weekly-report:send

Fly over to Mailtrap and... I'll refresh. Ok, two emails - let's check the second: that's the one what was broken before. The attachment... looks perfect.

Next, I like to keep my email logic close together and organized - it helps me to keep emails consistent and, honestly, remember what emails we're sending. Let's refactor the emails into a service... and eventually, use that to write a unit test.

Leave a comment!

  • 2020-03-30 weaverryan

    Hey @zakaria!

    When wkhtmltopdf works, it's great! When it doesn't, it's super hard to debug :/. I have not seen this "anointed exception" before. To see if it's working at all, I would try to render VERY simple HTML as a PDF - like maybe literally just an <h1> with NO CSS at all. If that works, then you can re-add more HTML little-by-little and CSS. If it does *not* work, then there may be a bigger setup issue.


  • 2020-03-30 zakaria

    For my part it does not work with app.css (bootstrap), I have an error.
    he exit status code '136' says something went wrong:
    stderr: "Loading pages (1/6)
    [=======>] 10 %%
    Floating p ==================>] 48%
    anointed exception (core dumped)
    I tried with a simple css it works. but not the app.css

  • 2020-03-11 weaverryan

    Hey Gompali!

    > I think I will implement a client for a python or go library to end it up in a reasonable time frame.

    That's not a bad idea. We use it on production, but we *have* had to fight with it, and I'm excited for there to be a different/better tool someday :). Another user discussed some alternatives in this comment:

    Good luck and cheers!

  • 2020-03-10 Gompali

    You're right, make this lib working is a "bummer". I pass it http, https, server local path, it - at best - ignores the .css files and images. I had it "once" right but never with correct headers and footers. I think the correct installation of the binary should be more detailed.

    And at the end of the day, it's still buggy and no insurance it will keep do the job. I think I will implement a client for a python or go library to end it up in a reasonable time frame.

  • 2020-03-09 Gompali

    Thks anyway.

  • 2020-03-09 weaverryan

    Hey Gompali!

    This is when working with wkhtmltopdf is a pain! It's an old tool, and not super friendly when it's not working. From my experience - and from the errors you have - it certainly looks like wkhtmltopdf is having a problem downloading *something* on the page - very likely CSS or JavaScript - but it could be something else. I would try 2 things:

    1) Try using http everywhere - run your server in http and make sure your links use http. Let's rule out https being a problem
    2) Try removing things from your page to see if you can get a successful PDF build. Like, remove the CSS and JS entirely from the page. Does it work now? If not, remove more and more. See if you can identify exactly which part of the page is causing the problem.

    Let me know what you find out!


  • 2020-03-06 Gompali

    I followed this workaround and it's printing correctly absolute paths. I had an issue with "http" scheme being printed instead of "https" because i work behing a reverse-proxy. Setting the TrustedProxies=ip-of-proxy does fix the pb, even if being in docker environment make uncertain about the ip to use. (I know you may try to assign fixed ip but there's other pbs there).

    Well this is doing a good job :

    {% for path in encore_entry_css_files('attestation_de_domiciliation') %}
    <link rel="stylesheet" href="{{ absolute_url(path) }}">
    {% endfor %}

    But now wkhtmltopdf still seem to struggle loading css :

    Do you have any idea to solve this ? (In browser the is rendered ok).

    The exit status code '1' says something went wrong:
    stderr: "The switch --no-outline, is not support using unpatched qt, and will be ignored.QStandardPaths: XDG_RUNTIME_DIR not set, defaulting to '/tmp/runtime-dockeruser'
    Loading page (1/2)
    [> ] 0%
    [======> ] 10%
    [==============================> ] 50%
    Error: Failed to load, with network status code 2 and http status code 0 - Connection closed
    Warning: Failed to load (ignore)
    [============================================================] 100%
    Printing pages (2/2)
    [> ]
    Exit with code 1 due to network error: RemoteHostClosedError
    stdout: ""
    command: /usr/bin/wkhtmltopdf --lowquality --margin-bottom '254mm' --margin-left '254mm' --margin-right '254mm' --margin-top '254mm' --page-size 'A4' --no-outline --encoding 'UTF-8' --disable-javascript '/var/www/html/var/cache/dev/snappy/knp_snappy5e623d7e3e46a1.31281460.html' './pdf/file_b23bc0.pdf'.

  • 2019-12-07 Amin Behravesh

    Thanks Ryan, actually I changed my OS, and everything is gone. :), I mean I am not using the previous config for my project anymore, and everything seems OK right now, if I can test in the previous environment I will inform you.

  • 2019-12-05 weaverryan

    And also see - I think we're debugging the same issue with another user... and I think I may know what the problem is now :)

  • 2019-12-05 weaverryan

    Hey Jérôme !

    Actually, it *is* supposed to look like that. You've proven that the link tags *are* being rendered (so, the reset is working as we expect) AND that the URL is absolute. I think that, for some reason, when wkhtmltopdf tries to open this "page" and make a request to that URL, it's failing. It could be due to how the Symfony local web server installs the binary. Try this to prove it:

    A) Start the web server with symfony serve --no-tls. This will start the server at http://localhost:8000 - not https.
    B) Update the SITE_BASE_SCHEME we set a few chapters ago - - to http to match this

    In theory, your site should work the same (except on http:// instead of https://) and the URLs to the link tags should also be http://. The key thing we're looking at is: does this fix things? If so, then we know the "https" part is the culprit. If it is, I have an idea of how to "get around it" in a reliable way.


  • 2019-12-04 Jérôme 

    After dumping `$html` : `<link rel="stylesheet" href="https://localhost:8000/build/app.css">`
    I guess it's not supposed to be like this... hmm...

  • 2019-12-04 weaverryan

    Hey Jérôme !

    Check my comment here - - we need to do some debugging to figure out the issue! Also, to help debugging, it might also be useful to dump($html) right after rendering the template and looking inside. Do you see any link tags? Or are there none? If there *are* link tags, what do the the URLs look like?


  • 2019-12-04 weaverryan

    Hey Amin Behravesh!

    That is *super* weird. I can't think of a reason why Docker would make a difference. When you call the reset() in your code, you are simply calling this method:

    As you can see, it reset a $returnedFiles property back to an empty array. This property is what tracks which files have already been rendered. This isn't using any caching or anything special - it's just a property that we're resetting. Here's what I might try to debug: right *before* you render the template (so right *after* calling reset()), try adding: dump($this->entrypointLookup) and look at the dumped $returnedFiles property. Is it empty? Or not? Put the *same* dump() line *after* the render call also. Is it empty there? Or not?

    I think something weird is going on - as there are two people with an issue... but I don't know what it is yet :).


  • 2019-12-04 Amin Behravesh

    I check it again in another machine(Mac Os, and everything is installed locally, not on a docker), and it works just fine.

  • 2019-12-04 Jérôme 

    Ok, it didn't fix anything... The attachment is here (OK) but the CSS isn't loaded.

  • 2019-12-04 Amin Behravesh

    No, it doesn't, I have EntrypointLookupInterface and reset line in my code, but it doesn't work.
    By the way my project is running in docker, I don't know if it is related to the problem or not?

  • 2019-12-04 Victor Bocharsky

    Hey Amin,

    Does this solution help you? :)


  • 2019-12-04 Amin Behravesh

    I have exactly the same issue, did you find any solution ?

  • 2019-12-03 Jérôme 

    I'm gonna try this ;) I'll tell you if it's okay then. Thanks!

  • 2019-12-02 Diego Aguiar

    Hey Jérôme 

    Vladimir is talking about this code block specifically like 67


  • 2019-12-02 Jérôme 

    What do you mean by "resetting entrypoints"?

  • 2019-12-02 Vladimir Sadicov

    Hey Jérôme 

    Interesting... Have you tried it with resetting entrypoints? or before it?


  • 2019-12-01 Jérôme 

    Hi, I followed each step of this chapter until replacing `{{ encore_entry_link_tags('app') }}` by the for loop. Then I tried sending the emails again, and downloaded the pdf, but the CSS isn't applied. I wonder what's going on here.