EDDiMark Documentation

EDDiMark does its magic using the third-party open-source TCPDF and TCPDI libraries.

TCPDI parses the existing PDF (assuming it is unencrypted and uncorrupted), parsing it into memory. TCPDF takes what TCPDI found then applies your watermark. Regretfully, TCPDI is unable to parse certain PDF elements into memory, such as internal links and forms. Understanding a little about how TCPDI and TCPDF come into play, using PHP memory, might help you to create the most effective and efficient watermarks.

Recommendations

Learn more about how to tune your watermarking settings and your server for the best TCPDF performance.

Settings

You can find the EDDiMark PDF settings page by clicking on the “Settings” link under the EDD “Downloads” menu in WordPress, and navigating to the “Extensions” tab.

Watermark Testing

EDDiMark offers on-the-fly manual creation of watermarked PDFs on the settings page (admin-side). You no longer have to go through a mock purchase to watermark a file, and all the same features that were available on the front end are now available on the back end. Learn more about the “test kitchen” for PDF stamping below.

Margins

EDDiMark default top/bottom and left/right margins are set to zero, meaning your default watermark will appear in the top left corner, without spacing. You can use margins to move your watermark stays away from the page edges. You can also use X and Y fine tuners to move the watermark across (X) and down (Y) the page. Remember, measurements are in millimeters.

Usually, you’d use the Y tuner to move your watermark DOWN from the TOP of the page, millimeter by millimeter. If you have PDFs with varying heights and want better control of where the watermark sits, you can move the footer watermark UP from the BOTTOM of the page by using a negative integer (e.g. -10, which would be 10mm) in the Y fine tuner setting. Just make sure to keep your watermark within the page boundaries — if it goes off the page, EDDiMark will create a new (unwanted) blank page with the orphaned watermark.

As far as watermark positioning goes, the X-axis and Y-axis tuners work across and down the page in MILLIMETERS. If you’ve moved your watermark too far down the page, it will create a blank page. Reduce your Y-axis number and/or your font size to get the watermark back on the page.

It’s very important to test your watermark settings until you are sure the watermark will fit inside the margins you have set, otherwise you will see problems.

Simple Shortcodes

Simple shortcodes available are [FIRSTNAME] [LASTNAME] [BUSINESSNAME] [EMAIL] [PHONE] [DATE] [TIMESTAMP] [PAYMENTID]. Using one of these in your overlay or footer text will cause the shortcode to be replaced by the customer data during watermarking. The customer data must exist in the order for the shortcode to function, of course.

[DATE] Shortcodes

[DATE] can be used as-is, and will insert the order date. This is different from [TIMESTAMP], which marks the moment the PDF is marked/downloaded.

Future [DATE] Shortcodes

