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 with shortcodes

Manipulate PDFs 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.

Manipulate PDFs 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 set your watermarking options (font, color, text, placement, etc.), head over to the “Test Watermark” tab, choose a PDF, 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. You can flesh out some dynamic shortcodes from your overlay and footer watermark content with actual personal information, using the “Test Watermark” tab.

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!

Manipulate PDFs 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:

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)

Manual shortcodes

For those of you more comfortable creating shortcodes manually, the basic shortcode is

[wptcpdfb]

Here are the shortcode parameters:

Note: You will need the plugin version 2.4.0 or newer for this to work.

Some example shortcodes

In all these examples, the original PDF location is hidden from website users, and remains un-touched (no encryption or watermarking of the original).

Non-AJAX link prompt style and the WordPress media file ID of the PDF to mark. The file is delivered by X-Accel or as a forced download, more secure than the AJAX example below.

[wptcpdfb file_id="15472" style="non-ajax link" text="Download"]

AJAX link prompt style and a PDF file URL to encrypt/watermark. The URL is hidden from website users. A file location is revealed during redirect – but the file is encrypted and/or marked (not the original file.

[wptcpdfb url="https://domain.com/wp-content/uploads/unlimited/file.pdf" style="link" text="Download now"]

The following shortcode will show an inline form with first name, last name, and email fields where the email field is required.

[wptcpdfb url="https://www.domain.com/wp-content/uploads/2024/11/joy.pdf" style="form" text="Get the file now" fields="first, last, email" required="email" submit="Click for Joy!"]

If you are hard-coding a PHP template for your download website, you could perhaps insert the shortcode parameters dynamically in your template using the WP do_shortcode() function:

$url = "https://this.com/url/i/happen/to/have.pdf";
echo do_shortcode( '[wptcpdfb url="' . $url . '" style="form"]' );

Notes

Front-end watermarking stores watermarked files on your server. In order for TCPDF to deliver, the watermarked versions must be at least temporarily stored somewhere. 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. An htaccess file with ‘Options -Indexes’ directive is added at this level. Marked PDFs will be organized by date date(Ymd-His) and a 4-digit random number, so as to not be guess-able.

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

1. When the ‘wptcpdfb_temp_folder’ filter hook 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” setting in the main settings panel to have them removed automatically on a schedule. You can change the schedule 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.

Try these suggestions for tuning TCPDF to work smoothly on your server.

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:

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.

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
}

Filter the temp folder location

Out of the box, the temporary folder for marked PDFs is

'/wp-content/uploads/wp-tcpdf-bridge/' . time( 'Ymd-His' ) . rand( 1000,9999)

That creates a folder inside the /wp-tcpdf-bridge/ folder with a date then a dash then a four-digit random number. So, marked files will be organized by the second they were downloaded, and then to prevent overlaps, each has a random suffix. If you change this location, make sure to keep it so simultaneous downloads do not collide in the same folder. Use the ‘wptcpdfb_temp_folder’ filter like this:

function wptcpdfb_temp_folder( $folder ) {
    return WPTCPDFB_TMP_FILEPATH . date('Y') . DIRECTORY_SEPARATOR . date( 'm' ) . DIRECTORY_SEPARATOR . date( 'd' ) . hrtime( true ) . DIRECTORY_SEPARATOR;
}
add_filter( 'wptcpdfb_temp_folder', 'my_wptcpdfb_temp_folder', 10, 1 );

