Building custom automated PDF financial reports and invoices for WooCommerce using native TCP printing streams
Understanding the Core Problem: WooCommerce PDF Generation Limitations
WooCommerce, while powerful, often relies on third-party plugins for robust PDF invoice and report generation. These plugins, while convenient, can introduce overhead, licensing costs, and sometimes a lack of granular control. For developers needing highly customized, dynamically generated financial documents directly integrated with WooCommerce’s order data, a native approach leveraging PHP’s built-in capabilities and direct TCP printing streams offers a more flexible and performant solution. This approach bypasses the typical HTML-to-PDF conversion bottlenecks and allows for direct manipulation of print data, ideal for scenarios requiring specific formatting or integration with legacy printing systems.
Leveraging PHP’s TCPDF Library for PDF Generation
The cornerstone of our native PDF generation will be the TCPDF library. While not strictly “native” to PHP core, it’s a widely adopted, mature, and feature-rich library that can be easily integrated into a WordPress plugin. It allows for direct generation of PDF documents without relying on external services or complex HTML rendering engines. We’ll focus on generating invoices and order reports.
First, ensure TCPDF is available. The most straightforward way within a WordPress plugin is to include it directly. You can download TCPDF from its official website or use Composer if your plugin development workflow supports it.
Plugin Structure and TCPDF Integration
Let’s outline a basic plugin structure. Assume your plugin is located at wp-content/plugins/my-custom-reports/.
my-custom-reports.php(Main plugin file)includes/class-my-custom-reports-pdf.php(TCPDF wrapper class)includes/class-my-custom-reports-admin.php(Admin interface for generating reports)
In your main plugin file (my-custom-reports.php), you’ll include the TCPDF library. If you’ve downloaded it manually, place the tcpdf directory within your plugin’s root or an includes sub-directory and adjust the path accordingly.
my-custom-reports.php (Main Plugin File)
This file handles plugin activation, deactivation, and includes necessary files.
<?php
/**
* Plugin Name: My Custom WooCommerce Reports
* Description: Generates custom PDF invoices and reports for WooCommerce orders.
* Version: 1.0.0
* Author: Your Name
* Author URI: Your Website
* Text Domain: my-custom-reports
* WC requires at least: 3.0
* WC tested up to: 7.9
*/
if ( ! defined( 'ABSPATH' ) ) {
exit; // Exit if accessed directly.
}
// Define plugin constants
define( 'MY_CUSTOM_REPORTS_VERSION', '1.0.0' );
define( 'MY_CUSTOM_REPORTS_PLUGIN_DIR', plugin_dir_path( __FILE__ ) );
define( 'MY_CUSTOM_REPORTS_PLUGIN_URL', plugin_dir_url( __FILE__ ) );
// Include TCPDF library
// Adjust path if TCPDF is located elsewhere (e.g., in vendor/tcpdf/)
require_once MY_CUSTOM_REPORTS_PLUGIN_DIR . 'tcpdf/tcpdf.php';
// Include core classes
require_once MY_CUSTOM_REPORTS_PLUGIN_DIR . 'includes/class-my-custom-reports-pdf.php';
require_once MY_CUSTOM_REPORTS_PLUGIN_DIR . 'includes/class-my-custom-reports-admin.php';
/**
* Initialize the plugin.
*/
function my_custom_reports_init() {
new My_Custom_Reports_Admin();
new My_Custom_Reports_PDF();
}
add_action( 'plugins_loaded', 'my_custom_reports_init' );
/**
* Add settings link on plugin page.
*/
function my_custom_reports_add_settings_link( $links ) {
$settings_link = '<a href="admin.php?page=my-custom-reports-settings">' . __( 'Settings', 'my-custom-reports' ) . '</a>';
array_unshift( $links, $settings_link );
return $links;
}
$plugin_basename = plugin_basename( __FILE__ );
add_filter( "plugin_action_links_$plugin_basename", 'my_custom_reports_add_settings_link' );
/**
* Load plugin textdomain for translation.
*/
function my_custom_reports_load_textdomain() {
load_plugin_textdomain( 'my-custom-reports', false, dirname( plugin_basename( __FILE__ ) ) . '/languages/' );
}
add_action( 'plugins_loaded', 'my_custom_reports_load_textdomain' );
Creating a TCPDF Wrapper Class
This class will encapsulate the PDF generation logic, making it reusable and cleaner. We’ll create a method for generating an invoice.
includes/class-my-custom-reports-pdf.php
<?php
if ( ! defined( 'ABSPATH' ) ) {
exit; // Exit if accessed directly.
}
/**
* Class My_Custom_Reports_PDF
*
* Handles PDF generation using TCPDF.
*/
class My_Custom_Reports_PDF extends TCPDF {
/**
* Header for the PDF document.
* Overrides the default TCPDF header.
*/
public function Header() {
// Logo
$logo_path = WP_CONTENT_DIR . '/uploads/your-company-logo.png'; // Replace with actual logo path
if ( file_exists( $logo_path ) ) {
$this->Image( $logo_path, 10, 10, 30, '', '', '', 'T', false, 300, '', false, false, 0, false, false, false );
}
// Company Name and Address
$this->SetFont( 'helvetica', 'B', 12 );
$this->SetXY( 50, 15 ); // Adjust position as needed
$this->Cell( 0, 10, get_bloginfo( 'name' ), 0, false, 'L', 0, '', 0, false, 'M', 'M' );
$this->SetFont( 'helvetica', '', 9 );
$this->SetXY( 50, 22 );
$this->MultiCell( 0, 5, 'Your Company Address Line 1' . "\n" . 'Your Company Address Line 2' . "\n" . 'Your City, Postal Code', 0, 'L', false, 1, '', '', true );
// Invoice Title
$this->SetFont( 'helvetica', 'B', 20 );
$this->SetXY( 10, 40 ); // Adjust position
$this->Cell( 0, 15, __( 'INVOICE', 'my-custom-reports' ), 0, false, 'C', 0, '', 0, false, 'M', 'M' );
}
/**
* Footer for the PDF document.
* Overrides the default TCPDF footer.
*/
public function Footer() {
// Position at 15 mm from bottom
$this->SetY( -15 );
// Font
$this->SetFont( 'helvetica', 'I', 8 );
// Page number
$this->Cell( 0, 10, 'Page ' . $this->getAliasNumPage() . '/' . $this->getAliasNbPages(), 0, false, 'C', 0, '', 0, false, 'T', 'M' );
// Custom footer text
$this->SetXY( 10, -25 ); // Adjust position
$this->MultiCell( 0, 5, 'Thank you for your business!', 0, 'C', false, 1, '', '', true );
}
/**
* Generates a WooCommerce order invoice.
*
* @param int $order_id The WooCommerce order ID.
* @return string The PDF content as a string, or false on failure.
*/
public function generate_invoice( $order_id ) {
$order = wc_get_order( $order_id );
if ( ! $order ) {
return false;
}
// Set document information
$this->SetCreator( PDF_CREATOR );
$this->SetAuthor( get_bloginfo( 'name' ) );
$this->SetTitle( sprintf( __( 'Invoice for Order #%s', 'my-custom-reports' ), $order_id ) );
$this->SetSubject( __( 'Order Invoice', 'my-custom-reports' ) );
$this->SetKeywords( 'invoice, order, woocommerce' );
// Add a page
$this->AddPage();
// --- Invoice Details ---
// Billing & Shipping Address
$this->SetFont( 'helvetica', 'B', 10 );
$this->SetXY( 10, 70 ); // Adjust position
$this->Cell( 50, 10, __( 'Bill To:', 'my-custom-reports' ), 0, 1, 'L' );
$this->SetFont( 'helvetica', '', 9 );
$this->MultiCell( 80, 5, $order->get_formatted_billing_full_name() . "\n" . $order->get_billing_address_1() . "\n" . $order->get_billing_city() . ', ' . $order->get_billing_postcode() . "\n" . $order->get_billing_country(), 0, 'L', false, 1 );
$this->SetXY( 110, 70 ); // Adjust position
$this->Cell( 50, 10, __( 'Ship To:', 'my-custom-reports' ), 0, 1, 'L' );
$this->SetFont( 'helvetica', '', 9 );
$this->MultiCell( 80, 5, $order->get_formatted_shipping_full_name() . "\n" . $order->get_shipping_address_1() . "\n" . $order->get_shipping_city() . ', ' . $order->get_shipping_postcode() . "\n" . $order->get_shipping_country(), 0, 'L', false, 1 );
// Order Information
$this->SetXY( 10, 95 ); // Adjust position
$this->SetFont( 'helvetica', 'B', 10 );
$this->Cell( 40, 10, __( 'Order Number:', 'my-custom-reports' ), 0, 0, 'L' );
$this->SetFont( 'helvetica', '', 10 );
$this->Cell( 50, 10, '#' . $order_id, 0, 1, 'L' );
$this->SetX( 10 );
$this->SetFont( 'helvetica', 'B', 10 );
$this->Cell( 40, 10, __( 'Order Date:', 'my-custom-reports' ), 0, 0, 'L' );
$this->SetFont( 'helvetica', '', 10 );
$this->Cell( 50, 10, $order->get_date_created()->date( 'Y-m-d H:i:s' ), 0, 1, 'L' );
// --- Items Table ---
$this->Ln( 10 ); // Add some space
// Table Header
$this->SetFont( 'helvetica', 'B', 10 );
$this->SetFillColor( 220, 220, 220 ); // Light grey background
$this->Cell( 100, 10, __( 'Product', 'my-custom-reports' ), 1, 0, 'C', 1 );
$this->Cell( 20, 10, __( 'Qty', 'my-custom-reports' ), 1, 0, 'C', 1 );
$this->Cell( 30, 10, __( 'Price', 'my-custom-reports' ), 1, 0, 'C', 1 );
$this->Cell( 40, 10, __( 'Subtotal', 'my-custom-reports' ), 1, 1, 'C', 1 );
// Table Rows
$this->SetFont( 'helvetica', '', 9 );
foreach ( $order->get_items() as $item_id => $item ) {
$product_name = $item->get_name();
$quantity = $item->get_quantity();
$price = $item->get_total() / $quantity; // Unit price
$subtotal = $item->get_total();
// Add product name with variations if any
$product_name_display = $product_name;
if ( $item->get_variation_id() > 0 ) {
$product_name_display .= ' (' . wc_get_formatted_variation( $item->get_variation(), true ) . ')';
}
$this->Cell( 100, 10, $product_name_display, 1, 0, 'L', 0 );
$this->Cell( 20, 10, $quantity, 1, 0, 'C', 0 );
$this->Cell( 30, 10, wc_price( $price ), 1, 0, 'R', 0 );
$this->Cell( 40, 10, wc_price( $subtotal ), 1, 1, 'R', 0 );
}
// --- Totals ---
$this->Ln( 5 );
// Shipping
if ( $order->get_shipping_total() > 0 ) {
$this->SetX( 130 ); // Align to the right side of the table
$this->SetFont( 'helvetica', 'B', 9 );
$this->Cell( 40, 8, __( 'Shipping:', 'my-custom-reports' ), 0, 0, 'R' );
$this->SetFont( 'helvetica', '', 9 );
$this->Cell( 40, 8, wc_price( $order->get_shipping_total() ), 0, 1, 'R' );
}
// Taxes
if ( $order->get_total_tax() > 0 ) {
$this->SetX( 130 );
$this->SetFont( 'helvetica', 'B', 9 );
$this->Cell( 40, 8, __( 'Tax:', 'my-custom-reports' ), 0, 0, 'R' );
$this->SetFont( 'helvetica', '', 9 );
$this->Cell( 40, 8, wc_price( $order->get_total_tax() ), 0, 1, 'R' );
}
// Total
$this->SetX( 130 );
$this->SetFont( 'helvetica', 'B', 12 );
$this->Cell( 40, 10, __( 'Total:', 'my-custom-reports' ), 0, 0, 'R' );
$this->SetFont( 'helvetica', 'B', 12 );
$this->Cell( 40, 10, wc_price( $order->get_total() ), 0, 1, 'R' );
// --- Output ---
// Output PDF as a string. Use 'D' to force download, 'I' to view in browser, 'F' to save to file.
// For direct TCP printing, we'll eventually use 'S' and send raw data.
return $this->Output( 'invoice_' . $order_id . '.pdf', 'S' ); // 'S' returns PDF as string
}
/**
* Generates a WooCommerce order report.
* This is a simplified example. A real report would involve more complex data aggregation.
*
* @param array $order_ids Array of order IDs to include in the report.
* @return string The PDF content as a string, or false on failure.
*/
public function generate_order_report( $order_ids = array() ) {
// Set document information
$this->SetCreator( PDF_CREATOR );
$this->SetAuthor( get_bloginfo( 'name' ) );
$this->SetTitle( __( 'WooCommerce Order Report', 'my-custom-reports' ) );
$this->SetSubject( __( 'Order Report', 'my-custom-reports' ) );
$this->SetKeywords( 'report, order, woocommerce' );
$this->AddPage();
// Report Title
$this->SetFont( 'helvetica', 'B', 16 );
$this->Cell( 0, 15, __( 'WooCommerce Order Report', 'my-custom-reports' ), 0, 1, 'C' );
$this->SetFont( 'helvetica', '', 10 );
$this->Cell( 0, 10, sprintf( __( 'Generated on: %s', 'my-custom-reports' ), date( 'Y-m-d H:i:s' ) ), 0, 1, 'C' );
$this->Ln( 10 );
// Table Header
$this->SetFont( 'helvetica', 'B', 10 );
$this->SetFillColor( 220, 220, 220 );
$this->Cell( 30, 10, __( 'Order ID', 'my-custom-reports' ), 1, 0, 'C', 1 );
$this->Cell( 50, 10, __( 'Customer', 'my-custom-reports' ), 1, 0, 'C', 1 );
$this->Cell( 40, 10, __( 'Date', 'my-custom-reports' ), 1, 0, 'C', 1 );
$this->Cell( 40, 10, __( 'Total', 'my-custom-reports' ), 1, 1, 'C', 1 );
// Table Rows
$this->SetFont( 'helvetica', '', 9 );
$total_sales = 0;
if ( ! empty( $order_ids ) ) {
foreach ( $order_ids as $order_id ) {
$order = wc_get_order( $order_id );
if ( $order ) {
$customer_name = $order->get_formatted_billing_full_name();
$order_date = $order->get_date_created()->date( 'Y-m-d H:i:s' );
$order_total = $order->get_total();
$total_sales += $order_total;
$this->Cell( 30, 10, '#' . $order_id, 1, 0, 'C', 0 );
$this->Cell( 50, 10, $customer_name, 1, 0, 'L', 0 );
$this->Cell( 40, 10, $order_date, 1, 0, 'C', 0 );
$this->Cell( 40, 10, wc_price( $order_total ), 1, 1, 'R', 0 );
}
}
} else {
// Fetch recent orders if no IDs are provided (example)
$orders = wc_get_orders( array(
'limit' => 50, // Fetch last 50 orders
'status' => array( 'processing', 'completed' ),
) );
foreach ( $orders as $order ) {
$customer_name = $order->get_formatted_billing_full_name();
$order_date = $order->get_date_created()->date( 'Y-m-d H:i:s' );
$order_total = $order->get_total();
$total_sales += $order_total;
$this->Cell( 30, 10, '#' . $order->get_id(), 1, 0, 'C', 0 );
$this->Cell( 50, 10, $customer_name, 1, 0, 'L', 0 );
$this->Cell( 40, 10, $order_date, 1, 0, 'C', 0 );
$this->Cell( 40, 10, wc_price( $order_total ), 1, 1, 'R', 0 );
}
}
// Total Sales Summary
$this->Ln( 10 );
$this->SetFont( 'helvetica', 'B', 12 );
$this->Cell( 120, 10, __( 'Total Sales:', 'my-custom-reports' ), 0, 0, 'R' );
$this->Cell( 40, 10, wc_price( $total_sales ), 0, 1, 'R' );
return $this->Output( 'order_report.pdf', 'S' );
}
}
Integrating with WooCommerce Order Actions
To make this practical, we need a way to trigger PDF generation. A common pattern is to add an action link to the WooCommerce order list or order details page. We’ll use the admin class for this.
Admin Interface for Report Generation
This class will add a settings page and potentially buttons on the order list to trigger PDF generation.
includes/class-my-custom-reports-admin.php
<?php
if ( ! defined( 'ABSPATH' ) ) {
exit; // Exit if accessed directly.
}
/**
* Class My_Custom_Reports_Admin
*
* Handles admin-side functionalities, including settings and action links.
*/
class My_Custom_Reports_Admin {
/**
* Constructor.
*/
public function __construct() {
add_action( 'admin_menu', array( $this, 'add_admin_menu' ) );
add_action( 'admin_init', array( $this, 'handle_pdf_generation_request' ) );
add_filter( 'manage_edit-shop_order_columns', array( $this, 'add_custom_order_columns' ) );
add_action( 'manage_shop_order_posts_custom_column', array( $this, 'display_custom_order_columns' ), 10, 2 );
add_action( 'admin_notices', array( $this, 'display_admin_notices' ) );
}
/**
* Add admin menu page.
*/
public function add_admin_menu() {
add_menu_page(
__( 'Custom Reports', 'my-custom-reports' ),
__( 'Reports', 'my-custom-reports' ),
'manage_woocommerce',
'my-custom-reports-settings',
array( $this, 'render_settings_page' ),
'dashicons-chart-bar',
80
);
// Add submenu for order reports
add_submenu_page(
'my-custom-reports-settings',
__( 'Order Report', 'my-custom-reports' ),
__( 'Order Report', 'my-custom-reports' ),
'manage_woocommerce',
'my-custom-reports-order-report',
array( $this, 'render_order_report_page' )
);
}
/**
* Render the main settings page.
*/
public function render_settings_page() {
// This page could be used for global settings like logo, company address, etc.
// For now, it's a placeholder.
?>
<div class="wrap">
<h1><?php esc_html_e( 'Custom Reports Settings', 'my-custom-reports' ); ?></h1>
<p><?php esc_html_e( 'Configure your custom report settings here.', 'my-custom-reports' ); ?></p>
<!-- Add settings fields here (e.g., logo upload, company details) -->
<form method="post" action="options.php">
<?php
// Example: Add a placeholder for settings API
// settings_fields( 'my_custom_reports_options_group' );
// do_settings_sections( 'my-custom-reports-settings' );
// submit_button();
?>
</form>
</div>
<?php
}
/**
* Render the order report generation page.
*/
public function render_order_report_page() {
?>
<div class="wrap">
<h1><?php esc_html_e( 'Generate Order Report', 'my-custom-reports' ); ?></h1>
<form method="post" action="">
<input type="hidden" name="my_custom_reports_generate_report" value="1" />
<?php wp_nonce_field( 'my_custom_reports_generate_report_nonce' ); ?>
<p><?php esc_html_e( 'Select orders to include in the report (optional). Leave blank to generate a report of recent orders.', 'my-custom-reports' ); ?></p>
<!-- Basic order selection (can be enhanced with date pickers, search, etc.) -->
<label for="order_ids"><?php esc_html_e( 'Order IDs (comma-separated):', 'my-custom-reports' ); ?></label>
<input type="text" id="order_ids" name="order_ids" class="regular-text" />
<p class="submit">
<?php submit_button( __( 'Generate PDF Report', 'my-custom-reports' ) ); ?>
</p>
</form>
</div>
<?php
}
/**
* Handle the PDF generation request.
*/
public function handle_pdf_generation_request() {
// Check if the request is for invoice generation from order list
if ( isset( $_GET['action'] ) && $_GET['action'] === 'generate_invoice_pdf' && isset( $_GET['_wpnonce'] ) && wp_verify_nonce( $_GET['_wpnonce'], 'generate_invoice_pdf_' . $_GET['order_id'] ) ) {
$order_id = intval( $_GET['order_id'] );
$pdf_generator = new My_Custom_Reports_PDF();
$pdf_content = $pdf_generator->generate_invoice( $order_id );
if ( $pdf_content ) {
// Output PDF for download
header( 'Content-Type: application/pdf' );
header( 'Content-Disposition: attachment; filename="invoice_' . $order_id . '.pdf"' );
header( 'Content-Length: ' . strlen( $pdf_content ) );
echo $pdf_content;
exit;
} else {
// Handle error: order not found or PDF generation failed
wp_redirect( admin_url( 'edit.php?post_type=shop_order&page=my-custom-reports-error=1' ) );
exit;
}
}
// Check if the request is for report generation from the report page
if ( isset( $_POST['my_custom_reports_generate_report'] ) && $_POST['my_custom_reports_generate_report'] == '1' && isset( $_POST['_wpnonce'] ) && wp_verify_nonce( $_POST['_wpnonce'], 'my_custom_reports_generate_report_nonce' ) ) {
$order_ids = array();
if ( ! empty( $_POST['order_ids'] ) ) {
$order_ids = array_map( 'intval', explode( ',', sanitize_text_field( $_POST['order_ids'] ) ) );
$order_ids = array_filter( $order_ids ); // Remove empty values
}
$pdf_generator = new My_Custom_Reports_PDF();
$pdf_content = $pdf_generator->generate_order_report( $order_ids );
if ( $pdf_content ) {
// Output PDF for download
header( 'Content-Type: application/pdf' );
header( 'Content-Disposition: attachment; filename="order_report_' . date('Ymd') . '.pdf"' );
header( 'Content-Length: ' . strlen( $pdf_content ) );
echo $pdf_content;
exit;
} else {
// Handle error
wp_redirect( admin_url( 'admin.php?page=my-custom-reports-order-report&error=1' ) );
exit;
}
}
}
/**
* Add custom columns to the WooCommerce order list.
*
* @param array $columns Existing columns.
* @return array Modified columns.
*/
public function add_custom_order_columns( $columns ) {
$columns['invoice_pdf'] = __( 'Invoice PDF', 'my-custom-reports' );
return $columns;
}
/**
* Display content for custom order columns.
*
* @param string $column The current column name.
* @param int $order_id The order ID.
*/
public function display_custom_order_columns( $column, $order_id ) {
if ( 'invoice_pdf' === $column ) {
$order = wc_get_order( $order_id );
if ( $order ) {
$nonce = wp_create_nonce( 'generate_invoice_pdf_' . $order_id );
$url = admin_url( 'edit.php?post_type=shop_order&action=generate_invoice_pdf&order_id=' . $order_id . '&_wpnonce=' . $nonce );
echo '<a href="' . esc_url( $url ) . '" class="button button-small" target="_blank">' . __( 'Download Invoice', 'my-custom-reports' ) . '</a>';
}
}
}
/**
* Display admin notices for errors.
*/
public function display_admin_notices() {