To add a future date marked from the date of purchase, you can use the [DATE-#YRS] [DATE-#MOS] [DATE-#WKS] [DATE-#DAYS] shortcode, where # is replaced with the number of days/months/weeks/years desired. This shortcode is based on 30-day months, and 365-day years, so it might be best to use days if you need precision.

Examples

[DATE-365DAYS] would be 365 days from the checkout date.

[DATE-2YRS] would be 730 days from the checkout date, but does not take into account a leap year.

Opacity Shortcodes

The {OPAC} shortcode — and watermarking with opacity — is totally unique to this plugin is very helpful for people not wanting to obscure their PDF content, since the watermark sits on top. Some people use this shortcode to create an invisible — or nearly invisible — text watermark.

The {OPAC} shortcode doesn’t always play nice with HTML in your watermark, so sometimes some rearranging will need to be done. Consider wrapping your HTML inside {OPAC} tags if trying to get opacity, if the inverse isn’t working.

Examples:

{OPAC-0.5}This is sample text{/OPAC}

“This is sample text” will be at 50% transparency. The tag needs a dash, then a number representing the fraction of 100% opacity.

{OPAC-0.1}This is very transparent text{/OPAC}

“This is very transparent text” will be at 10% transparency.

Note there is an open tag and a close tag around the text. If text does not wrap when using this tag, you may have to use HTML <br> tags. {OPAC} tag is still beta.

Text alignment

To style a link <a> or tag when using HTML, the following inline CSS options are available: font-style:italic, font-weight:bold, and text-align:center and text-align:right. This feature allows you to center text – yay!

Here’s an example of the code used to center some text.

<span style=”text-align: center; font-weight: bold;”>center some bold text</span>

This might also work:

<span style=”text-align: center;”><strong>center some bold textManual / Test Watermarking Screenshot of testing settings

Added in v2.0, the “test kitchen” allows you to preview your watermarks before going live with them. The test watermark will observe all of the EDDiMark general settings, but also allow you to enter any customer (or mock customer) details to flesh out any shortcodes you may have used ([FIRSTNAME], [LASTNAME], etc.). Have fun with it!

File Management & Cleanup

Watermarked files are delivered to the customer, but in order for that to happen, they must remain on the server for at least a very brief period of time.

After watermarking and delivery, watermarked files are moved to folders made unique by the customers’ payment IDs. If these files are not immediately deleted, they will sit forever… unless you turn on the “Schedule file deletion?” EDDiMark setting. Deletion can be set to every hour, twice daily, daily, or weekly.

EDDiMark PDF management settings

This will add watermarked files to a cron job which handles deletion for you. If you have the “recycle” option selected, files still inside the EDD “Download Link Expiration” window will be kept on the server. Why recycle? Because PDF watermarking can be memory-intensive, and delivering a customer’s already-watermarked file you have stored puts less pressure on the server. Want your files to be deleted on a different schedule?

Hooks (actions/filters)

Hooks were included to make it possible to adjust EDDiMark to carry out some of your specific needs. The hooks are no supported by EDDiMark staff unless you find a bug or need arguments added. We will not be able to write actions and filter code for you. The hooks were placed for your developer’s convenience.

‘ eddimark_add_custom_font ‘ and ‘ eddimark_font_decode ‘, and ‘ eddimark_out_charset ‘ filters, more here (Also note that as of version 1.5, the plugin comes with an automatic font uploader; you can upload your own TTF font to the watermarker, leaving these hooks a lot less necessary for custom font work.)

‘ eddimark_add_barcode ‘ filter for maybe adding barcodes

‘ eddimark_settings_array ‘ filter to allow for manipulation of main watermarking settings (possibly to add settings).

‘ eddimark_set_zoom_mode ‘ and ‘ eddimark_set_viewer_preferences ‘ filters for setting PDF viewing preferences via TCPDF. Examples of SetDisplayMode() in use. More on TCPDF setViewerPreferences() here.

Immediate deletion. If you are using “Forced” downloads (vs. “Redirect,” an EDD Settings->Misc->File Downloads setting), you can clean watermarked files off the server immediately using the ‘ eddimark_do_cleanup ‘ filter hook, with something like the following code in your theme or in a plugin:

add_filter( 'eddimark_do_cleanup', '__return_true' );

Your original PDF file names are preserved during watermarking. This is done by moving the marked file either into:

  • a) (Most likely) a folder named after the EDD Payment ID in the wp-content/uploads/eddimark-pdf/ folder. For example, a PDF downloaded for Payment ID 3589 would move to the wp-content/uploads/eddimark-pdf/3589 folder. This folder location can be changed by reassigning the ‘EDDIMARK_TMP_FILEPATH’ constant.
  • b) If a) doesn’t work, the plugin will use get_temp_dir() to find a suitable temporary location, which might be your /tmp directory. (/tmp won’t work with NGINX) But inside that directory, your files will be in folders named like this: “eddimark_paymentID” where paymentID is a number equal to the customer’s payment ID.

Need to change the way your files are named? As of version 2.0, this is no longer likely, but if so, you can use the ‘ eddimark_file_name ‘ hook. The new file name is also delivered to customers. Here’s an example of adding the download key to the file name:

add_filter( 'eddimark_file_name', 'eddimark_alter_file_name', 10, 2 );
eddimark_alter_file_name( $file_name, $key, $args ) {

    // replaces the timestamp in the filename with the unique download key
    $file_name = $file_name . '_' . $key . '.pdf';
    return $file_name;

}

Barcodes (maybe adding)

To add a barcode somewhere on your page, you can use the ‘eddimark_add_barcode’ filter. An example goes like this:


add_filter( 'eddimark_add_barcode', 'eddimark_barcode_function', 10, 1 );
function eddimark_barcode_function( $barcode_array ) {
    return array( '2D', 'Test Barcode', 'QRCODE', 100, 230, 30, 30 );
}

This hooked function adds a QR code to your PDF, 100mm from the left, and 230 mm down the page, 30mm square size. This could be really cool for adding a QR code to your PDF file – a receipt, a ticket, or any other confirmation needing scanning.

The ‘my_barcode_function’ function returns an array used by EDDiMark to create a barcode.

  1. The first argument accepts either ‘1D’ or ‘2D’.
  2. The second argument will be your barcode contents.
  3. The third argument states the TYPE of barcode (please refer to TCPDF documentation for 1D vs 2D barcode setup and appropriate names for barcode types.)
  4. The fourth argument is X-axis placement. In the example, I have it set 10cm (100mm) over to the right.
  5. The fifth argument is Y-axis placement. In the example, I have it set 23cm (230mm) over to the right.
  6. The sixth argument is the width of the barcode in millimeters.
  7. The seventh argument is height of the barcode in millimeters.

Font use

