Pridge WP Endpoint

Pridge WP Endpoint connects WordPress and WooCommerce to Pridge Server virtual printers. It sends raw print payloads through the server's plugin API and provides a stable PHP entry point that other WordPress plugins can use.

This repository contains the source-side WordPress plugin only. Pridge Server and the desktop client that pulls jobs and talks to physical printers are separate applications.

Capabilities

• Separate Overview, Integrations, Endpoints & Routing, and Print Archive pages.
• Raw binary-safe submission to POST /api/plugin/jobs.
• Multiple named endpoint tokens with a configurable default destination.
• Per-document routing for receipts, invoices, packing slips, and active Shiptastic carrier labels.
• Public PHP submission API for other plugins.
• Optional WooCommerce receipt printing and Germanized PDF document printing.
• WooCommerce HPOS-compatible order access, duplicate prevention, and bounded retries.
• Optional Germanized integration with an explicit dependent switch.
• Shiptastic shipped order trigger and provider-specific label forwarding.
• Binary-safe archive of successful and failed attempts with protected payload previews.
• Scoped dark-neon administration with accessible modals and reduced-motion support.
• Third-party plugin notices suppressed only on Pridge administration pages.
• Self-updating from GitHub releases through WordPress's native Plugins page, with an automatic backup before every update and one-click restore.

Version 0.3.0 uses existing Germanized Pro and Shiptastic PDF files for routed invoice, packing-slip, and shipping-label jobs.

Requirements

• WordPress 6.4 or newer.
• PHP 7.4 or newer.
• A reachable Pridge Server and at least one endpoint token.
• WooCommerce only when automatic order printing is required.
• Germanized for WooCommerce only when its optional adapter is enabled.
• Shiptastic for WooCommerce only when the Shipped trigger or shipping-label routes are required.

Installation and configuration

1. Copy this plugin directory into wp-content/plugins/pridge-wp-endpoint.
2. Activate Pridge WP Endpoint on the WordPress Plugins screen.
3. Open Pridge in the WordPress administration menu.
4. On Overview, enter the server base URL without /api/plugin/jobs.
5. On Endpoints & Routing, add one named endpoint token for each virtual printer.
6. Choose a default endpoint and assign each document type to its intended endpoint.
7. Use Test default endpoint on Overview to submit a real test job.
8. Enable the desired optional integrations on Integrations.

Tokens are stored in a non-autoloaded WordPress option and are never rendered back into the settings form. Leaving an existing endpoint's token field empty preserves its saved value.

WooCommerce integration

WooCommerce is optional. Enable it on Integrations and choose the order state that should create routed order documents. Leaving a document route unassigned disables automatic printing for that type.

The plugin can generate a compact plain-text receipt from WooCommerce CRUD objects. When the Germanized integration is disabled, invoice and packing-slip routes retain their basic text fallback. When Germanized is enabled, those fallbacks are not used: the integration fetches the existing Germanized Pro PDF files instead. The integration:

• supports High-Performance Order Storage;
• runs after the selected WooCommerce status or Shiptastic shipped transition;
• records an accepted job ID per event and document to prevent duplicate submissions;
• retries only network failures and HTTP 5xx responses, up to three times with backoff;
• never makes a Pridge failure roll back checkout or order processing.

Automatic WooCommerce printing is disabled by default.

Germanized integration

Germanized is optional and disabled by default. Its switch can only be enabled when both the WooCommerce integration and Germanized for WooCommerce are active. When enabled, Pridge uses the latest finalized Germanized Pro/StoreaBill invoice PDF and the existing packing-slip PDF attachments stored on the order's Shiptastic shipments. It never substitutes generated text for these routed documents.

The Test Germanized PDFs button belongs to the Germanized section and lists the 50 most recent orders. It sends every existing PDF that has a configured route: invoice, each packing slip, and each carrier label. The test bypasses normal duplicate prevention, does not mark the documents as automatically printed, and records every attempted submission in Print Archive. Missing PDFs are reported and are never generated by the test.

Disabling the switch bypasses Germanized-specific behavior. A missing or inactive Germanized installation never causes a fatal error.

Shiptastic integration

Current Germanized releases use the separate Shiptastic for WooCommerce plugin for shipment and label workflows. When Shiptastic is active:

• Shipped (Shiptastic) appears in the order trigger list;
• each active shipping provider appears as its own shipping-label route;
• a newly created label is forwarded as its original PDF, image, or raw label bytes;
• label metadata prevents the same label from being sent twice to the same endpoint.

