WaterWoo Documentation

Why Waterwoo?

WooCommerce is a great plugin to use for selling your PDFs because Woo collects more information from customers during checkout than other ecommerce options, even when sharing free files. WooCommerce allows you to collect name, email address, phone number, business name, and more. WaterWoo allows you to use customer information to personalize each PDF, visibly or invisibly.

Compare WaterWoo to the other PDF watermarking plugins available.

Other plugins limit watermark placement to specific quadrants of the page, but WaterWoo will watermark anywhere on the page, millimeter by millimeter – and with two separate watermarks if desired.

WaterWoo has a ton more leverage in robust yet easy-to-understand backend settings. These settings will help you get your files watermarked exactly how you need them – on a per file basis. You can have a different watermark – different text, different font, different colors, different placement and rotation – for every file in your catalog should you desire. It’s still a lightweight plugin that can operate quickly on most file sizes. You won’t believe it’s not magic.

A little about WaterWoo PDF Premium works

WaterWoo does its magic using the third party open-source TCPDF and TCPDI libraries. TCPDI parses the existing PDF (assuming it is parse-able/syntactic/uncorrupted AND unencrypted) into PHP memory, then TCPDF applies your watermark. Understanding a little about how TCPDI and TCPDF come into play, and using PHP memory wisely, might help you to create the most effective and efficient watermarks. Sometimes the most effective watermark is just a line of invisible text, noting your purchaser’s name and email!

Installation

With your purchase you will receive a download link for the premium (paid) version of this plugin. The link will be on your order confirmation webpage and in your receipt email. If at any time you need a fresh copy of WaterWoo PDF Premium, you can also log into your account at web.little-package.com/account. Open the .ZIP file package to find the “waterwoo-pdf-premium/” plugin folder.

  1. Upload the entire “waterwoo-pdf-premium” folder to the WordPress “/wp-content/plugins/” directory. Alternatively you can go to Plugins -> Add New, click “Upload Plugin” and upload the ZIP file.
  2. Activate the plugin through the “Plugins” menu in WordPress. If the free version of the plugin is still active, deactivate the free version.
  3. Visit WooCommerce->Settings->Watermark tab to set your plugin preferences.
    Additional settings panels are found in each product editor screen, on the same screen panel where you edit product price and inventory.
  4. Please test your watermarking before going live to make sure it works and looks great!

If you were using the free version of the plugin, please deactivate it. It’s recommended you also delete inactive plugins. Your settings will be saved and applied toward the paid version. The two are entirely different and separate plugins and should not be active on your WP installation at the same time.

Recommendations

Make sure to test your watermarking before going live! Each PDF is different under the hood and some may not work. 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.

PHP Version

WaterWoo PDF recommends you run PHP version 7.4 or higher. WaterWoo PDF is PHP version 8.2 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 WaterWoo demands much more efficiently! Upgrading your PHP is 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. 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.

If you have large PDFs, complex watermarks (HTML, images, fonts, encryption) and/or heavy customer traffic, you may also want to upgrade your hosting so you can use more CPUs if necessary. Trying to run this plugin on cheap shared hosting won’t always work out. Keep in mind that your hosting plan needs to be robust enough to support the memory and bandwidth necessary to fulfill PDF manipulation requests in PHP memory. Try these suggestions to tune for performance. (FYI Thai characters are already disabled in Waterwoo.) Keep your watermarks simple. Avoid HTML and images if possible, use base fonts, and remember that file protections/passwording also make huge demands on your server.

Tips for upgrading from the free version

It’s easy. Replaces an installation of the free version with the Premium (paid) version plugin files. Deactivate the free version of the plugin before using the Premiumversion. The Premium version uses any basic watermarking settings you have saved from the free version, and adds many new options.

You will find general settings in the same place as you did with the free version, but now you will also have access to per-product watermarking options under each product editing page. Look for those options in the same WordPress “metabox” where you’d normally find Inventory, Shipping, and Attributes/Variations settings.

Managing License Keys

