Athenian Order PDFs

Developer starting point

This baseline documents order-PDF generation code. It does not claim a production PDF artifact, email delivery, or customer download has been exercised.

Customer Workflow

Individual Order Download

1. Customer logs into WooCommerce My Account.
2. Customer opens the Orders list or a single order.
3. The plugin verifies account context, order ownership, and permissions.
4. A Download PDF action/button appears when access is allowed.
5. The download URL is generated using the order-pdf endpoint and a nonce.
6. The plugin renders the order through WCOPDF\Templates::render_order().
7. Dompdf converts the HTML to a downloadable PDF.
8. The browser receives a Content-Disposition: attachment response with the generated filename.

Bulk Order Export

1. Customer opens the Order PDFs My Account tab.
2. Customer optionally enters a monthly range.
3. The plugin queries WooCommerce orders for the current customer.
4. Each order is rendered into the same invoice-style template.
5. Orders are joined with page breaks.
6. Dompdf renders a combined PDF.
7. The file is downloaded using a timestamped filename such as:

orders-example.com-20260701-153000.pdf

---

Technical Architecture

Main Bootstrap

athenian-order-pdfs.php defines plugin constants, loads Composer autoload if present, registers a simple namespace-based autoloader for the WCOPDF namespace, flushes rewrite rules on activation/deactivation, checks WooCommerce availability, and initializes the plugin on plugins_loaded.

Key constants:

define('WCOPDF_VERSION', '1.0.3');
define('WCOPDF_FILE', __FILE__);
define('WCOPDF_DIR', plugin_dir_path(__FILE__));
define('WCOPDF_URL', plugin_dir_url(__FILE__));

Class Overview

| Class | File | Responsibility | | --- | --- | --- | | WCOPDF\Plugin | includes/Plugin.php | Central initializer, endpoint registration, query vars, download routing. | | WCOPDF\Admin | includes/Admin.php | Settings page, registered options, Media Library logo picker, color picker assets, Dompdf warning. | | WCOPDF\Buttons | includes/Buttons.php | Adds My Account order-list and single-order PDF buttons with ownership checks. | | WCOPDF\Account_Page | includes/Account_Page.php | Adds the Order PDFs account-menu item and renders the bulk export form. | | WCOPDF\Downloads | includes/Downloads.php | Builds download URLs, validates nonces, queries orders, streams PDFs. | | WCOPDF\Templates | includes/Templates.php | Renders order HTML, document wrapper, PDF CSS, brand header, line-item tables, totals, notes, and transaction details. |

WordPress and WooCommerce Hooks

| Hook | Location | Purpose | | --- | --- | --- | | plugins_loaded | Main plugin file | Initializes the plugin after WooCommerce availability check. | | init | Plugin, Account_Page | Registers rewrite endpoints. | | query_vars | Plugin | Adds PDF-related query vars. | | template_redirect | Plugin | Routes PDF download requests. | | admin_menu | Admin | Adds the settings page. | | admin_init | Admin | Registers plugin settings. | | admin_enqueue_scripts | Admin | Enqueues Media Library, color picker, admin CSS/JS. | | admin_notices | Admin | Shows WooCommerce/Dompdf dependency notices. | | woocommerce_account_menu_items | Account_Page | Adds the My Account menu item. | | woocommerce_account_order-pdfs-all_endpoint | Account_Page | Renders the bulk export account endpoint. | | woocommerce_my_account_my_orders_actions | Buttons | Adds the single-order PDF action to the orders list. | | woocommerce_order_details_after_order_table | Buttons | Adds the single-order PDF button to the order-detail view. |

Rewrite Endpoints

The plugin registers two account-facing endpoints:

| Endpoint | Purpose | | --- | --- | | order-pdf | Single-order PDF download endpoint. | | order-pdfs-all | Bulk/all-orders PDF export endpoint and My Account page. |

The plugin also registers supporting query vars:

wcopdf
order_id
nonce
_wpnonce
range

---

PDF Rendering Flow

Single Order

My Account button
  → Downloads::single_order_url(order_id)
  → order-pdf endpoint with nonce
  → Plugin::maybe_download_pdf()
  → Downloads::download_single_order(order_id, nonce)
  → permission + nonce validation
  → Templates::render_order(order)
  → Downloads::output_pdf(html, filename)
  → Dompdf render + PDF response

Bulk Orders