One reason watermarks might not show up is when the watermark contains special characters but a font which doesn’t support those characters is in use. Sometimes the watermark might show up as question marks (???????). This usually just means you need to try using a different font.

Select the “Deja Vu,” “Furat,” or “M Sung” 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. EddiMark PDF can do RTL watermarking.

To run watermarking with your custom font, go to https://yoursite.com/wp-admin/options-general.php?page=eddimark-fonts Once your TTF font is added using the font uploader at this URL, it will be available to you in the EDDiMark settings.

Alternatively, you can run the filter “eddimark_add_custom_font”. If you’re not a developer you might want to stop reading here. Font must be added to TCPDF first using AddFont(). Please read TCPDF docs. Fonts which come with TCPDF can also be added back in to the fonts folder; they were removed to keep this plugin as lightweight as possible.

add_filter( 'eddimark_add_custom_font', 'eddimark_custom_font_name', 10, 1 );
function eddimark_custom_font_name() {
    $font = TCPDF_FONTS::addTTFfont( $font_file, $font_type, $enc, $flags, $outpath, $platid, $encid, $addcbbox, $linkbox );
    return $font;
}

Keep in mind the $font value you return will be run in SetFont() while EDDiMark does its magic.

addTTFfont() parameters:

$fontfile (string) Font file (full path).
$fonttype (string) Font type. Leave empty for autodetect mode. Valid values are: TrueTypeUnicode, TrueType, Type1, CID0JP = CID-0 Japanese, CID0KR = CID-0 Korean, CID0CS = CID-0 Chinese Simplified, CID0CT = CID-0 Chinese Traditional.
$enc (string) Name of the encoding table to use. Leave empty for default mode. Omit this parameter for TrueType Unicode and symbolic fonts like Symbol or ZapfDingBats.
$flags (int) Unsigned 32-bit integer containing flags specifying various characteristics of the font (PDF32000:2008 – 9.8.2 Font Descriptor Flags): +1 for fixed font; +4 for symbol or +32 for non-symbol; +64 for italic. Fixed and Italic mode are generally autodetected so you have to set it to 32 = non-symbolic font (default) or 4 = symbolic font.
$outpath (string) Output path for generated font files (must be writeable by the web server). Leave empty for default font folder.
$platid (int) Platform ID for CMAP table to extract (when building a Unicode font for Windows this value should be 3, for Macintosh should be 1).
$encid (int) Encoding ID for CMAP table to extract (when building a Unicode font for Windows this value should be 1, for Macintosh should be 0). When Platform ID is 3, legal values for Encoding ID are: 0=Symbol, 1=Unicode, 2=ShiftJIS, 3=PRC, 4=Big5, 5=Wansung, 6=Johab, 7=Reserved, 8=Reserved, 9=Reserved, 10=UCS-4.
$addcbbox (boolean) If true includes the character bounding box information on the php font file.
$link (boolean) If true link to system font instead of copying the font data (not transportable) – Note: do not work with Type1 fonts.

If your overlay or footer are not looking right after you’ve added a new font, the filter ‘eddimark_font_decode’ might need to be used to add html_entity_decode() around your overlay or footer input.

‘ eddimark_timeout_extend ‘ for extending the timeout used by wp_remote_get() to fetch remote PDF files. Default is 15 seconds.

Passwords & Encryption

Be aware that protecting a PDF requires to encrypt it, which increases the processing time a lot. This can cause a PHP time-out in some cases, especially if the document contains images or fonts.

The file will be automatically encrypted if a password is set. 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 (learn more about implications here). Typing the word “email” into the password field in EDDiMark settings will force the end user to open the PDF with the buyer’s email address.

The permission array is composed of values taken from the following ones (specify the ones you want to block):

  • The following are set together:
    • print : Print the document
    • 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.
  • The following are set together:
    • modify : Modify the contents of the document by operations other than those controlled by ‘fill-forms’, ‘extract’ and ‘assemble’
    • assemble : Assemble the document (insert, rotate, or delete pages and create bookmarks or thumbnail images), even if ‘modify’ is not set
  • copy : Copy or otherwise extract text and graphics from the document
  • The following are set together:
    • 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

More information about SetProtection() here.

Recommended you allow:
  • Copy. If not allowed this document will not be readable by humans who rely on screen readers instead of their eyes to read. Keep it accessible!

Why does the watermark go off the page, create new pages?

Your watermark text string is too big or long for the page! A blank page was created trying to accommodate the overflowing text.

Try decreasing font size, adjusting margins, adjusting rotation, or using the X and Y fine tuners to move the watermark back onto the page. The built-in adjustments on the settings page ultimately allow for watermarking on all document sizes. You may need to edit your watermark if it is too verbose.

