Pdfcrowd Blog

Changes:

• Added the setDisableSmartShrinking method.

Overview

The Pdfcrowd API v2 is the new generation of our API. It is not 100% backward compatible but the changes are mostly syntactic and the migration from API v1 should be straightforward.

If you want to switch your current API v1 plan to API v2, please follow these steps:

1. Activate the free API v2 trial in your account page.
2. Follow the instructions below and migrate your API v1 implementation to API v2.
3. If the API v2 works to your satisfaction, choose from our API v2 plans.
4. If you no longer need the API v1 implementation, you can cancel the API v1 plan.

API v2 Links

API client libraries

If you use our API client library, install the latest version from the API home page. The library supports both API versions and you can easily run both implementations side by side under your current Pdfcrowd account.

The migration should consist of these steps:

1. Instantiate the API v2 client.
2. Migrate the convert*** method (the one that returns PDF).
3. Migrate the conversion settings.
4. Error handling (important)

API client instantiation

The code below shows how to instantiate API clients. The first line corresponds to what you have in your current API v1 implementation (client_v1). The second line shows how to instantiate the API v2 client (client_v2).

// PHP
client_v1 = new Pdfcrowd("username", "apikey")
client_v2 = new \Pdfcrowd\HtmlToPdfClient("username", "apikey")

// Java
Client client_v1 = new Client("username", "apikey");
Pdfcrowd.HtmlToPdfClient client_v2 = new Pdfcrowd.HtmlToPdfClient("username", "apikey");

// .NET
pdfcrowd.Client client_v1 = new pdfcrowd.Client("username", "apikey");
pdfcrowd.HtmlToPdfClient client_v2 = new pdfcrowd.HtmlToPdfClient("username", "apikey");

# Ruby
client_v1 = Pdfcrowd::Client.new("username", "apikey");
client_v2 = Pdfcrowd::HtmlToPdfClient.new("username", "apikey");

# Python
client_v1 = pdfcrowd.Client("username", "apikey")
client_v2 = pdfcrowd.HtmlToPdfClient("username", "apikey")

// Node.js
var client_v1 = new pdf.Pdfcrowd("username", "apikey")
var client_v2 = new pdfcrowd.HtmlToPdfClient("username", "apikey")

Conversion methods

The following table shows the mapping of conversion methods.

Conversion settings methods

If your API implementation is in Node.js, continue below.

If your API v1 implementation customizes the conversion settings, check the following table to find the corresponding API v2 functionality.

Node.js

API client instantiation:

// Node.js
var client_v1 = new pdf.Pdfcrowd("username", "apikey")
var client_v2 = new pdfcrowd.HtmlToPdfClient("username", "apikey")

The API v1 client uses a dictionary of options. API v2 uses methods on the client object.

// API v1
client_v1.convertURI(
    'http://example.com',
    pdf.saveToFile("example.pdf"), {
        width: "11in",
        height: "8.5in",
        user_print_media: true,
    }
);

// API v2
client_v2.setPageSize("Letter");
client_v2.setUsePrintMedia(true);

client_v2.convertUrlToFile(
    "http://example.com",
    "example.pdf",
    function(err, fileName) {
        if (err) return console.error("Pdfcrowd Error: " + err);
        // success, pdf was saved to fileName
    });

See the HTML to PDF API v2 - Node.js documentation for more examples.

The following table maps API v1 options to API v2 methods. The mapping of the convert*** methods is here.

HTTP access

The API v2 endpoint is https://api.pdfcrowd.com/convert/
The authentication method for user credentials is HTTP Basic Access Authentication.

Convert URL

# API v1
curl -F "username=username" -F "key=apikey" \
     -F 'src=http://example.com' \
     -o example.pdf \
     https://pdfcrowd.com/api/pdf/convert/uri/

# API v2
curl -f -u "username:apikey" \
     -F "url=http://www.example.com" \
     -o example.pdf \
     https://api.pdfcrowd.com/convert/

Convert file