Order PDFs account tab
  → bulk export form
  → order-pdfs-all endpoint with wcopdf=all
  → Plugin::maybe_download_pdf()
  → Downloads::download_all_orders(range)
  → WC_Order_Query
  → Templates::render_order(order) for each order
  → page-break joined HTML
  → Templates::wrap_document()
  → Dompdf render + combined PDF response

Dompdf Behavior

When Dompdf\Dompdf is available, the plugin:

• Creates a new Dompdf\Options instance.
• Enables remote assets with isRemoteEnabled.
• Sets chroot to ABSPATH.
• Uses A4 portrait paper.
• Loads the generated HTML.
• Renders the PDF.
• Sends no-cache headers.
• Sends Content-Type: application/pdf.
• Sends Content-Disposition: attachment with UTF-8 filename handling.

When Dompdf is not installed, the plugin falls back to an HTML preview and displays an instruction to install Dompdf with Composer:

composer require dompdf/dompdf:^2

---

Template and Document Design

The PDF layout is defined primarily inside WCOPDF\Templates::wrap_document() and WCOPDF\Templates::render_order().

Notable design decisions:

• A4 portrait format.
• Compact modern sales-order layout.
• Dompdf-friendly inline CSS.
• Header grid with logo, brand/store address, and invoice title.
• Meta table for order number, date, payment, shipping, and status.
• Billing and shipping cards.
• Line-item table with thumbnail, item name, metadata, quantity, price, and total.
• Bottom grid with notes/transaction context on the left and order totals on the right.
• Running footer using CSS page margin behavior.
• Page-break protection for key document blocks.
• Generated color tints based on admin-selected brand colors.

The plugin also includes assets/css/pdf.css, which appears to contain an alternate or reusable compact invoice stylesheet. The currently inspected PHP template embeds its main PDF styles inline for Dompdf rendering.

---

Security and Permission Model

Single-Order Downloads

Single-order PDFs are protected by:

• Logged-in WooCommerce account context.
• Order ownership check.
• manage_woocommerce override for authorized administrators/managers.
• Nonce validation based on the order ID.
• Legacy nonce compatibility for older URLs that included user ID in the nonce action.

Nonce actions include:

wcopdf_order_{order_id}
wcopdf_order_{order_id}|{user_id}  // legacy compatibility

Bulk Downloads

Bulk PDF exports require a logged-in user or WooCommerce management capability. Non-admin users are restricted to orders matching their own customer ID. Users with manage_woocommerce can generate broader order exports.

Potential hardening opportunity: the current bulk export form is permission-gated and sanitizes the range input, but adding a nonce to the bulk export form would make the flow more consistent with the single-order download endpoint.

---

Data Model and Persistence

The plugin does not create custom database tables, custom post types, or custom taxonomies. It reads directly from WooCommerce orders and stores configuration in WordPress options.

WordPress Options

wcopdf_logo_id
wcopdf_logo_url
wcopdf_color_primary
wcopdf_color_secondary
wcopdf_color_accent
wcopdf_footer_text
wcopdf_filename_pattern

WooCommerce Data Read

The plugin reads from native WooCommerce order structures, including:

• WC_Order objects.
• Order item products.
• Order item coupons.
• Order item shipping rows.
• Order fees.
• Refund totals.
• Customer notes.
• Payment gateway/order payment method data.
• Billing and shipping addresses.
• Product image IDs.
• Item metadata.

---

Technical Strengths

• Clean namespace organization under WCOPDF.
• Lightweight class structure with separated responsibilities.
• Uses WooCommerce account hooks rather than custom account UI routing.
• Uses WordPress Settings API for admin configuration.
• Uses WordPress Media Library for logo selection.
• Uses WordPress color picker for brand styling.
• Uses WooCommerce order APIs rather than direct SQL.
• Provides dependency warnings for missing Dompdf.
• Includes defensive order ownership checks for customer downloads.
• Supports legacy nonce actions for backward compatibility.

---

Implementation Notes for Developers

• Flush rewrite rules after activation or when endpoints are changed.
• Confirm Dompdf is installed in the plugin directory if PDF downloads show HTML preview instead.
• Confirm WooCommerce My Account page permalinks are working before testing endpoints.
• Review assets/js/custom-best-match-search.php before deploying as part of this plugin package.
• Keep PDF template styling Dompdf-compatible; advanced modern CSS support may be limited.
• Be careful when enabling remote images through Dompdf in production environments.
• Consider performance testing for customers with very large order histories.

---