If you find the PDF seems to look different after it is watermarked, it’s quite possible your PDF wasn’t displaying properly in the first place. There are countless variations and interpretations of PDF syntax such that the application you use to view your PDF might show it differently than the next application. If you send a copy of the PDF and we find that it also looks “incorrect” to you in Adobe Acrobat, we have found the problem: your PDF syntax is poor, and the open-source PDF parser/writer used in EDDiMark is just reproducing what it has found. Again, try re-saving the file with Apple Preview, or editing crop boxes/clip paths with Adobe Acrobat/Illustrator, then try again. Bottom line: your PDF must have reasonably predictable PDF syntax in order for a machine to be able to read it consistently across all applications.

Troubleshooting

If you are getting an error message, please let us know right away. Providing us with error logs is very helpful toward resolving your issue more quickly. Here are a couple errors which are occasionally encountered by users:

Uncaught exception ‘InvalidArgumentException’ with message ‘Cannot open’…”

If you get this error while trying to watermark or test watermark a file, it is likely because your PDF file isn’t found or the filename uses unsafe characters like spaces in the PDF file name. We recommend you replace spaces with dashes.

Fatal error: Allowed memory size of n bytes exhausted

If you get this error, please refer to “TCPDF Recommendations“.

If you are attempting to encrypt your PDF, and are getting blank pages, your server might not support the encryption level you’ve chosen. This happens more often with AES encryption, so try RC4 instead. There are also other reasons your PDFs might gain blank pages.

Meanwhile, here are some things to try:

  • Make sure you have checked the box at the top of your settings page (Downloads -> Extensions -> PDF Watermark) so that watermarking is enabled! If you’d rather just watermark a couple files, or certain files, list them in the textarea box below the global watermark checkbox, one file name per line.
  • Make sure your uploaded PDF file is not already encrypted/passworded. EDDiMark PDF needs full access to an unadulterated PDF to do its magic!
  • Some PDF files are mildly corrupted. Re-saving them with Apple Preview or Adobe Acrobat can help clean them up so EDDiMark can do its job. If we find that your PDF is the problem and not EDDiMark, it is up to you to repair your PDF.
  • If you are getting ???? instead of your watermark, make sure the font you are using is subsetted for your language characters. When in doubt, please try Déjà Vu, Furat or M Sung.
  • Maybe make sure your original file name doesn’t contain spaces. Replace blank spaces with dashes or underscores and keep file names simple. This isn’t usually the cause of problems, though.

Errors and Error Logging

If you are having troubles with EDDiMark (and maybe the libraries it uses, TCPDI/TCPDF), it’s often very helpful to know what’s going on “under the hood.” There are two ways to get more information, especially if you are not getting descriptive error messages printed to your screen. Here’s two places to look:

Especially if your site is in development, it’s great to leave WordPress debugging turned on. We usually turn it off for production sites unless there is a problem, and only then turn it on temporarily. Please read about how to turn on Wordpress debugging. In the wp-config.php file, we use the following three lines so logs are saved to a file and not printed to the screen. It’s prettier that way.

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Logs will be stored in your Wordpress /wp-content/ folder.

Maybe Easier Debugging…

If you don’t feel comfortable editing your wp-config.php file or using a WP Debugging plugin, you can also turn on Easy Digital Downloads debugging in the EDD settings. Go to Downloads->Settings->Misc and check Debug Mode to turn it on. This may provide some clues if you are having troubles. We recommend turning debugging off again when everything seems to be going OK.

How do I activate my API license key?

An API key is not necessary for the plugin to have full watermarking functionality. However, activating your license key allows access to automatic plugin updates. Your license key is valid for one year after purchase. Once your license key expires, attempt at updating the plugin might return an “unauthorized” error message. You can find out more on your account page.

Your API key is entered under WordPress Settings -> EDDiMark License. (It is not found in the Easy Digital Downloads or EDDiMark settings panel.) Once on this page, enter your license key, and click the “Activate License” button to activate your license.

Similarly, you can click the “Deactivate License” button to deactivate your license if it is active. Deactivating your license on this screen will make the license available to be used on another site. You can also check the status of or deactivate license keys at via your online account (www.little-package.com/account). Most local/development license key activations do not count toward your license key activation count. If your URL matches the following, it does not count toward key activations:

  • localhost
  • 10.0.0.0/8
  • 172.16.0.0/12
  • 192.168.0.0/16
  • *.dev
  • *.local
  • dev.*
  • staging.*
  • test.*

Can I get an invoice for my plugin purchase?

Yes! You can easily print your own invoice, including a VAT/GST number (if you added one during checkout) by going to “your account page,” clicking on “Purchases,” and viewing the order receipt. Click the red “Print” button at the top of your order review page, and use the print dialog to either print or export a PDF if desired.

Little Package