PDFShift
Last updated 07 October 2019
The PDFShift add-on is currently in beta.
Table of Contents
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!