kennethormandy/craft-api2pdf

Generate PDFs using api2pdf.com

1.0.0-beta.1 2023-01-12 20:13 UTC

Requires

• api2pdf/api2pdf.php: 1.1.1
• craftcms/cms: ^3.1.0|^4.0.0

Requires (Dev)

• codeception/codeception: ^4.0
• codeception/module-asserts: ^1.1
• vlucas/phpdotenv: ^4.1

MIT

• Kenneth Ormandy

• cms
• pdf
• Craft
• craftcms
• craft-plugin
• api2pdf

README

Api2Pdf plugin for Craft CMS

Generate PDFs easily, using Api2Pdf.com

Requirements

This plugin requires Craft CMS 3.1.x or later, or Craft 4.0.0 or later.

Installation

The Craft 4 version of the plugin is currently tagged as a beta release. You can install it with:

composer require kennethormandy/craft-api2pdf:^1.0.0-beta.1

Otherwise, require the plugin using Composer like normal:

composer require kennethormandy/craft-api2pdf

Then, in the Craft CMS Control Panel, go to Settings → Plugins, and click the “Install” button for Craft Api2Pdf. Or run:

./craft install/plugin api2pdf

Settings

The only setting required to run the plugin is an API key from Api2Pdf, which can (and probably should) be set to an environment variable:

Actions

• api2pdf/pdf/generate-from-url
• api2pdf/pdf/generate-from-html
• api2pdf/pdf/merge

Twig

• craft.api2pdf.generateFromUrl
• craft.api2pdf.generateFromHtml
• craft.api2pdf.merge

Options

Option	Type	Description
filename	String
redirect	Boolean	Redirect directly to the PDF URL

• filename
• redirect

All advanced options for Headless Chrome to pass along to Api2Pdf are also supported.

Examples

Action generate-from-url

Get the JSON response from Api2Pdf:

<form method="post" action="" accept-charset="UTF-8">
  <input
    type="hidden"
    name="action"
    value="api2pdf/pdf/generate-from-url"
  />
  <input type="hidden" name="url" value="https://example.com" />
  {{ csrfInput() }}
  <input type="submit" value="Generate PDF from URL" />
</form>

Redirect directly to the PDF url:

<form method="post" action="" accept-charset="UTF-8">
  
  <input
    type="hidden"
    name="action"
    value="api2pdf/pdf/generate-from-url"
  />

  <!-- Set the URL (your site or any public URL) to use -->
  <input type="hidden" name="url" value="https://example.com" />

  <!-- Redirect to the PDF URL -->
  <input type="hidden" name="options[redirect]" value="1" />

  {{ csrfInput() }}
  <input type="submit" value="Generate PDF from URL with a redirect" />
</form>

Action generate-from-html

Redirect directly to the PDF made using an HTML string:

<form method="post" action="" accept-charset="UTF-8">

  <input
    type="hidden"
    name="action"
    value="api2pdf/pdf/generate-from-html"
  />

  <!-- Set the custom HTML string -->
  <input type="hidden" name="html" value="<p>Hello from action with HTML</p>" />

  <!-- Redirect to the PDF URL -->
  <input type="hidden" name="options[redirect]" value="1" />

  {{ csrfInput() }}
  <input type="submit" value="Generate with redirect from HTML" />
</form>

Offer an editable filename:

<form method="post" action="" accept-charset="UTF-8">

  <input
    type="hidden"
    name="action"
    value="api2pdf/pdf/generate-from-html"
  />

  <!-- Set the custom HTML string -->
  <input type="hidden" name="html" value="<p>Hello</p>" />

  <!-- Set the filename to the value of the form input -->
  <input type="text" name="options[filename]" value="test.pdf" />

  {{ csrfInput() }}
  <input type="submit" value="Generate from HTML" />
</form>

Action merge

Merge two hosted PDFs (generated by this plugin or otherwise), into one:

These URLs passed to this function need to be hosted PDFs. Whether or not they were previously generated via this plugin previously, or whether they are on your server doesn’t matter, as long as they are accessible at the URL.

{% set urls = [
  'https://example.com/one.pdf',
  'https://example.com/two.pdf'
] %}

<form method="post" action="" accept-charset="UTF-8">
  <input
    type="hidden"
    name="action"
    value="api2pdf/pdf/merge"
  />
  {% for url in urls %}
    <input type="hidden" name="urls[]" value="{{ url }}" />
  {% endfor %}
  {{ csrfInput() }}
  <input class="btn" type="submit" value="Merge PDFs" />
</form>

Twig generateFromUrl function

{% set result = craft.api2pdf.generateFromUrl('https://example.com') %}

{% if result and result.success %}
  {{ result.pdf }}
{% endif %}

Twig generateFromHtml function

{% set result = craft.api2pdf.generateFromHtml('<h1>Hello</h1>') %}

{% if result and result.success %}
  {{ result.pdf }}
{% endif %}

Slightly more detailed example:

{% set options = {
  redirect: true,
  filename: "test.pdf"
} %}
{% set result = craft.api2pdf.generateFromHtml('<h1>Hello</h1>', options) %}

{% if result and result.success %}

  {# Display the URL #}
  <p>{{ result.pdf }}</p>

  {# The other pieces of metadata available #}
  <ul>
    <li>{{ result.mbIn|round }}mb</li>
    <li>{{ result.mbOut|round }}mb</li>
    <li>US${{ result.cost|round }}</li>
    <li>{{ result.responseId }}</li>
  </ul>
  
{% else %}
  <p>{{ result.error }}</p>
{% endif %}

Twig merge function

{% set urls = [
  'https://example.com/one.pdf',
  'https://example.com/two.pdf'
] %}
{% set result = craft.api2pdf.merge(urls) %}

{% if result and result.success %}
  {{ result.pdf }}
{% else %}
  {{ result.error }}
{% endif %}

Notes

• This plugin is build for v1 of the Api2Pdf API, but support for the v2 endpoint may be added when it’s out of beta, the Api2Pdf client libraries are also updated
• This plugin only supports Headless Chrome for PDF generation. If you are interested in adding support for another endpoint, I’d be open to discussing a Pull Request (but note the v2 API also only supports Headless Chrome).

License

The MIT License (MIT)

Copyright © 2019–2020 Kenneth Ormandy Inc.