WP TCPDF Bridge Documentation

This fairly simple plugin allows you to use TCPDF in WordPress to alter PDF files, in three main ways:

  1. Upon upload to the WP Media Library
  2. In the WordPress admin TCPDF “test kitchen”, manually
  3. On the front end by your users, using buttons, links, or forms created via shortcodes

Upon upload to the WP Media Library

This method is optional and should be used with care. Bear in mind that once a PDF is altered by TCPDF, and especially if it is encrypted, it cannot be altered again, so if you are running a PDF through TCPDF while uploading to the media library, it will be saved to your library with a static watermark and might not be watermarked again. Dynamic shortcodes such as [FIRSTNAME] [LASTNAME] [EMAIL] etc. will not work for you, for hopefully obvious reasons. Skip to read about Test Kitchen or Shortcodes if you want to use these dynamic shortcodes. (Frankly, we don’t expect the upload method to be used as much as the other two methods.)

For this feature you’ll want to start with the TCPDF Bridge Settings page (yoursite.com/wp-admin/options-general.php?page=wptcpdfb-settings). Carefully review and fill out the options there. Assuming you have selected to alter all or just some of your PDFs, now when you upload those PDFs to your WordPress media library, they will be altered. Embed, share, and download them off your site as you like.

Turn off this setting when you are finished with it, or you will permanently alter every PDF you upload. Altered PDFs often cannot be altered again if they are encrypted.

In the WordPress admin TCPDF “test kitchen”

The Test Kitchen allows you to Watermark PDFs on-the-fly, anytime from the WordPress admin panel. Just choose a PDF, set your watermarking options (font, color, text, placement, etc.), head over to the “Test Watermark” tab, and click a button. The watermarked file will appear in a new window (or via dialog for download, depending on your browser), where you can save it. The watermarked file is not saved to your Media Library, so if you need that, check out this feature. If you’d like to flesh out some dynamic shortcodes from your overlay and footer watermark content with actual personal information, use the fields under the “Test Watermark” tab.

Shows the settings available for Test watermarking/stamping PDFs with plugin

If you are familiar with WP and PHP you can use the filter hook ‘wptcpfb_wildcard’ to match your own content with the [WILDCARD] shortcode. Many other hooks are available in this plugin for customization, take a look!

On the front end, using buttons, links, or forms created via shortcode

The next tab in the TCPDF Bridge settings area is the shortcode generator. It looks like this, and will have a list of your shortcodes at the bottom if you create any:

Shows the settings for the Shortcode tab of the TCPDF Bridge plugin

The magic shortcode builder for WP TCPDF Bridge. Fill out the form, click Save Changes, and your shortcode will be saved in a list below for your reference (not shown in this screenshot).

The generator creates a small piece of code in [brackets] which you can place in your posts, pages, and widgets where you want a link to a particular PDF, and want that PDF altered upon download click. Experiment with the settings to get the type of link you desire. You can opt to collect user information (name, email) before the download continues, and use that personal information to mark the PDF. If your user is already logged in, you can opt to use their saved personal information to mark the PDF.

Your shortcode might look like this:
[wptcpdfb id=90210 /]
(replace 90210 with the shortcode ID you’ve created in the shortcode generator)

Notes

Front-end watermarking stores watermarked files on your server. In order for TCPDF to watermark the same PDF file over and over again, the watermarked versions must be at least temporarily stored somewhere so they can be delivered. The plugin uses the WordPress uploads folder. In these cases you will find your watermarked PDFs in a ‘wp-tcpdf-bridge’ folder inside your WordPress uploads folder. They will be organized by date and time.

There are cases where the uploads directory will not be used:

  1. When the ‘wptcpdfb_temp_folder’ is used to change the temp directory location
  2. When the inline link shortcode, which uses AJAX to watermark and deliver, is used

Over the years many users have expressed interest in keeping these files; others are concerned about the space they consume on the server. You can use the “Housekeeping: Delete Files Weekly” setting in the main settings panel to have them removed automatically once a week. You can change the schedule from weekly to a schedule of your choice using the ‘wptcpdfb_schedules’ and ‘wptcpdfb_filter_cron_schedule’ filter hooks. ‘wptcpdfb_schedules’ allows you to add a schedule that might not already exist in cron. Once that schedule exists, you can change TCPDF Bridge’s default schedule from weekly to your schedule using the ‘wptcpdfb_filter_cron_schedule’ hook.

You can also delete all these files at any time by clicking the “Housekeeping: Delete Files Now” button. Otherwise, the files are stored in your wp-content/uploads/wp-tcpdf-bridge/ folder, where they can be manually managed any time.

Also note that AJAX file downloads use a browser redirect, which is not a secure method of download. If the point of using this plugin is security, we recommend not using the AJAX shortcodes, as fun as they might be.

Recommendations

Make sure to test your watermarking thoroughly before going live! TCPDF is a fallible third-party library which does its best to parse/understand and re-write your PDF with your desired changes (watermarks/encryption/etc), but it cannot possibly work on all PDFs and on all servers 100% of the time. Stay realistic, think carefully through the process, plan, and do your testing. And remember, we fully support and maintain the Bridge plugin, but not TCPDF (tcpdf.org).

PHP Version

We recommend you run PHP version 7.0 or higher. WP TCPDF Bridge is PHP version 8.1+ compatible, so don’t hesitate to upgrade after making backups. PHP 7.0 is twice as fast for WordPress as PHP 5.6 and processes TCPDF demands much more efficiently! This is the first thing you should try if you’re running out of memory while processing PDFs.

Increase Memory