# API v1
curl -F "username=username" -F "key=apikey" \
     -F 'src=@example.html' \
     -o example.pdf \
      https://pdfcrowd.com/api/pdf/convert/html/

# API v2
curl -f -u "username:apikey" \
     -F "file=@example.html" \
     -o example.pdf \
     https://api.pdfcrowd.com/convert/

Convert string

# API v1
curl -F "username=username" -F "key=apikey" \
     -F "src=<html><body><h1>Hello World!</h1></body></html>" \
     -o hello.pdf \
     https://pdfcrowd.com/api/pdf/convert/html/

# API v2
curl -f -u "username:apikey" \
     -F "text=<html><body><h1>Hello World!</h1></body></html>" \
     -o hello.pdf \
     https://api.pdfcrowd.com/convert/

The following table maps API v1 options to API v2 options.

Miscellaneous

Header and footer

Variables
Replace variables with HTML classes:
%u ⇒ pdfcrowd-source-url
%p ⇒ pdfcrowd-page-number
%n ⇒ pdfcrowd-page-count

<!-- API v1 -->
Page %p of %n.

<!-- API v2 -->
Page <span class='pdfcrowd-page-number'></span> of <span class='pdfcrowd-page-count'></span>.

Placement
API v1 places headers and footers to the margin area. API v2 places them to the printing area. The height of the header and footer can be set with setHeaderHeight and setFooterHeight.

Units

API v1 allows to specify a unit-less numeric value that is interpreted as points (1/72 of an inch). API v2 doesn't allow this, the value must be specified with a mm, in, cm or pt suffix.

Addendum

Changes:

• Fixed an issue in Python and NodeJs libraries.
• All API requests are now encoded as multipart/form-data.

After 8 months in Beta, the new Pdfcrowd API is ready for your production workloads. Thanks to everyone who provided feedback!

The API v2 brings a lot of improvements and solves many issues present in the API v1. It introduces minor backward incompatible changes but the migration from the API v1 should be straightforward.

The API v1 will continue to work for accounts that were opened before introducing the API v2. However, it will no longer receive any updates.

What's new in the API v2?

• Faithful conversions. The API implements the latest HTML5, CSS3 and JavaScript specifications.
• No downtime. The API is highly available with automatic capacity scaling and failover. It is hosted in the Google Cloud Platform.
• In addition to HTML to PDF, the new API enables these conversions:
  • HTML to Image
  • PDF to PDF
  • Image to PDF
  • Image to Image
• New features:
  • Linearized PDFs for fast web view.
  • Post-load DOM manipulation via custom JavaScript (remove, add and modify elements).
  • An option to specify a delay to wait before printing if the page loads dynamic content.
  • An option to send session specific information via cookies.
  • An option to print only a part of the HTML document.
  • Multi-page watermarks and backgrounds to allow to fill in scanned PDF forms.
  • Intuitive HTML zoom.
  • Detailed conversion logs that can help with conversion troubleshooting.
  • Exportable conversion statistics.
  • Concurrent conversions.
  • Support for modern JavaScript charting libraries (Google Charts, Highcharts, etc.)
  • Improved remote font support (Google Fonts, Typekit, etc.)
  • CJK languages and complex scripts (Arabic alphabet, Brahmic scripts).

In this tutorial you will learn how to easily convert web pages and raw HTML documents to PDF in your PHP applications. We will use the Pdfcrowd API for PDF generation. The API offers these benefits:

• The API is easy to use and fully supports HTML/CSS3/JavaScript.
• The integration takes only a few minutes.
• No third-party libraries are needed, just a single tiny PHP file.
• It does not consume CPU/memory on your computer, PDFs are created on the Pdfcrowd servers.

Introduction

Let's start with an example:

<?php
require 'pdfcrowd.php';

$client = new \Pdfcrowd\HtmlToPdfClient("username", "apikey");
$pdf = $client->convertUrl('https://en.wikipedia.org/');
?>

