Frontend Settings

Frontend refers to the front end of your website; the side of your website facing outward. Frontend settings are PDF stamping settings that apply to everything visible to your customer/user.

Setup

Choose a PDF manipulation library

In order to programmatically change a PDF, its code must first be read by a parser. The parser reads the PDF into memory, trying to understand the beginning, middle, and end of the PDF, based on the PDF specification (and allowing for some cases involving common syntax errors, e.g. malformations). The parsers are free/open-source FPDI, free/open-source TCPDI, paid FPDI PDF-Parser, and paid SetaPDF Core. The free version of FPDI is limited in that it will only PDFs up to version 1.4. The free version of TCPDI can handle PDFs to version 1.7 but is not maintained. Here is more information about choosing a PDF read/write library set.

Therefore, because these parsers are so limited, and because PDFs are so diverse and evolving, we will always recommend purchasing one of Setasign’s PDF libraries, either FPDI PDF-Parser or SetaPDF Stamper. If you have troubles with your PDF “not working,” we will recommend you purchase from Setasign. You are welcome to use the free libraries and it is very possible you will have good luck there; however, we will not guarantee it.

It is recommended you save settings immediately after choosing a library, since each library has a slightly different set of the following settings.

Start Page

Enter the number (1 or 2 or 5, for example) you wish inking to begin on. If it is the first page, enter 1. If you only want the last page watermarked, choose “Last Page Only” on the Pages to Stamp setting.

End Page

If you want inking to end on the 25th page, enter 25. If you want inking to go to the last page, enter “last.”

Pages to Stamp

This setting is self-explanatory; however, there is one setting, “Custom,” which maybe needs explaining. If you choose custom, another text field will show up where you can enter a string of the pages you wish to be inked. Here are some examples of what you could type:

1,2,3,4,28-59 (this means all pages except 5-27)

3-7,12-19 (this means all pages except 1,2 and 8-11)

Left/Right Margin

The margins set a “fence” on your PDF which inking will try to stay inside. If your margins are 0 (zero) then inking can go right to the edge of the page. This setting is in millimeters by default.

Font

Each library comes with its own font set, and fonts for each library are stored separately. When you select a library, click Save Settings, then proceed to font selection.

When PDF Ink plugin is first loaded, fonts are moved from the plugin folder to a wp-content/uploads/pdf-ink/fonts folder. If that folder is accidentally emptied/deleted, you may have trouble watermarking. PDF Ink does make attempts to ensure fonts are always available for stamping, so try not to sweat it too much.

IMPORTANT: If your text contains characters like д φ or é, accents, tildes, breves, carons, cedillas, dots, etc., e.g. your language is not English, then maybe do not use FPDF, and do not use the base fonts included with PDF Ink: Helvetica, Times, Courier. If your selected font isn’t subsetted for characters anticipated in your watermarks and/or the font isn’t embedded in the PDF, characters might show up as boxes □ or � question marks.

TCPDF supports UTF-8 and comes bundled with the most fonts. To support other languages from around the world, we have included various other fonts which are generously subsetted. Select the “Deja Vu,” “AE Furat,” “AE Al Arabiya,” “M Sung,” “Kozmin Pro,” or “Kozgo Pro” font in the Settings panel if your language uses accent characters. To see if your language will be watermark-able with the Deja Vu font, view this chart. Select Furat for Arabic script, or M Sung for Chinese, Kozmin or Kozgo for Japanese. Fonts which come with TCPDF can also be added back in to the fonts folder; some were removed to keep this plugin as lightweight as possible.

Right to Left (RTL) watermarking is possible with TCPDF.

True Type Fonts (.ttf) can be added to any PDF Ink library. Below the font selection setting you should see a clickable link to the Font Uploader. If not, you can navigate there via WordPress menu -> Pages to Stamp -> Fonts. This drag-and-drop feature allows .ttf font file inputs, and prepares the fonts for your PDFs. After a font is added, you will find it in the font selection setting, and can save that setting. Adding a font which is carefully subsetted for your needs can not only make your PDFs easier to read, but can save a lot of PHP memory, too.