Increase your PHP memory allotment to at least 64MB. We recommend a 128MB, 256MB or maybe even 512MB setting (don’t keep increasing this expecting it to solve all your problems; though. You could cause problems). If your host does not allow more than 16 or 32, it might be a good time to switch hosts or servers. If you expect your PDF to take more than 30 seconds to parse (gasp!), you may also need to increase your PHP max_execution_time. You may even need to request more CPU from your hosting service.

Large PDFs?

If you are having trouble sharing large PDF files, keep in mind that your hosting plan needs to be robust enough to support the memory and bandwidth necessary to fulfill these requests. Try these suggestions: https://tcpdf.org/docs/performances/. (FYI Thai characters are already disabled in TCPDF.) Keep your watermarks simple (avoid HTML if possible, and remember that file protections/passwording also make huge demands on your server).

Maybe it’s time for a server upgrade?

Backend Access

Currently the TCPDF Bridge settings are limited to folks who can “manage options:” Administrators.

Access level can be filtered using the TCPDF Bridge ‘wptcpdfb_settings_manage_options’ hook. For example, you could add the following code to your functions.php file (or using the Code Snippets plugin if you can’t edit your functions.php file) to give access to the WordPress editor role:

function allow_my_editor_to_use_wptcpdfb( $capability ) {
    // you can edit $capability here; I’m just returning 'edit_pages' cuz that’s what an editor can do
    // https://wordpress.org/support/article/roles-and-capabilities/
    return 'edit_pages';
}
add_filter( 'wptcpdfb_settings_manage_options', 'allow_my_editor_to_use_wptcpdfb', 10, 1 );

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. It 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
tags.

Text alignment

Some HTML can be used in watermark content, so go ahead and experiment to see what you can get away with!

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 (bold) text.

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

This might also work:

<span style="text-align: center">center some <strong>bold text</strong></span>

In case you need it, RTL watermarking can be selected in the TCPDF Bridge settings by clicking a checkbox.

Barcodes

TCPDF Bridge includes a generator for adding custom barcodes to your PDFs on-the-fly before they are delivered to your users. Your user clicks a download link, and during the download process a code is added to pages of your PDF. If your user provided information (name, email) or is logged in, the barcode can include this information using shortcodes. You can also manually generate barcodes for PDFs on the administration side of WordPress. Learn a little more about the types of barcodes available when using TCPDF.

In your watermarking settings, you will find a checkbox which will switch from regular text/image watermarking, to barcode watermarking:

WP TCPDF Bridge barcode settings panel screenshot

Here you can see the checkbox has been checked, revealing a barcode settings panel. The panel will vary slightly depending if you’ve selected a 1D or 2D style barcode.

Your barcode will inherit its content, position, and color from the main watermarking settings. If your content (after shortcodes are replaced for actual content) does not conform to the barcode standard you’ve chosen, you will get the error:

Error in 1D/2D barcode string

In other words, if your barcode type requires numbers, use numbers. If it doesn’t allow UPPERCASE, don’t use uppercase. Each barcode type has its own unique requirements (and you probably know what those are for the barcode you need).

Using Templates

We recommend always using child themes to make edits to your theme. Otherwise, if you edit your parent theme (the files you downloaded from WordPress or purchased online) next time you update, your changes will disappear. They will be overridden. Poof! Gone. Using child themes to make edits avoids this trouble.

If you would like to change the structure or appearance of TCPDF Bridge forms and modals, and there are no hooks available to make the changes you want in PHP, you can use the TCPDF Bridge templating system. There are pitfalls to overriding templates, but sometimes it is unavoidable.

  1. You will need to create a folder called wptcpdfb in your child theme folder.
  2. Move any overwritten plugin template files into this wp-content/child-theme/wptcpdfb folder

Fairly simple, especially if you know some HTML/PHP. Any code changes you’ve made to that new template file inside the child-theme will be visible online.

For example, if you wanted to alter and style the modal/popup, the template you’d look at is in the wp-tcpdf-bridge/templates/wptcpdfb folder, called modal.php. Copy and move that file to your child-theme-whatever-its-called/wptcpdfb/ folder that you created in step 1 above. At that point you can make changes to the modal. You will want to make sure you keep the basic Bootstrap modal syntax intact, so that the modal continues to function. Changing modal form input names is also strongly discouraged, as it will break the plugin’s function. If you have suggestion for DOM items or CSS tags which could help everyone and prevent you from templating, please get in touch.

Keep reading below (under “hooks” ↓) about how to change text using hooks. As suggested above, editing templates works, but is less future-forward than using hooks. This means that if a parent template is updated/changed by the developer for better function or to fix an issue, and you don’t have time to also fix your template override to match the update, you might have problems.

Hooks

This plugin comes with a lot of filter and action hooks, especially for TCPDF use. If the plugin doesn’t do exactly what you need, chances are there is already a hook for that. Dig in!

A few hooks closer to the surface have to do with front end form output.

If you prefer to not use form labels and instead show placeholders, you can use the following filter hooks to change the output from ” to the text of your choice:

‘wptcpdfb_fn_placeholder’
‘wptcpdfb_ln_placeholder’
‘wptcpdfb_email_placeholder’

Example use:

add_filter( 'wptcpdfb_email_placeholder', function( $placeholder ) {
    return 'Your Email';
});

You could then hide the form labels using CSS, like this (why like this?):

.wptcpdfb_modal label {
    height:1px;
    left:-10000px;
    overflow:hidden;
    position:absolute;
    top:auto;
    width:1px
}

Other Topic?

WP TCPDF Bridge is built with TCPDF, just like EDDiMark and WaterWoo (also sold here). We recommend you review their documentation and blog posts about them, as they do have overlap in function.

Little Package Web