This code converts en.wikipedia.org and stores the generated PDF to a string variable. You can save the result to a file or you can stream it to the browser, which we will discuss in detail shortly. You can click the thumbnail to open the generated PDF file:

Besides web pages, you can also convert a local HTML file or an HTML string:

<?php
$pdf = $client->convertFile('/path/to/your/file.html');
$pdf = $client->convertString('<b>bold</b> and <i>italic</i>');
?>

It is also possible to save the PDF directly to a file:

<?php
$client->convertUrlToFile('http://example.com/', 'example.pdf');
?>

Basic Customization

Now that you know the basics, you may want to customize the generated PDF. Let's change the page format to Letter with half-inch margins:

<?php
$client->setPageSize("Letter");
$client->setPageMargins("0.5in", "0.5in", "0.5in", "0.5in");
?>

You can use metric units as well:

<?php
$client->setPageMargins("1cm", "1cm", "10mm", "10mm");    
?>

You can also specify the appearance of the PDF when it is opened in a viewer:

<?php
$client->setInitialPdfZoomType(Pdfcrowd::FIT_PAGE);
$client->setPageLayout(Pdfcrowd::CONTINUOUS);
?>

The API provides many other options including password protection and fully customizable page headers and footers. Learn more about the available options in the HTML to PDF API - PHP SDK documentation.

Server Side PDF Generation

In this section we will show two common PDF generation scenarios.

Generate PDF and send it to the browser

The following code converts example.com to PDF and sends it as a response:

<?php

require 'pdfcrowd.php';

try {
    $client = new \Pdfcrowd\HtmlToPdfClient("username", "apikey");
    $pdf = $client->convertUrl("https://example.com.com/");

    header("Content-Type: application/pdf");
    header("Cache-Control: no-cache");
    header("Accept-Ranges: none");
    header("Content-Disposition: inline; filename=\"example.pdf\"");

    echo $pdf;
}
catch(\Pdfcrowd\Error $why) {
    fwrite(STDERR, "Pdfcrowd Error: {$why}\n");
}

?>

To convert an HTML string you can use convertString() instead of convertUrl():

<?php
$pdf = $client->convertString("<html><head>..</head><body>..</body></html>");
?>

Since Content-Disposition is set to inline the generated PDF is opened in the browser. If you change it to attachment the browser will pop up the file download dialog:

<?php
header("Content-Disposition: attachment; filename=\"mydomain.pdf\"");
?>

Provide a PDF version of your web pages

This example shows how to enhance your PHP code so it can return a PDF version of your web pages. Let's look at the following helper function:

<?php
require 'pdfcrowd.php';

function generatePDF()
{
    if (!$_GET["pdf"])
        return False;

    try {
        // build the url and remove the pdf field from the query string
        $url = "http://" . $_SERVER["SERVER_NAME"] . $_SERVER["PHP_SELF"];
        if (count($_GET) > 1) {
            unset($_GET["pdf"]);
            $url = $url . "?" . http_build_query($_GET, '', '&');
        }

        // call the API
        $client = new \Pdfcrowd\HtmlToPdfClient("username", "apikey");
        $pdf = $client->convertUrl($url);

        // send the generated pdf to the browser
        header("Content-Type: application/pdf");
        header("Cache-Control: no-cache");
        header("Accept-Ranges: none");
        header("Content-Disposition: attachment; filename=\"created.pdf\"");

        echo $pdf;
    }
    catch(\Pdfcrowd\Error $why) {
        fwrite(STDERR, "Pdfcrowd Error: {$why}\n");
    }

    return True;
}
?>

The generatePDF() function first checks if there is a pdf field in the query string. If yes, then the field is removed from the url. The function then passes the modified url to the API and finally sends the generated PDF to the browser.

You can use the function in your code like this:

<?php
if (generatePDF())
    return;

// your HTML rendering code
// ...
?>

https://mydomain.com/page.php?pdf=1 now returns a PDF version of https://mydomain.com/page.php.