How to convert HTML to an image using wkhtmltoimage and Laravel

Converting HTML to images lets developers generate screenshots, thumbnails, and visual previews of webpages. wkhtmltoimage(opens in a new tab) is a command-line tool that uses the WebKit rendering engine. It’s lightweight, fast, and runs headless (no GUI required). It’s available for macOS, Linux, and Windows.

In this tutorial, you’ll learn how to use wkhtmltoimage with Laravel to convert HTML to an image.

Development considerations

Nutrient’s HTML-to-image API provides hosted conversion without installing wkhtmltoimage on the application server. The Processor API free plan includes 50 credits per month and adds an evaluation watermark to output. Credit usage depends on the operations in the request. See Processor API pricing for paid plans and pay-as-you-go options that remove the watermark.

Requirements

• PHP — Install a version supported by the chosen Laravel release. Downloads are available from the PHP website(opens in a new tab).

To check if you have PHP installed on your system, you can open a terminal and run the command php -v.

• Composer — Install the PHP dependency manager using the Composer installation guide(opens in a new tab).
• Laravel — Check the Laravel installation requirements(opens in a new tab) for the chosen release. Compatibility with the unmaintained demo repository needs separate verification.

Running laravel -v checks whether the Laravel installer is available; it doesn’t identify a project’s Laravel framework version. If the installer is missing, install it with Composer:

composer global require laravel/installer

Add Composer’s global binary directory to PATH so the shell can find the Laravel installer. Use the Composer global command documentation(opens in a new tab) to locate that directory. The following example assumes a Unix-like shell and a global binary directory at $HOME/.composer/vendor/bin; substitute the actual path if it differs:

export PATH="$HOME/.composer/vendor/bin:$PATH"

Setting up the project

Create a new Laravel project by running the following:

laravel new html-to-image

This will create a new directory called html-to-image with the basic Laravel structure.

Navigate to the project directory by running the following command:

cd html-to-image

Installing wkhtmltoimage

Install wkhtmltoimage on your system. You can download the appropriate version for your operating system from the official website(opens in a new tab).

Check if wkhtmltoimage is installed by running the following command:

wkhtmltoimage -V

It’ll display the version number of the library like this:

wkhtmltoimage 0.12.6 (with patched qt)

Make sure you have wkhtmltoimage installed on your system and that the binary is in the system’s PATH. You can check this by running the following command:

which wkhtmltoimage

If it’s not in the PATH, you can add the location to the PATH variable.

Integrating wkhtmltoimage with Laravel

1. Once you have wkhtmltoimage installed, you can integrate it with Laravel by creating a new command that utilizes the library. To do this, use the following command to generate a new command class:

   php artisan make:command ConvertHtmlToImage

   This will create a new file in the app/Console/Commands directory.

2. Open the app/Console/Commands/ConvertHtmlToImage.php file and update the handle method to use the wkhtmltoimage library to convert HTML to an image:

   public function handle(): int
   {
       $html = $this->argument('html');
       $output = $this->argument('output');
   
       // Escape shell arguments to prevent command injection.
       $escapedHtml = escapeshellarg($html);
       $escapedOutput = escapeshellarg($output);
   
       $outputLines = [];
       $resultCode = null;
   
       exec("wkhtmltoimage --format png {$escapedHtml} {$escapedOutput} 2>&1", $outputLines, $resultCode);
   
       if ($resultCode !== 0) {
           $this->error("Failed to convert HTML to image");
           if (!empty($outputLines)) {
               $this->error(implode("\n", $outputLines));
           }
           return Command::FAILURE;
       }
   
       $this->info("HTML converted to image and saved to {$output}");
       return Command::SUCCESS;
   }

   This method takes the html and output arguments and passes them to the wkhtmltoimage command. The --format option specifies the output format (PNG in this case).

   The escapeshellarg() function sanitizes the input arguments to prevent command injection attacks. The exec() function executes the wkhtmltoimage command, capturing both output and the result code for error handling.

3. In the signature property of the class, define the arguments and options that this command accepts:

   protected $signature = 'convert:html-to-image {html=public/index.html} {output=public/image.png}';

   The html argument is the path to the HTML file that will be converted to an image, and the output argument is the path to the output image file. The = syntax sets default values for these arguments.

4. Here’s the full code for the command:

   <?php
   
   namespace App\Console\Commands;
   
   use Illuminate\Console\Command;
   
   class ConvertHtmlToImage extends Command
   {
       /**
        * The name and signature of the console command.
        *
        * @var string
        */
       protected $signature = 'convert:html-to-image {html=public/index.html} {output=public/image.png}';
   
       /**
        * The console command description.
        *
        * @var string
        */
       protected $description = 'Convert HTML to image using wkhtmltoimage';
   
       /**
        * Execute the console command.
        *
        * @return int
        */
       public function handle(): int
       {
           $html = $this->argument('html');
           $output = $this->argument('output');
   
           // Escape shell arguments to prevent command injection.
           $escapedHtml = escapeshellarg($html);
           $escapedOutput = escapeshellarg($output);
   
           $outputLines = [];
           $resultCode = null;
   
           exec("wkhtmltoimage --format png {$escapedHtml} {$escapedOutput} 2>&1", $outputLines, $resultCode);
   
           if ($resultCode !== 0) {
               $this->error("Failed to convert HTML to image");
               if (!empty($outputLines)) {
                   $this->error(implode("\n", $outputLines));
               }
               return Command::FAILURE;
           }
   
           $this->info("HTML converted to image and saved to {$output}");
           return Command::SUCCESS;
       }
   }

Creating the HTML file

Currently, there isn’t an HTML file inside the public directory. So, create a file called index.html and paste the following code into it:

