PDF Stamper Documentation

The following are recommendations for settings, and ideas for hooks to use for extending the function of PDF Stamper.

Setup

First of all, you should purchase SetaPDF Stamper.

Alternatively, a 14-day evaluation copy of SetaPDF Stamper can be used if your server has Ioncube installed, and the license file (.htSetaPDF-Stamper.icl) in place. Make sure to follow SetaSign’s instructions for how to install your license file if you are using the evaluation copy. This is a step many people skip in their hurry to set everything up with an evaluation copy. Ioncube must be active on your server and you must use the correct IonCube package to match your server’s current PHP version.

Note: an evaluation copy is not the same as a paid copy of SetaPDF Stamper. If you have upgraded to a paid copy, install those files on your server to replace the free copy. If you have paid SetaSign, you will no longer need the .icl file or Ioncube.

Installation instructions

The SetaPDF folder must be moved into the wp-content/uploads/woostamper folder OR your WordPress installation must include a call to the SetaPDF-Stamper autoload.php file. If the SetaPDF-Stamper is not included, the plugin will not do much, and certainly will not stamp. See more below:

  1. Install the PDF Stamper for WooCommerce plugin just like any other WordPress plugin, so that it shows in your WP plugins folder like this: https://yoursite.com/wp-content/plugins/woostamper-pdf Need help learning how to install plugins?
  2. purchase your SetaPDF-Stamper license or borrow an evaluation copy and download that software package.
  3. SetaPDF-Stamper requires PHP 5.6 minimum and these PHP extensions be running on your server.
  4. Unzip the SetaPDF-Stamper software package. The folder we need is nested inside the package, in the “library” folder.
  5. Install/upload the “SetaPDF” folder inside your /wp-content/uploads/woostamper folder. If the /wp-content/uploads/woostamper/ folder doesn’t exist, go ahead and create it. Please not this is inside the uploads folder, not the plugins folder.When you’ve uploaded the “SetaPDF” folder, you should see this file heirarchy: https://yoursite.com/wp-content/uploads/woostamper/SetaPDF/Autoload.php Alternatively, (advanced) you can include* SetaPDF-Stamper autoloader anywhere in your WP installation (optimally using the ‘plugins_loaded’ hook with a priority lower than 99), and that will also work.

The plugin will provide error messages indicating when SetaPDF-Stamper is not loaded correctly. One thing to make sure is all the SetaPDF files are loaded, files been transferred in UTF-8 not ASCII, and that no files have been corrupted/truncated in transfer. When in doubt, re-upload the files to your server.

You can also turn on WooStamper debugging in the WooStamper Log settings. WooStamper log output will be supplemented by information in your WordPress debug logs.

Setup

You’ll find settings in the WooCommerce -> Settings under the “WooStamper” tab. Please review the notes and tooltips on the PDF Stamper general settings page, as they reveal a lot of tips and background for each setting. Click small (?) icons on settings pages to see the tooltips.

Watermark Positioning

Seta allows for nine positions on the page: TOP MIDDLE BOTTOM as combined with LEFT CENTER RIGHT. Choose where you would like your watermark to essentially sit, and then you can fine-tune it by millimeter with the X and Y fine-tuners. Use font size and line height carefully to help keep your stamp from going off the page. The stamp text input field in the plugin settings accepts line breaks, just hit your enter key to apply a line break.

Simple Shortcodes

Simple shortcodes available are [FIRSTNAME] [LASTNAME] [BUSINESSNAME] [ADDRESS1] [ADDRESS2] [CITY] [STATE] [POSTCODE] [COUNTRY] [COUNTRYCODE] [EMAIL] [PHONE] [DATE] [TIMESTAMP] [ORDERNUMBER] [PRODUCTNAME]. Using one of these in your text will cause the shortcode to be replaced by the customer data during checkout and watermarking – if the data was collected.

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. Same with any other fields. Generally, simple shortcode fields should work unless you (or your theme or a plugin) change that by removing a field from checkout.

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

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.

Product Quantity Shortcodes

To add in the number of a product purchased, you can use the [PRODUCT-1234] shortcode, where 1234 is replaced with the numeral WooCommerce product ID. You can find the product ID listed underneath the product title on your main WooCommerce Products listing page (hover over the desired product title to see the ID), or by hovering over the product title and looking at the browser status bar (lower screen, look for the number after “post=”). This must be an item found in the cart in order to work, otherwise the shortcode comes up blank. This shortcode will not work with the testing feature.

