PDFShift

An Elixir client for the PDFShift API, which allows you to convert HTML to PDF.

Installation

The package can be installed by adding pdf_shift to your list of dependencies in mix.exs:

def deps do
  [
    {:pdf_shift, "~> 0.2.2"}
  ]
end

Configuration

You need a PDFShift API key to use this client. You can get one by signing up at PDFShift.

Set your API key using one of these methods:

Set the PDFSHIFT_API_KEY environment variable

Pass the API key in the options to each function

PDFShift.convert("https://example.com", %{}, api_key: "your_api_key")

Usage

Converting a URL to PDF

PDFShift.convert("https://example.com")

Converting HTML content to PDF

PDFShift.convert("<html><body>Hello World</body></html>")

Converting with options

PDFShift.convert("https://example.com", %{
  landscape: true,
  format: "A4",
  margin: %{
    top: "1cm",
    right: "1cm",
    bottom: "1cm",
    left: "1cm"
  },
  header: %{
    source: "<div style='text-align: center;'>Header</div>",
    height: "2cm"
  },
  footer: %{
    source: "<div style='text-align: center;'>Page {{page}} of {{total}}</div>",
    height: "2cm"
  }
})

Check credit usage

PDFShift.credits_usage()

Available options

The following options can be passed to the convert/3 function:

sandbox - Will generate documents that don't count towards your credits. The generated document will come with a watermark.
encode - Will return the generated PDF in Base64 encoded format, instead of raw.
filename - Name of the destination file. If given, the response will be a JSON with a URL to download the file.
webhook - An URL where PDFShift will send a POST request with the conversion result.
s3_destination - Path to your S3 bucket to save the converted PDF directly into your AWS S3 account.
timeout - Will kill the page loading at a specified time without stopping with a TimeoutError (in seconds).
wait_for - Name of a function available globally. PDFShift will wait for this function to return a truthy value.
landscape - Will set the view in landscape mode instead of portrait.
lazy_load_images - Will load images that are otherwise only loaded when they are visible.
css - Will append CSS styles to the document. Can be a URL or a String of CSS rules.
javascript - Will execute the given Javascript before saving. Can be a URL or a String of JS code.
disable_javascript - Will not execute any javascript in the document.
disable_backgrounds - The final document will not have background images.
remove_blank - Remove the last page if it is considered empty.
delay - In milliseconds. Will wait for this duration before capturing the document (max 10 seconds).
raise_for_status - Will stop the conversion if the status_code from the given source is not 2XX.
use_print - Use the print stylesheet instead of the general one.
format - Format of the document. Standard values (A4, Letter, etc.) or custom width x height.
pages - Pages to print. Can be one number, a range, a list or a combination.
zoom - A value between 0 and 2. Controls zoom level in the document.
is_gdpr - If true, ensures data protection compliance by refusing certain features.
is_hipaa - If true, ensures HIPAA compliance by refusing certain features.
margin - Object defining empty spaces around the content (top, right, bottom, left).
auth - Object containing username and password for accessing password-protected content.
cookies - List of cookies to send along with the requests when loading the source.
http_headers - List of HTTP headers to pass to the request.
header - Object defining a custom header with source and height properties.
footer - Object defining a custom footer with source and height properties.
protection - Object defining PDF restrictions and passwords.
watermark - Object defining a watermark to add to the document.

Development

Setup

Run the setup script to install system dependencies and register git hooks:

bin/setup

This installs actionlint, check-jsonschema, lefthook, and mado via Homebrew, then registers the pre-commit hooks.

Then install Elixir dependencies:

mix deps.get

Commands

Task	Command
Run tests	`mix test`
Run a single test file	`mix test test/pdf_shift/client_test.exs`
Run a single test	`mix test test/pdf_shift/client_test.exs:42`
Lint	`mix credo`
Format	`mix format`
Generate docs	`mix docs`

License

The package is available as open source under the terms of the MIT License.