You can also redefine the WPTCPDFB_TMP_FILEPATH constant if you need to (define it before wp-tcpdf-bridge/wp-tcpdf-bridge.php is loaded.

The ultimate “hook”: using the WPTCPDF_Handler object

If you have good PHP skills or can hire a developer, watermarking can be implemented on your site in a headless way. Start by creating an instance of WPTCPDF_Handler, fleshing out a settings array, and work with that. Here is an example of what that might look like:

function wptcpdfb_wp_loaded() {
	$my_settings = [
		// page setup
		'start'         => 2, // start watermarking on page 2
		'end'           => 'last', // go to last page; otherwise specify a number
		'pages'         => 'all', // pick: all, first, last, odd, or even
		'rtl'           => '', // set to 'on' to use RTL
		'top_bottom'    => 0, // page margin
		'left_right'    => 0, // page margin
		'font'          => 'courier', // base fonts are helvetica, times, courier, etc. See get_font_selections()

		// First watermark position: "overlay"
		'o_content'     => '{OPAC-0.5}Watermark #1 with some HTML{/OPAC}',
		'o_is_barcode'  => '', // 'on' means the mark is a barcode
		'o_size'        => 24, // font size
		'o_color'       => '#cccccc', // Hex color
		'o_rotate'      => 30, // degrees rotation
		'o_x'           => 0, // move right in mm from left
		'o_y'           => 100, // move down in mm from top, or from bottom if negative integer

		// Second watermark position: "footer"
		'f_content'     => 'Licensed to [FIRSTNAME] [LASTNAME], [EMAIL]',
		'f_is_barcode'  => '', // 'on' means the mark is a barcode
		'f_size'        => 9, // font size
		'f_color'       => '#000000', // Hex color
		'f_rotate'      => 0, // degrees rotation
		'f_x'           => 0, // move right in mm from left
		'f_y'           => -10, // move down in mm from top, or from bottom if negative integer

		// Protection
		'download_type' => 'force', // force, xsendfile, or redirect
		'encrypt'       => 4, // 4 = none. 1 = RSA 40 bit. 2 = RSA 128 bit. 3 = AES 128 bit. 5 = AES 256 bit
		'pwd'           => '', // string
		'pwd_owner'     => null, // string, recommend leaving this alone unless you're sure what you are doing
		'unlock'        => '', // 'on' activates this. Again, leave alone unless you know what you are doing
		'failure'       => '', // yes or no. 'yes' means file will be delivered if watermarking fails
		'permissions'   => [], // Array of any of the following: print, copy, modify, annot, assemble, print-high, fill-forms, extract. Adding a permission to this list actually removes it.
	];

	// Instantiate the WPTCPDFB_Handler class
	$wpptdpcdfb     = new LittlePackage\WPTCPDFBridge\Classes\WPTCPDFB_Handler;
	$wpptdpcdfb->set_settings( $my_settings );
	$wpptdpcdfb->settings = $wpptdpcdfb->prepare_watermark_content( $wpptdpcdfb->settings );
	$requested_file = 'http://www.mywebsite.com/wp-content/uploads/2024/11/technical-file.pdf';
	$file_name      = 'technical-file.pdf'; // File name for the marked file (might be same as original)

	// Send for watermarking, returns file location
	$watermarked_file = $wpptdpcdfb->apply_watermark( $requested_file, $file_name , $wpptdpcdfb->settings, false );

	// Do something with the $watermarked file, a string marking the location of the marked file
	// die( $watermarked_file );

}
add_action( 'wp_loaded', 'wptcpdfb_wp_loaded', 100 );

Note: You will need the plugin version 2.4.0 or newer for this to work.

In another example, you could use an existing hook in your e-commerce solution to adjust the file path. Many WordPress ecommerce plugins include filter hooks for manipulating the file path just before a download. Let’s try it with Download Monitor:

function watermark_dlm_file_path( $file_path, $remote_file, $download ) {

	if ( $remote_file ) {
		// Here you will need to write some code to fetch the remote file so it can be manipulated on this server
	}
	// Instantiate the WPTCPDFB_Handler class
	$wpptdpcdfb = new LittlePackage\WPTCPDFBridge\Classes\WPTCPDFB_Handler;
	// You'll need to flesh out this array, like in the example above
	$wpptdpcdfb->set_settings( [] );
	$wpptdpcdfb->settings = $wpptdpcdfb->prepare_watermark_content( $wpptdpcdfb->settings );

	$file_name = strtok( wp_basename( $file_path ) ); // File name for the marked file (might be same as original)

	// Send for watermarking, returns file location (might need to be adjusted as URL / absolute path before returning
	return $wpptdpcdfb->apply_watermark( $file_path, $file_name , $wpptdpcdfb->settings, false );

}
add_action( 'dlm_file_path', 'watermark_dlm_file_path', 50, 3 );

Note: You will need the plugin version 2.4.0 or newer for this to work.

	// An example of barcode settings for each watermark position if barcode is ON, see TCPDF documentation for how to adjust this
	// Also, more here: https://www.little-package.com/blog/2020/06/printing-a-barcode-or-qr-code-on-a-pdf
	if ( 'on' === $settings['o_is_barcode'] ) ) { // "overlay" position

		$settings['o_barcode_type'] = 'QRCODE';
		$settings['o_barcode_417_params'] = [];
		$settings['o_barcode_width'] = 100;
		$settings['o_barcode_height'] = 100;
		$settings['o_barcode_small_bar_width'] = 1.4;
		$settings['o_barcode_style'] = [];
		$settings['o_barcode_align'] = 'N';
		$settings['o_barcode_distort'] = false;
	}

	if ( 'on' === $settings['f_is_barcode'] ) ) { // "footer" position

		$settings['f_barcode_type'] = 'EAN';
		$settings['f_barcode_417_params'] = [];
		$settings['f_barcode_width'] = 100;
		$settings['f_barcode_height'] = 100;
		$settings['f_barcode_small_bar_width'] = 1.4;
		$settings['f_barcode_style'] = [];
		$settings['f_barcode_align'] = 'N';
		$settings['f_barcode_distort'] = false;
	}

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.