However, a wildcard shortcode which uses hashes [PRODUCT-###] is much easier to use. No more need to match it up with the product that might be in the cart at some point. Try using [PRODUCT-###] as a shortcode. It will be replaced by the number purchased of the specific file downloaded.

Passwording, protections and encryption

Encryption must be turned on to allow for passwording and permissions, and will be applied on top of those features. The user password can be set to “email,” which will be replaced with the downloader’s email (if available, please make sure it is required before using this magical setting). Otherwise, set it ad lib, and it will be required the downloader enter it correctly in order to even view the file (they will be able to view metadata, by default, more on that below). Once they enter it correctly, they can view the file, but permissions might prevent them from doing certain things with the file, per your settings, such as copy or print.

The owner password is set arbitrarily by the plugin and you might want to change it to something more suited to yourself right away. The owner password not only opens a passworded PDF, but also removes all permissions blocks. Anyone with an owner password essentially becomes an “owner” of the file, meaning they can do pretty much anything to it. Careful with this.

Filter Hooks

All stamping occurs in the classes/woostamper-pdf-stamp.php and classes/woostamper-pdf-test-stamp.php (for testing) files. Inside WooStamper_PDF_Stamp->do_stamping(), the Seta class is called, and your PDF file is manipulated. Some filter hooks available for tinkering during that process are:

‘woostamper_custom_font‘ and ‘woostamper_filter_font‘ – These two filters will allow you to manipulate the font in use by Seta in the meantime before Stamper integrates a custom font uploader. As it stands only three fonts are available: Helvetica, Times, and Courier.

‘woostamper_filter_shortcodes‘ – for adjusting or maybe adding your own custom shortcode

‘woostamper_filter_rgb‘ – Maybe you want to recolor your stamp depending on the time or some other factor…

‘woostamper_change_timestamp‘ – This filter allows you to reset it to FALSE in order to NOT change the PDF modified time to the download/stamp time, which woostamper does by default. To use it:

add_filter( 'woostamper_change_timestamp', '__return_false' );

‘woostamper_increment‘ – This one is important and has to do with both performance and the security of your document. Please read carefully.

The PDF format offers a way to add changes to a document by simply appending the changes to the end of the file. This method is called incremental update and has the advantage that it is very fast, because only changed objects have to be written. This behavior is the default one, when calling the save()-method. Sadly it makes it easy to revert the document to the previous state by simply cutting the bytes of the last revision.

The parameter of the save()-method allows you to define that the document should be rebuild from scratch by resolving the complete object structure. Just pass SetaPDF_Core_Document::SAVE_METHOD_REWRITE to it. This task is very performance intensive, because the complete document have to be parsed, interpreted and rewritten.

Additionally it is possible to rewrite the whole document with all available objects. The benefit of this solution is that it will keep compressed object streams intact: SetaPDF_Core_Document::SAVE_METHOD_REWRITE_ALL. The disadvantage is that unused objects may be copied/written, too.

By default PDF Stamper uses incremental update, which is faster; however, less secure. If you have a system which has more memory and processing power, you can set the file to NOT increment by using the following code in a child theme functions.php file (or by using Code Snippets plugin):

add_filter( 'woostamper_increment', '__return_false' );

That would take your PDF further into FORTRESS-LAND.

‘woostamper_set_password‘ – A hook to allow you to fiddle with the set password.

‘woostamper_encrypt_metadata‘ – This is set to false by default to allow your metadata to be searched in your site implementation. To also encrypt the metadata, just set it to true like so:

add_filter( 'woostamper_encrypt_metadata', '__return_true' );

‘woostamper_allow_filling_forms‘ – Another encryption-related hook. By default woostamper encryption allows for form filling. To turn this off use the hook like so:

add_filter( 'woostamper_allow_filling_forms', '__return_false' );

Troubleshooting

Please refer to the setup instructions and review carefully. Oftentimes, problems are solved by making sure these instructions are followed. For example, sometimes people are using an evaluation copy of SetaPDF Stamper yet fail to make sure their host’s server has Ioncube installed. Other times, the SetaPDF Stamper library files have not been transferred correctly to their destination in the WordPress uploads directory.

If you are still having troubles with WooStamper, 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. When you email us for help, we will ask for this information.

Here’s two places to look:

1. WordPress Debugging

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 located in your root WordPress folder, 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 in a debug.log file. The file is updated every time a PHP notice or error occurs.

2. WooStamper Debugging Logs

WooStamper 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 WooStamper settings page:

Where to find WooStamper debug log settings and logs

If you are experiencing stamping troubles, please turn on logging. The logs will likely pick up some more detailed information which will be helpful during troubleshooting. Cut and paste this information in an email to us!

Little Package