PDFShift

This add-on is operated by S.A.S.U. PDFShift

HTML to PDF conversion made simple.

PDFShift

Last updated 07 October 2019

The PDFShift add-on is currently in beta.

The PDFShift add-on converts your app’s HTML documents to PDF using PDFShift’s powerful API.

PDFShift provides client libraries in Python, Node.js and PHP to get started quickly. You can also send HTTPS requests from the language of your choice.

Provisioning the add-on

PDFShift can be attached to any Heroku application via the add-on page or via the CLI:

A list of all plans available can be found here or by running heroku addons:plans pdfshift

$ heroku addons:create pdfshift
Creating pdfshift on ⬢ blooming-water-4431... free
Created pdfshift-example-12345 as PDFSHIFT_API_KEY, PDFSHIFT_URL
Use heroku addons:docs pdfshift to view documentation

Once PDFShift has been added, two config vars will be set for your app:

  • PDFSHIFT_API_KEY contains your specific API key granting access to the newly provisioned PDFShift instance.
  • PDFSHIFT_URL contains the root URL for the PDFShift instance’s API.

This can be confirmed using the heroku config:get command.

Local environment

Your local (development) server doesn’t have the keys configured, so you need to export them.

Heroku Local reads configuration variables from a .env file. You can preview all of your app’s config vars by typing heroku config.

To add PDFShift’s config variables to your local environment, simply run the following command:

$ heroku config:get PDFSHIFT_API_KEY -s  >> .env
$ heroku config:get PDFSHIFT_URL -s  >> .env

This will add both PDFSHIFT_API_KEY and PDFSHIFT_URL to your .env file.

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

(For more information, see the Heroku Local article.)

API Options

PDFShift provides a variety of options to help you generate the best PDF for your needs.

The main arguments to pass to the API are:

Parameter name Required? Type Example Description
source yes string https://pdfshift.io/documentation The HTML source to convert. This can either be an URL to load or some raw HTML
sandbox no boolean false If true, a watermark is applied to the PDF output, but you won’t lose any credits for your conversions. Useful when developing!

Many parameters are available, including watermarking and encryption.

See the PDFShift documentation for a complete and up-to-date API reference.

Dashboard

Your PDFShift dashboard let you see your API usage along with the successful and failed document requests.

The dashboard is available by visiting the Heroku Dashboard and selecting the application in question, then selecting PDFShift from the Add-ons menu.

Alternatively, you can open the dashboard via the CLI:

$ heroku addons:open pdfshift
Opening https://addons-sso.heroku.com/apps/your_app_id/addons/your_addon_id...

Using Node.js

Start by installing the npm package:

$ npm install pdfshift

The following sample demonstrates reading in an HTML file and submitting it to PDFShift for conversion:

const pdfshift = require('pdfshift')(process.env.PDFSHIFT_API_KEY);
const fs = require('fs');

let data = fs.readFileSync('invoice.html', 'utf8');

pdfshift.convert(data).then(function (binary_file) {
    fs.writeFile('invoice.pdf', binary_file, "binary", function () {})
}).catch(function({message, code, response, errors = null}) {})

You can visit the NPM.js package page for more details and more code samples.

Using Python

Start by installing the package using pip:

$ pip install pdfshift

The following sample demonstrates reading in an HTML file and submitting it to PDFShift for conversion:

pdfshift.api_key = os.environ.get('PDFSHIFT_API_KEY')

document = open('invoice.html', 'r')
document_content = document.read()
document.close()

binary_file = pdfshift.convert(document_content)
with open('invoice.pdf', 'wb') as output:
    output.write(binary_file)

Visit the Pypi package page for more details.

Using PHP

You can use Packagist to install the package:

$ composer require pdfshift/pdfshift-php

or you can download it directly from our Github repository.

The following sample demonstrates reading in an HTML file and submitting it to PDFShift for conversion:

require_once('vendor/autoload.php');
use \PDFShift\PDFShift;
PDFShift::setApiKey(getenv('PDFSHIFT_API_KEY'));

$data = file_get_content('invoice.html');
PDFShift::convertTo($data, null, 'result.pdf');

Migrating between plans

No downtime or disruption of service will occur as you modify your plans.

Use the heroku addons:upgrade command to upgrade to a new plan.

$ heroku addons:upgrade pdfshift:growth
-----> Upgrading pdfshift:growth to blooming-water-4431... done, v13 ($39/mo)
       Your plan has been updated to: pdfshift:growth

You can also downgrade your account if your usage requires it.

Use the heroku addons:downgrade command to downgrade to a new plan.

$ heroku addons:downgrade pdfshift:starter
-----> Upgrading pdfshift:starter to blooming-water-4431... done, v13 ($9/mo)
       Your plan has been updated to: pdfshift:starter

Canceling PDFShift

You can cancel your PDFShift plan by destroying the Heroku provisioning.

Keep in mind that this action will destroy all your associated data, cannot be undone and will render your connection to the API unavailable.

$ heroku addons:destroy pdfshift
 ▸    WARNING: Destructive Action
 ▸    This command will affect the app blooming-water-4431
 ▸    To proceed, type blooming-water-4431 or re-run this command with --confirm blooming-water-4431

> blooming-water-4431
Destroying pdfshift-example-12345 on ⬢ blooming-water-4431... done

Support

Billing, Heroku account issues, and runtime issues should be submitted via one of the Heroku Support channels.

For all other requests, including feedback or just wanting to say hi, feel free to contact us at support@pdfshift.io.

We are happy to help you with creating awesome PDF documents!

Feedback

Log in to submit feedback.