If your library is SetaPDF-Stamper, your font file is stored but not processed at the time. It is processed during PDF manipulation, and further coding might be required to ensure the correct encoding and subsetting is used.

Right to Left (RTL)

If this checkbox is checked, the PDF writer will move from the right side of the page to the left, instead of left-to-right.

Placement Settings

PDF Ink allows for 1 or more watermark placements on the page, naturally up to 4. We recommend one or two, but won’t stop you if you want more. 🚥 Here is how to get supernatural and have more than four. Add the following PHP snippet to your child theme functions.php file in order to have 6 placements per page:

add_filter( 'pdfink_placement_number', function( $num, $source ) { return 6; }, 10, 2 );

Each placement has the following content settings:

Content

A lot can be done here, or nothing. If nothing is entered here, nothing will show. Maybe you only want to password your PDF. That is fine!

Many “magic tags” are available to help create dynamic content. More about magic tags below.

HTML in Content

If you are using TCPDF, HTML is allowed. TCPDF allows these tags: <a> <b> <blockquote> <br> <dd> <del> <div> <dl> <dt> <em> <h1> <h2> <h3> <h4> <h5> <h6> <hr> <i> <img> <li> <ol> <p> <pre> <small> <span> <strong> <sub> <sup> <table> <td> <th> <thead> <tr> <u> <ul>

That means the following would work to create some centered, and italicized text:

<span style="text-align:center">Some centered and <em>italicized</em> text!</span>

If using an <img> tag in your stamp content, the image width and height attributes must be set. Transparent images make great watermarks, just make sure to use a small image file (smush those bytes)!

There is no HTML allowed with FPDF and only a little HTML is allowed in SetaPDF-Stamper. SetaPDF-Stamper also allows these tags: <div> <span> <b> <strong> <i> <em> <sub> <sup> <u> <br>.

Images as Content

PDF Ink comes with four possible placements* and each one can have an image or text content. (These can overlap with FPDF and TCPDF, giving 8 built-in stamps per page, but YMMV.) To add an image to your PDF page, simply fill in the following settings:

Image Path

Though this setting is ultimately saved as a file path, you can enter a URL in the settings field and it will be converted to a path for you. Make sure the file has permissions 755 and is stored on the same server as your PDF Ink installation.

Supported formats are JPEG and PNG images without GD library and all images supported by GD: GD, GD2, GD2PART, GIF, JPEG, PNG, BMP, XBM, XPM;

If no dimentions are set, the image is output at 72dpi.

Supported formats are JPEG, PNG and GIF. The GD extension is required for GIF. Transparency is supported. For JPEGs, all flavors are allowed:
  • gray scales
  • true colors (24 bits)
  • CMYK (32 bits)
For PNGs:
  • gray scales on at most 8 bits (256 levels)
  • indexed colors
  • true colors (24 bits)
For GIFs: in case of an animated GIF, only the first frame is displayed.

SetaPDF-Stamper allows for stamping with PNG, JPEG, JPEG2000 and GIF images. If an image is used in a placement, the content saved for that placement will not be used. Use another PDF Ink placement to add additional text to the page alongside the image.
Width

Set the width in pixels (optional).

If using FPDF, this setting can be used to set the DPI. Use a negative integer (e.g. -300) to set the DPI.

Height

Set the height in pixels (optional).

If using FPDF, this setting can be used to set the DPI. Use a negative integer (e.g. -300) to set the DPI.

If either width or height is not set, the base image width and height will be used. If only one is set, the image will be scaled accordingly.

*You can have more than four placements using the pdfink_placement_number WP filter hook.

Using HTML & TCPDF

When using TCPDF, images can be stamped onto PDFs using HTML. This is great for adding a logo or an image watermark to a PDF right in an HTML string possibly also containing text, and can lead to creative and impactful results. With TCPDF, use an HTML <img> tag to add your image. If you need help with this, just get in touch.

As an example, the next block of HTML would embed an image in your PDF (TCPDF only):

<img src="../../relative/path/to/your/image.png" width="400" height="300">