Once WaterWoo PDF Premium is installed and activated on your site, head over to the WordPress menu -> Settings -> WaterWoo License. The license key does not have to be activated for your plugin to function. 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.

  1. Enter your license key
  2. Click the “Activate License” button to activate your license. OR, 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 (web.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.*

Can I get an invoice for my plugin purchase?

Yes! You can easily print your own invoice, including adding a a VAT/GST number by going to “your account page.” After editing your profile how you would like it to show on the invoice, click on “Purchases,” and view the order. 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.

Features

How do I test my watermark?

The Premium version of Waterwoo allows on-the-fly manual creation of watermarked PDFs on the settings page. Look for the Test Run feature at the bottom of the page under WooCommerce -> Settings -> Watermark, fill in the settings you want, and go!

Two tricky alternatives:

  1. Create a coupon in your Woocommerce shop to allow 100% free purchases. Don’t share this coupon code with anyone! Test your watermark by purchasing PDFs from your shop using the coupon.
  2. Create a free product but make it hidden, or better yet make it a private post (visible only to you).

Once you have purchased the test file once, you can demo your changes from your “https://mywebsite.com/my-account/downloads” screen as long as your download privileges remain valid. You can also re-send purchase emails in order to test from the email download links.

Margins

Waterwoo comes with default margins to keep your watermark inside an area on the page. These are 10mm left/right, and 10mm top/bottom.

If you would like to remove this restriction, set the margins to 0. Margins keep your mark within bounds. If you would like to move things in on the page, maybe use the X/Y adjusters.

The XY fine tuners also move things on the page; however, they cannot remove the margins. So a margins setting was added primarily for those people wanting to remove the margins or keep content within bounds.

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, WaterWoo 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] [ORDERNUMBER] [PRODUCTNAME]. Using one of these in your overlay or footer text will cause the shortcode to be replaced by the customer data during checkout and watermarking.

Keep in mind if you do not solicit the “businessname” field or make it mandatory, and the customer leaves it blank, the [businessname] shortcode will leave an empty spot in the watermark if you use it. The other simple shortcode fields are guaranteed to come through unless you (or your theme) changes that.

Here is more information about how to use your theme’s function.php file to alter WooCommerce core fields

Here is an example of creating your own WaterWoo shortcode for checkout field data.

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.