Shipping labels are sent when Shiptastic creates the label. The Shipped trigger controls when receipt, invoice, and packing-slip routes run; these are separate events.

When Germanized integration is enabled, automatic order events and the Germanized PDF test also use existing Shiptastic labels whose carrier has an assigned route. Testing never creates or purchases a new carrier label.

Print archive

Every submission attempt made through the internal job service is archived, including failed attempts. The archive stores a binary-safe payload copy, destination, document type, safe metadata, result, and timestamp. Administrators can use View to inspect text, a bounded hexadecimal preview of opaque bytes, or an inline PDF/image.

Archive details and inline files require manage_options plus WordPress nonces. Data is retained on deactivation and uninstall by default. It is removed on uninstall only when the administrator explicitly enables the data-removal preference on Overview.

Public PHP API

Other plugins can submit raw bytes after plugins_loaded without reading Pridge options or instantiating internal classes:

$result = pridge_wp_submit_job(
    $raw_bytes,
    array(
        'content_type'  => 'application/octet-stream',
        'endpoint_id'   => 'warehouse-printer',
        'document_type' => 'packing_slip',
        'metadata'      => array(
            'source'   => 'my-plugin',
            'document' => 'packing-slip',
        ),
    )
);

if ( is_wp_error( $result ) ) {
    $error_code = $result->get_error_code();
} else {
    $job_id = $result['job_id'];
}

Use pridge_wp_is_configured() to check whether a server URL and usable default endpoint are saved.

Arguments

pridge_wp_submit_job( string $payload, array $args = array() ) accepts:

• payload: raw bytes as a PHP string. Do not base64-encode or JSON-wrap them.
• content_type: the real payload MIME type. The configured default is used when omitted.
• metadata: a small non-sensitive array, JSON-encoded into X-Pridge-Metadata, with a 4 KB maximum.
• endpoint_id: optional named endpoint ID. The configured default is used when omitted.
• document_type: optional archive and routing identifier for the payload.

It returns an array containing job_id, status, archive_id, endpoint_id, and endpoint_name after an exact 201 Created response, or WP_Error on failure.

Extension hooks

apply_filters( 'pridge_wp_job_metadata', $metadata, $safe_context );
do_action( 'pridge_wp_before_submit', $safe_context );
do_action( 'pridge_wp_after_submit', $result, $safe_context );
apply_filters( 'pridge_wp_woocommerce_receipt_lines', $lines, $order );
apply_filters( 'pridge_wp_woocommerce_invoice_lines', $lines, $order );
apply_filters( 'pridge_wp_woocommerce_packing_slip_lines', $lines, $order );

The safe context contains byte count, content type, and document type. The post-submission action also receives the resolved endpoint ID. Endpoint tokens and raw payloads are never passed to hooks.

Pridge Server contract

POST <base_url>/api/plugin/jobs
Authorization: Bearer <endpoint token>
Content-Type: <payload content type>
X-Pridge-Metadata: {...optional JSON...}

<raw payload bytes>

The token identifies the destination and is never sent in a URL. The request body is passed unchanged to WordPress's HTTP API. TLS certificate verification is always enabled and every request has a finite timeout.

Security and data handling

• Settings changes and test submissions require manage_options and valid nonces.
• Endpoint tokens are never added to HTML, JavaScript, URLs, archive metadata, or logs.
• WooCommerce diagnostics contain only a document key, order ID, attempt number, and safe error code.
• Archive payload access is restricted to administrators and protected by nonces.
• Deactivation preserves all settings and archive data.
• Uninstall removes data only when the administrator explicitly enables that preference.
• Print jobs may contain personal or commercial data. Calling integrations are responsible for limiting metadata and payload content to what printing requires.

Development

The plugin has no bundled Composer or npm runtime dependencies. Validate changed PHP files with php -l, and use the configured WordPress coding standards and test suite when those tools are available.

All source code, documentation, logs, commit messages, and UI strings must remain in English.

License

GNU General Public License v3.0 or later, with one additional term under GPLv3 Section 7(b). See LICENSE for the full license text and ADDITIONAL_TERMS.md for the additional term.

❤️ Support Development

☕ Buy Me a Coffee
https://buymeacoffee.com/sayehava

💜 Ko-fi
https://ko-fi.com/sayehava

[!TIP] Even a small donation helps fund future modules, maintenance, bug fixes, and new features.