The next example of HTML use would center the image left-right on the page:

<span style="text-align:center"><img src="../../relative/path/to/your/image.png" width="400" height="300"></span>

Font Size

Font size is a numeric input, and fonts are sized in points by default.

Font Color

Font color input is expected in HEX format, e.g. #CC0000. A color selection tool is there for your convenience.

Bold/Italic

(FPDF only) If bold and/or italic is checked, all the text will be bolded and/or italicized. Finer control is possible with TCPDF, which allows for using the HTML <strong> and <em> tags ad lib inside your sentences, rather than having to italicize or bold entire placements.

Font Opacity

(FPDF/SetaPDF-Stamper/TCPDF) TCPDF uses {OPAC-[0-1]}{/OPAC} magic tags to create transparency ad-lib. FPDF and SetaPDF-Stamper on the other hand, allow the entire content block’s opacity to be changed. For FPDF and SetaPDF-Stamper, enter a number between 0 and 1 (in hundredth increments) in the settings to change away from the default which is 100% opaque (0% transparent).

Opacity and Magic Tags

In TCPDF you can use the special tag “{OPAC}” to indicate a block of transparent text in your content. If you are using TCPDF and have access to customer data because you’re using Woo|DLM|EDD, the following content would look like a 25% transparent read out of the customer’s first and last name, email, and a date 1 year out from purchase:

{OPAC-0.25}Licensed to [FIRSTNAME] [LASTNAME] (email: [EMAIL]), expires: [DATE-1YRS]{/OPAC}

Notice the closing {/OPAC} tag, which is important, too. This example also uses PDF Ink “magic tags,” so we’ve gotten a little ahead of ourselves. More on magic tags below.

TIP: transparent (invisible) watermarks are a great way to trick and catch pirates. 🏴‍☠️

Line Spacing

(SetaPDF-Stamper only) Space between lines of text. By default this is font size / 2.54 (font size divided by 2.54).

Alignment

(SetaPDF-Stamper only) Left, Right or Center of the page.

Vertical Positioning

(SetaPDF-Stamper only) Top, Middle or Bottom of the page.

X-Axis Fine Tuning

Use this setting as a tool to fine-tune the position of your content on across the page on the X axis, one millimeter at a time. 0 is the left of the page. This tuning is added to your margins.

Y-axis Fine Tuning

Fine-tune the position of your content up and down the page on the Y axis, one millimeter at a time. 0 is the top of the page. If you use negative integers (e.g. -10) you will be moving from the bottom of the page. Tricky! So if you want your content box to start 3 centimeters from the bottom of the page, enter -30 (30 millimeters is 3 centimeters). If you want your content box to start 3 centimeters from the top of the page, enter 30.

This tuning is added to your margins.

Rotation

Enter 0-359. Rotation occurs counter-clockwise. We aren’t sure why it doesn’t also happen clockwise. Or maybe it does. We get turned around. 🎡 Use this setting along with margins and fine tuning to bring your watermark vertical along the right or left margin of the page — great for sheet music!

Hint: If you use the RTL checkbox and rotation together, you can reverse the aspect of your rotation.

Security Settings

Fallback

If for some reason the PDF cannot be manipulated, do you want to send a copy of the original PDF out to your customer/user, or fail with an error message?

Encryption Level

Protecting a PDF with limited permissions and/or passwords requires encryption. Encryption can increase the processing time and possibly cause a PHP time-out in some cases, especially if the PDF contains images, HTML or embedded fonts.

Your server must have OpenSSL installed to encrypt PDFs. We recommend you perform testing with encryption before launching to ensure your server can handle the load.

FPDF only has RC440 and RC4128 level encryption. RC440 encryption can be used to get the ball rolling with passwords and permissions on your PDF, but be aware it is no longer considered secure and has fallen out of favor.

Document Permissions

Encrypting a PDF allows permissions to be set. Permissions can be changed in the plugin settings as long as encryption is turned on.