Number Sold [PRODUCT-#] Shortcodes

To add in the quantity/number of a product purchased, you can use the [PRODUCT-###] shortcode. The # in this shortcode becomes a wildcard, where # represents the WooCommerce product ID (but you don’t have to fuss with finding the product ID). The shortcode [PRODUCT-###] will be replaced by the number/qty of product purchased of the file downloaded.

This shortcode will not work with the testing feature.

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.

{OPAC-0}This is invisible text{/OPAC}

“This is invisible text” will be 0% opacity (transparent).

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.

Custom Shortcodes

If you would like to create a custom shortcode to display dynamic output, that can usually be done using filter hooks included in WaterWoo. The filter hooks to use are ‘wwpdf_filter_overlay’ and ‘wwpdf_filter_footer’ and the parameters they pass are $order_id and $product_id. So unless you are adding static content, it’s necessary that you have collected and have reliable access to output from the database. The parameters $order_id and $product_id, related directly to the download being requested, should allow you to fetch all sorts of related data. A simple example looks like:

function fetch_woo_order_data_for_shortcode( $input, $order_id, $product_id ) {

    // first could get the order object from the order id:
    // you can get a lot of info from the order object ($order in this case)
    $order = wc_get_order( $order_id );
    if ( ! $order ! is_a( $order, 'WC_Order' ) ) {
         return $input; // make sure to return $input if something goes wrong
    }
    // or maybe you want to get a product object from the product id:
    $product = wc_get_product( $product_id );
    if ( ! $product || ! is_a( $product, 'WC_Product' ) ) {
        return $input; // make sure to return $input if something goes wrong
    }

    // Examples of getting some order data from the order object, lots of data can be accessed
    // More info: https://stackoverflow.com/a/44708344
    $order_data = $order-&amp;amp;amp;gt;get_data();
    $order_total = $order_data['total']; // getting the order total data

    // More info on grabbing product data: https://www.businessbloomer.com/woocommerce-easily-get-product-info-title-sku-desc-product-object/

    // ...find and sanitize the data you seek
    $the_data_you_seek = 'woohoo I found it!'; // replace with actual value

    // if/when we find [YOUR_CUSTOM_WATERWOO_SHORTCODE] in a watermark, replace it with the $the_data_you_seek
    $input = preg_replace( '/\\[YOUR_CUSTOM_WATERWOO_SHORTCODE\\]/', $the_data_you_seek, $input );

    return $input;
}
add_filter( 'wwpdf_filter_overlay', 'fetch_woo_order_data_for_shortcode', 10, 3 ); // for filtering the overlay watermark
add_filter( 'wwpdf_filter_footer', 'fetch_woo_order_data_for_shortcode', 10, 3 ); // for filtering the footer watermark

Read more information about custom shortcodes for Waterwoo PDF watermarking, and check out an example of a shortcode for Brazilian CPF checkout fields. This custom code would go in your child theme functions.php file or be built in to your custom plugin.

If this is foreign to you, that’s OK. It should be straightforward and simple to implement to a developer who is familiar with WordPress and PHP. Don’t have a developer? Find one! Developers are like car mechanics or plumbers, specialists who are ready to help you out of a pinch. Can’t find one? Get in touch and we will look at your project and offer a flat-rate quote for your project (usually under $100).

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 (bold) 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 text</strong></span>

If this isn’t working for you, please make sure your code is UTF-8. Curly quotes will not work in PHP code!

Hooks (actions/filters)

Hooks it possible to adjust WaterWoo to carry out some of your specific needs. We will not be able to write action and filter function code for you. The hooks were placed for your developer’s convenience. We do not support hook use unless you find a bug or need arguments added.

If you are unfamiliar with how to edit your [child] theme functions.php file to add hooked functions to your website, you should check out the Code Snippets plugin.

‘ wwpdf_add_custom_font ‘ and ‘ wwpdf_font_decode ‘ filters, more here

‘ wwpdf_download_file_name ‘ filter, you’ll know it when you need it… more here

‘ wwpdf_add_barcode ‘ filter for maybe adding 1D and 2D barcodes and QR codes to PDFs

‘ wwpdf_file_cleanup ‘ action to clean up residual files on the server if using Redirect download method. More here.

‘ wwpdf_do_cleanup ‘ filter to maybe prevent cleanup of files served via forced or xsendfile download. More here.

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

‘ wwpdf_filter_overlay’ and ‘ wwpdf_filter_footer ‘ filters to allow for manipulation of watermarks. With these hooks you can possibly add in your own custom coded shortcodes.

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

‘ wwpdf_set_password ‘ filter for creating alternate passwords. More here.

‘ wwpdf_set_permissions ‘ filter hook for adjusting which permissions are set in file encryption. Learn more below.

Watermarking using a JPG/PNG file

Since WaterWoo allows quite a bit of HTML in your watermark content, you can go ahead and use <img> tags to put an image on your PDF. Transparent images make great watermarks, just make sure to use a small image file (smush those bytes)! Image width and height must be indicated when using an <img> tag in your watermark input. Try something like this:

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

<img src="https://url.to/your/image.gif" width="100" height="250" />

These are just examples. Replace with the correct image location and size, and save in your overlay or footer watermark content settings.

Watermark Specific Pages

function watermark_specific_pages( $bool, $pagenum, $pagecount, $pdf ) {

    // Tell it which pages NOT to watermark
    // Here I'm saying don't watermark pages 2, 3, 4, 6, 7, 8, 10, or 20
    if ( in_array( $pagenum, [ 2,3,4,6,7,8,10,20 ] ) {
        return true;
    }
    return false;

}
add_filter( 'wwpdf_dont_watermark_this_page', 'watermark_specific_pages', 10, 4 );

If you want this to apply to a specific PDF, you can use $pdf checks (version 3.5 of WaterWoo or newer). This is up to your developer to code. Don’t worry too much – this is going to all become much easier in a future iteration of WaterWoo!

Fonts (maybe adding)

You can add fonts to the plugin with a click. All you need is a TTF (TrueType Font) file of your desired font. Adding a font subsetted correctly for the needs of your WooCommerce shops and/or PDFs can not only make your PDFs easier to read, but can save a lot of PHP memory, too. Learn more about adding your special font to WaterWoo.

Another way to add fonts to TCPDF (Programmatically)

To run watermarking with your custom font, you can run the filter “wwpdf_add_custom_font”. Font must be added to TCPDF first using addTTFfont(). 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. This is in development and not a supported feature.

add_filter( 'wwpdf_add_custom_font', ‘my_custom_font_name’, 10, 1 );
function my_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 WaterWoo 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 ‘wwpdf_font_decode’ might need to be used to add html_entity_decode() around your overlay or footer input.

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. Typing the word “email” into the password field in WaterWoo settings will force the end user to open the PDF with the buyer’s email address. The word email works magic in this case, but must be lowercase and without punctuation. Note: If you type the shortcode “[EMAIL]” into the password field in WaterWoo settings, the password to open the PDF will be [EMAIL] (the shortcode does not work magic in the password field).

Keep your sanity — here are some ideas to consider before passwording your PDFs using WaterWoo.

Alternatively the ‘wwpdf_set_password’ hook can be used to set a different type of password if desired, see below.

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 and here.

We 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!

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

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

Passwords

Here’s an example of how to use the ‘wwpdf_set_password’ filter hook to set up your own password. In this example it uses the customer’s billing phone. It would be important in this instance to require a phone number from your customers!

add_filter( 'wwpdf_set_password', 'my_own_password_function', 10, 2 );
function my_own_password_function( $password, $order_id ) {
    $order = wc_get_order( $order_id );
    $order_data = $order-&amp;amp;amp;gt;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
    return $password;
}

Learn more about order/customer data that would be accessible using the $order_id argument provided in this hook.

Barcodes (maybe adding)

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

add_filter( 'wwpdf_add_barcode', 'my_barcode_function', 10, 2 );
function my_barcode_function( $barcode_array, $order_id ) {
    // if desired you could bring in order information using the $order_id variable
    // otherwise just return a 2D QRCODE that says &amp;amp;amp;quot;Test Barcode&amp;amp;amp;quot; when scanned, like this:
    return array( '2D', 'Test Barcode', 'QRCODE', 100, 230, 30, 30 );
}

The ‘my_barcode_function’ function returns an array used by the WaterWoo PDF Premium plugin to create a barcode.

  1. The first argument accepts either ‘1D’ or ‘2D’.
  2. The second argument will be your barcode contents. The string must conform to string type expected by the type of barcode (third argument)
  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) from the top of the page.
  6. The sixth argument is the width of the barcode in millimeters.
  7. The seventh argument is height of the barcode in millimeters.
  8. The remaining arguments are optional, and vary between 1D and 2D. For 1D, they are: $xres=null, $style=array(), $align=''. For 2D, they are: $style=array(), $align='', $distort=false. These defaults are set for you,but you can override them using the `wwpdf_add_barcode` filter hook.

The WooCommerce order ID is passed as a parameter to `wwpdf_add_barcode` filter hook so you can include some order data in your barcode.

If you are unfamiliar with how to edit your [child] theme functions.php file to add hooked functions to your website, try using the Code Snippets plugin, which makes it simple to add PHP code like the examples on this page.

Read more about using this filter hook to add barcodes to your PDF.

What happens to files on the server…

If you choose the WooCommerce “Force” download method, the file is watermarked, download is forced, and the temporary file is deleted.

Otherwise, if you have chosen “Redirect” or “XSendFile” download method, the file is watermarked, the buyer is redirected to the temporary file, and the file remains in a temporary folder in a WordPress “/uploadds/waterwoo-pdf” folder. It is recommended you set up a cron to keep this folder empty.

File Name Change

If you would maybe like your manipulated PDF to have a different filename, that can be done. Maybe customized with date and order number? Function my_custom_PDF_filename() would do this:

add_filter( 'wwpdf_download_file_name', 'my_custom_PDF_filename', 10, 2 );
function my_custom_PDF_filename( $file_name, $order_number ) {
    // Alter the filename
    $file_name = str_replace( '.pdf', '', $file_name ) . '_' . time() . '_' . $order_number . '.pdf';
    // Return the changed filename
    return $file_name;
}

This filter hook could also be used to customized your customer’s file download file name in other ways. That’s up to you and your developer.

If you find that your file name is unexpectedly changed on downloading, you might want to look into the unique string setting which WooCommerce turns on by default “for security.” WaterWoo will not change file names unless you write custom code.

Clean Up files after Download

The ‘wwpdf_do_cleanup’ filter will allow you to turn OFF file clean up for forced downloads:

add_filter( 'wwpdf_do_cleanup', __return_false );

Redirect and X-Accel-Redirect must have files on the server for the customer to fetch. Files are automatically stored to the WP uploads folder when using Redirect and X-Accel-Redirect. It’s recommended to set up a cron job to delete customized PDFs from the wp-content/uploads/waterwoo-pdf folder. To make this simple for yourself, use the WP Crontrol plugin, and add a PHP function like this on the schedule of your choice:

function wwpdf_file_cleanup() {

    // Bail if not in WordPress cron
	  if ( ! edd_doing_cron() ) {
	    return;
    }
    // this function assumes your watermarked PDFs are going to this folder:
    $dir = WP_CONTENT_DIR . '/uploads/waterwoo-pdf/';
    wwpdf_scheduled_cleanup( $dir );

}

function wwpdf_scheduled_cleanup( $dir ) {    

    // get straight to business deleting only PDFs
    // simple. no recursive sub-directory deletion here
    foreach( glob( $dir . &amp;amp;amp;quot;/*.[pP][dD][fF]&amp;amp;amp;quot; ) as $file ) {
        if ( is_file( $file ) ) {
            @unlink( $file );
        }
    }

}
wwpdf_file_cleanup();

Disclaimer: You’ll want to carefully review this function before using it to make sure it is suitable for your use. Things might have changed since we posted it and we cannot guarantee how or if it will perform.

Amazon S3 Hosted Files

If using WooTheme’s S3 plugin, you must create a SHORTCODE to use as the product file path. Documentation for how to set up a bucket, S3 file, and shortcode are here.

A shortcode will look like this:

[amazon_s3 bucket=MyBucketName object=MyFileName.ext]

Noted June 2018: WooCommerce’s Amazon S3 plugin does not work to deliver files if your bucket name is a domain name (e.g. “mydomain.com”) or has a period (“.”), dash (“-“), or space in it.

Dropbox Hosted Files

To set up WaterWoo to work with Dropbox, you will need the separate Woocommerce Dropbox Plugin. Please follow its installation instructions to set it up. Also please contact its developers with any questions about its setup. Once that plugin is set up correctly, you will be able to easily select PDF files from Dropbox in your product editor.

Troubleshooting

If the plugin doesn’t seem to work, here are some basic first things to try:

  1. First make sure you have checked the box at the top of your settings page (Woocommerce -> Settings -> Watermark) so that watermarking is enabled! If you’re not using Global watermarking settings, make sure watermarking is enabled at the product level.If you’ve checked “Turn on Watermarking” at the individual product level, that’s a global setting override. Make sure you then set an individual watermark! Checking this box and leaving the overlay/footer watermarks fields blank below, will mean you get a blank watermark.
  2. Make sure your uploaded PDF file is not already encrypted/passworded. WaterWoo needs full access to the PDF guts to do its magic!
  3. If your watermark contains special characters, please try one of the included fonts other than Helvetica, Courier, or Times Roman. Some font files are subsetted to include more international characters, like those seen in French and Polish, for example. Learn more about this.
  4. 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.
  5. Some PDF files are mildly corrupted un-readable by the parser. Please try watermarking another PDF to rule out this problem. Re-saving a broken PDF with Apple Preview (“Export as PDF”) or Adobe Acrobat can sometimes help clean them up so WaterWoo can do its job. If we find that your PDF is the problem and not WaterWoo, it is up to you to repair/re-create your PDF.

I am getting an error message

Ack! That’s horrible! Here are what the most common error messages mean:

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 filename uses unsafe characters like spaces in the PDF file name. Replace spaces with dashes or underscores or remove them.

It’s also possible the PDF isn’t located where the computer thinks it is. Double check your file paths, and that the PDF is where you think you put it.

Warning: fopen(): remote host file access not supported

If you get this message it’s because you’re trying to store your PDF on another host (another domain). Your PDF needs to be hosted on the same URL as your WooCommerce installation (unless you’re using the Woo Amazon S3 extension and hosting your PDF on S3 or WooCommerce Dropbox extension and have your file at Dropbox).

Fatal error: Allowed memory size of n bytes exhausted

If you get this error, please refer to “Recommendations” in the plugin documentation. TL;DR: start by upgrading your PHP installation and increasing your PHP memory limits. Simplify your watermark by removing HTML, images, fonts, and/or encryption. Remember: WaterWoo is essentially a bridge between the open source TCPDI/TCPDF libraries and WooCommerce. TCPDF makes a huge demand on the server after TCPDI parses the entire PDF into memory, in order to spit the PDF back out with the watermark added. If you have a large PDF and a complex watermark to add to it, and are expecting affordable, un-managed shared hosting to reliably process the file on potentially heavy customer demand, you’re rolling the dice.

TCPDF_PARSER ERROR: decodeFilterFlateDecode: invalid code
If you get this error, it is likely because you are trying to manipulate a PDF which has already been passworded or protected. PDFs must be unlocked with full user permissions in order to be parsed by TCPDI and watermarked.

If you’re getting a different error message on the screen, please let us know right away! Use the information below about Error Logging in order to provide us information we need to help you. Everyone’s WordPress setup is different, so help us understand yours and how it might be interacting with our plugin.

Errors and Error Logging

If you are having troubles with WaterWoo (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. Read more 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.

WaterWoo Logs

WaterWoo PDF Premium also has its own built-in logs which will log errors more specific to the plugin. You can find the settings, and the logs by clicking links at the top of your WaterWoo settings page:

Where to find waterwoo log settings and logs

If these logs are turned on while you are experiencing watermarking troubles, they will likely pick up some more detailed information which will be helpful during troubleshooting. Cut and paste this information in an email to us!

Why doesn’t the first page get watermarked?

If your watermarking is skipping the first page, maybe the parser (TCPDI) is not reading that page as part of the document. Is it possible the cover page was added as an afterthought? TCPDF struggles with incremented PDFs.

The cover page must be reintegrated into the PDF source code, and often this can be done by removing it, adding it back in, and saving the file as a PDF.

I recommend using a PDF viewer such as Apple Preview to delete the cover page, save, then drag and drop the cover page back into place from another open version of the same file, then ‘Export as PDF’ to save it. This should help smooth out any problematic PDF syntax issues. Unfortunately we know of no other PDF reader (Windows or Mac) that can help the way Preview does for syntactically-incorrect PDFs.

Why does the watermark go off the page, create new pages, or change the box size?

Your watermark text string is too big or long for the page! TCPDF is a little dumb, and created a blank page 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 WaterWoo 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.

If you are using WaterWoo v3.0+ and 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.

My watermark isn’t English

The Helvetica, Times Roman and Courier fonts in this plugin arrive to you subsetted for English. If you want to use one of these fonts but need different subsetting, you would need to create those font files yourself (TTF) and use the font uploader in the plugin to add your custom-subsetted 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. Right to Left (RTL) watermarking is possible with WaterWoo.

A primary reason watermarks do not show up, or shows up as question marks or empty boxes, is when the watermark contains special characters but a font which doesn’t support those characters is in use. Learn more about using fonts.

Little Package Web