193 collapsed lines
1
<!DOCTYPE html>
2
<html>
3
  <head>
4
    <meta charset="utf-8" />
5
    <title>
6
      A simple, clean, and responsive HTML invoice template
7
    </title>
8

9
    <style>
10
      .invoice-box {
11
        max-width: 800px;
12
        margin: auto;
13
        padding: 30px;
14
        border: 1px solid #eee;
15
        box-shadow: 0 0 10px rgba(0, 0, 0, 0.15);
16
        font-size: 16px;
17
        line-height: 24px;
18
        font-family: 'Helvetica Neue', 'Helvetica', Helvetica,
19
          Arial, sans-serif;
20
        color: #555;
21
      }
22

23
      .invoice-box table {
24
        width: 100%;
25
        line-height: inherit;
26
        text-align: left;
27
      }
28

29
      .invoice-box table td {
30
        padding: 5px;
31
        vertical-align: top;
32
      }
33

34
      .invoice-box table tr td:nth-child(2) {
35
        text-align: right;
36
      }
37

38
      .invoice-box table tr.top table td {
39
        padding-bottom: 20px;
40
      }
41

42
      .invoice-box table tr.top table td.title {
43
        font-size: 45px;
44
        line-height: 45px;
45
        color: #333;
46
      }
47

48
      .invoice-box table tr.information table td {
49
        padding-bottom: 40px;
50
      }
51

52
      .invoice-box table tr.heading td {
53
        background: #eee;
54
        border-bottom: 1px solid #ddd;
55
        font-weight: bold;
56
      }
57

58
      .invoice-box table tr.details td {
59
        padding-bottom: 20px;
60
      }
61

62
      .invoice-box table tr.item td {
63
        border-bottom: 1px solid #eee;
64
      }
65

66
      .invoice-box table tr.item.last td {
67
        border-bottom: none;
68
      }
69

70
      .invoice-box table tr.total td:nth-child(2) {
71
        border-top: 2px solid #eee;
72
        font-weight: bold;
73
      }
74

75
      @media only screen and (max-width: 600px) {
76
        .invoice-box table tr.top table td {
77
          width: 100%;
78
          display: block;
79
          text-align: center;
80
        }
81

82
        .invoice-box table tr.information table td {
83
          width: 100%;
84
          display: block;
85
          text-align: center;
86
        }
87
      }
88

89
      /** RTL **/
90
      .invoice-box.rtl {
91
        direction: rtl;
92
        font-family: Tahoma, 'Helvetica Neue', 'Helvetica',
93
          Helvetica, Arial, sans-serif;
94
      }
95

96
      .invoice-box.rtl table {
97
        text-align: right;
98
      }
99

100
      .invoice-box.rtl table tr td:nth-child(2) {
101
        text-align: left;
102
      }
103
    </style>
104
  </head>
105

106
  <body>
107
    <div class="invoice-box">
108
      <table cellpadding="0" cellspacing="0">
109
        <tr class="top">
110
          <td colspan="2">
111
            <table>
112
              <tr>
113
                <td>
114
                  Invoice #: 123
115

116
                  Created: January 23, 2023
117

118
                  Due: January 31, 2023
119
                </td>
120
              </tr>
121
            </table>
122
          </td>
123
        </tr>
124

125
        <tr class="information">
126
          <td colspan="2">
127
            <table>
128
              <tr>
129
                <td>
130
                  Acme, Inc.
131

132
                  12345 Sunny Road
133

134
                  Sunnyville, TX 12345
135
                </td>
136

137
                <td>
138
                  Acme Corp.
139

140
                  John Doe
141

142
                  john@example.com
143
                </td>
144
              </tr>
145
            </table>
146
          </td>
147
        </tr>
148

149
        <tr class="heading">
150
          <td>Payment Method</td>
151

152
          <td>Check #</td>
153
        </tr>
154

155
        <tr class="details">
156
          <td>Check</td>
157

158
          <td>1000</td>
159
        </tr>
160

161
        <tr class="heading">
162
          <td>Item</td>
163

164
          <td>Price</td>
165
        </tr>
166

167
        <tr class="item">
168
          <td>Website design</td>
169

170
          <td>$300.00</td>
171
        </tr>
172

173
        <tr class="item">
174
          <td>Hosting (3 months)</td>
175

176
          <td>$75.00</td>
177
        </tr>
178

179
        <tr class="item last">
180
          <td>Domain name (1 year)</td>
181

182
          <td>$10.00</td>
183
        </tr>
184

185
        <tr class="total">
186
          <td></td>
187

188
          <td>Total: $385.00</td>
189
        </tr>
190
      </table>
191
    </div>
192
  </body>
193
</html>

Converting HTML to PNG

Navigate to the project directory and run the following command:

php artisan convert:html-to-image public/index.html public/image.png

This runs the ConvertHtmlToImage command, which is defined in the app/Console/Commands/ConvertHtmlToImage.php file.

It takes two arguments:

• The first argument is the path to the input HTML file (public/index.html).
• The second argument is the path to the output image file (public/image.png).

This command will convert the HTML file to an image and save it to the public/image.png file.

Conclusion

This tutorial covered setting up a Laravel project and integrating wkhtmltoimage to convert HTML to images. The combination works well for generating visual snapshots of webpages within PHP applications.

An alternative approach is Spatie/Browsershot(opens in a new tab), which uses headless Chrome to convert HTML to an image. This requires Chrome and Puppeteer installed on your system.

For hosted conversion, use Nutrient’s HTML-to-image API. Create a Processor API account(opens in a new tab) to test conversion with the free plan, and check the pricing page before production use.

FAQ