The permission array is composed of values taken from the following:

  • print : Print the document
  • copy : Copy or otherwise extract text and graphics from the document
  • modify : Modify the contents of the document by operations other than those controlled by ‘fill-forms’, ‘extract’ and ‘assemble’
  • annot‑forms : Add or modify text annotations, fill in interactive form fields, and, if ‘modify’ is also set, create or modify interactive form fields (including signature fields)
  • fill‑forms : Fill in existing interactive form fields (including signature fields), even if ‘annot-forms’ is not specified
  • assemble : Assemble the document (insert, rotate, or delete pages and create bookmarks or thumbnail images), even if ‘modify’ is not set
  • print‑high : Print the document to a representation from which a faithful digital copy of the PDF content could be generated. When this is not set, printing is limited to a low-level representation of the appearance, possibly of degraded quality.
  • extract : Extract text and graphics (in support of accessibility to users with disabilities or for other purposes).

128-bit encryption is required for permissions fill-forms, assemble, print-high, and extract.

We recommend you allow copy and extract. If not allowed, the PDF will not be readable by humans who rely on screen readers instead of their eyes to read. Keep it accessible!

TCPDF uses SetProtection() and FPDI Protection uses something similar. More information about SetProtection() here and here.

The ‘pdfink_filter_permissions’ filter hook allows you later control of your file permissions, maybe based settings passed in parameters. Keep in mind, this hook will override any general settings or per-product settings. You can take advantage of the filter as follows (preferably in your child theme functions.php file or a custom plugin):

function pdfink_filter_permissions( $permissions, $settings ) {
    $permissions = array( 'modify', 'copy' ); // maybe add any others you may want to block here, in the array
    return $permissions;
}

User Password

PDF Ink allows you to set two types of password: user and owner. If you don’t set any password, the document will open as usual.

If you set a user password, the PDF viewer will ask for it before displaying the document. Typing the word “email” into the settings password field will force the end user to open the PDF with the downloader’s email address (if collected by anticipated means, WooCommerce/EDD/DLM). The word email works magic in this case, but must be lowercase and without punctuation. Note: If you type the magic tag “[EMAIL]” into the settings password field, the password to open the PDF will be [EMAIL] (the magic tag does not work magic in the password field — it’s just wrong).

Similarly, if you type the word “phone” (lowercase) into the settings password field, a phone number (IF COLLECTED during checkout) will be set as password.

Keep your sanity — here are some ideas to consider before selling passworded PDFs.

Alternatively the ‘pdfink_filter_password’ hook can be used to programmatically set a different password (based on unique $_POST data, for example) if desired. This example uses the customer’s billing phone. It would be important in this instance to require a phone number from your customers!

add_filter( 'pdfink_filter_password', 'my_own_password_function', 10, 2 );
function my_own_password_function( $password, $settings ) {
    try {
        $order = wc_get_order( $settings['uid'] );
 
        $order_data = $order->get_data();
        $phone = $order_data['billing']['phone']; // might be wise to set up a fallback in case this is empty
        // maybe remove any non-digit character from phone number
        $password = preg_replace('/D+/', '', $phone);
        // return phone as password
    } catch ( Exception $e ) {
        error_log( 'Unable to get a WooCommerce order object from UID in settings array.' );
    }
    return $password;
}

Owner Password

Most people do not know the owner password for their PDFs, and nobody should know the owner password for your PDFs. If someone has your PDF owner password, they can remove all protections and own full control over the PDF content.

With the creation of each PDF, an owner password is generated for you if one is not set here. One must be set, so we recommend you set something good and un-guessable here.

Unlock with User Password

This setting completely unlocks the PDF for your customer with their user password, as if it were an owner password. We don’t recommend turning this on in 99.9% of cases, but if you have a use for it, it is here for you.

Original/open Password

(SetaPDF-Stamper only) If your PDF is passworded and you want for it to stay passworded on the server, you can put the password here and SetaPDF Core will unlock the PDF before manipulation. The password is obfuscated when stored in your WordPress database.

Otherwise, all PDFs must be un-encrypted (no passwords, no protections) in order for PDF manipulation libraries to interact with them.