Download the PHP package bitdreamit/laravel-qz-tray without Composer

Laravel QZ Tray

Enterprise silent printing for Laravel. Print PDFs, ZPL labels, ESC/POS receipts, and raw commands directly from your browser — no print dialog, no pop-ups — using QZ Tray's WebSocket bridge.

Quick Start

For the impatient — five commands to a working test print. Every step is explained in full further down; this is just the fast path.

Add the CSRF meta tag and two <script> tags to your layout (see QZ Tray on the machine that will physically print, then visit:

That page shows live connection status, lets you pick a printer, and print a real test job. If it prints, you're done — jump to Frontend Usage for how to wire it into your own pages.

Table of Contents

• Quick Start
• What is This?
• Requirements
• Installation — Step by Step
  • Step 1 — Install via Composer
  • Step 2 — Run the Installer Command
  • Step 3 — Run Migrations
  • Step 4 — Add Scripts to Your Layout
  • Step 5 — Install QZ Tray on Client Machines
  • Step 6 — Verify Everything Works
• Publishing Assets — Manual Control
• Configuration Reference
• Certificate Management
• Artisan Commands
• All Available Routes / API Endpoints
• Frontend Usage — SmartPrint JS
  • Method 1 — HTML Data Attributes (Zero JS)
  • Method 2 — JavaScript API
  • Method 3 — Global Shorthand Functions
  • Print Types Reference
  • All Data Attributes Reference
  • Full SmartPrint API Reference
  • Events Reference
• Printing Use Cases
  • Print a PDF Invoice
  • Print a ZPL Label (Zebra)
  • Print an ESC/POS Receipt (Thermal)
  • Auto-Print on Page Load
  • Print with Copies and Delay
  • Printer Switcher Modal
  • Print Queue with Retry
  • Offline Queue (Print When Reconnected)
  • Listen to Print Events
  • Using the ZPL Adapter
  • Using the ESC/POS Adapter
• Laravel Backend Printing (Server-Side)
• Database — Print Job Logging
• Multi-Tenant Support
• Security
• Environment Variables Reference
• Troubleshooting
• File Structure
• Upgrade Guide
• FAQ

What is This?

Standard web printing always shows a dialog box. Laravel QZ Tray eliminates that entirely.

How it works:

1. QZ Tray is a small Java application running on each client machine. It opens a local WebSocket server on port 8181.
2. Your Laravel app provides a signed certificate (at /qz/certificate) so QZ Tray trusts your website.
3. SmartPrint.js connects to QZ Tray via WebSocket and sends print jobs silently.
4. The print job goes directly to the physical printer — no dialog, no confirmation.

Requirements

Note: QZ Tray must be installed on every client machine (the computer connected to the printer). It does NOT need to be on your server.

Installation — Step by Step

Step 1 — Install via Composer

Laravel auto-discovers the service provider. Nothing extra needed.

Step 2 — Run the Installer Command

This single command does everything:

• Publishes config/qz-tray.php
• Publishes database migrations
• Publishes Blade views to resources/views/vendor/qz-tray/
• Publishes JavaScript and CSS assets to public/vendor/qz-tray/
• Generates your SSL certificate automatically

Expected output:

Force reinstall: Add --force to overwrite existing files:

Step 3 — Run Migrations

This creates the qz_print_jobs table for optional print job logging.

Step 4 — Add Scripts to Your Layout

Add these two lines to your main Blade layout (e.g. resources/views/layouts/app.blade.php), just before </body>:

Important: The <meta name="csrf-token"> tag is required. SmartPrint uses it to sign print requests.

Step 5 — Install QZ Tray on Client Machines

Each computer that will physically print needs QZ Tray installed.

Download links by OS:

Or link directly in your app:

After installing, QZ Tray starts automatically with Windows/macOS and runs in the system tray. No configuration needed on the client side.

Step 6 — Verify Everything Works

1. Check status endpoint:

   Should return:

2. Open the interactive test page:

   This is the official QZ Tray demo — you can test all print types here.

3. Open the SmartPrint demo page:

   Interactive page showing connection status, printer list, and live print testing.

4. Test the signing pipeline:

   Should return "message": "Signing works correctly".

Publishing Assets — Manual Control

php artisan qz:install (Step 2 above) runs every publish group at once plus generates a certificate — the right choice for a first install. Reach for the individual vendor:publish commands below when you want more control: republishing only the config after an update, keeping generated views out of a CI pipeline, or a Docker build step that shouldn't touch storage/.

Publish everything at once without the installer command's certificate-generation step:

Add --force to any of the above to overwrite files you've already published (e.g. after upgrading the package and wanting the latest smart-print.js):

After publishing qz-assets, re-run php artisan migrate if you also re-published qz-migrations — publishing only copies the migration file into your app; it doesn't run it.

Configuration Reference

After publishing, edit config/qz-tray.php:

Protect routes with authentication (recommended for production):

Certificate Management

The certificate allows QZ Tray to trust your website. It is a self-signed SSL certificate generated on your server — only the public certificate is sent to the browser; the private key never leaves your server.

Generate a new certificate

Force regenerate (replace existing)

Show certificate details after generation

Example output:

Customize certificate subject

Edit config/qz-tray.php:

Then regenerate:

Certificate file locations

Security: The storage/qz/ directory should not be web-accessible. Laravel's storage/ folder is not served by default — this is correct.

Artisan Commands

qz:prune-preferences isn't scheduled automatically — the qz_printer_preferences table (unlike the old Cache-backed printer memory) doesn't expire on its own. Wire it into your scheduler if row growth matters for your install:

All Available Routes / API Endpoints

All routes are prefixed with /qz by default (configurable).

Security

Status & Health

Printer Management

Device identity (v1.1.0+): every request to /qz/printer, /qz/print, /qz/jobs, and /qz/clear-cache is scoped by whichever of these identities is present, in the order set by qz-tray.identity_priority (default device → user → session):

• device — send an X-Device-Id: <uuid> header (or device_id body/query param). SmartPrint.getDeviceId() returns the UUID smart-print.js already generates and persists per browser/workstation — use the same value if you call these endpoints yourself.
• user — the authenticated user (auth()->user()), when the route runs behind an auth middleware.
• session — anonymous fallback, isolated per Laravel session.

A request can match more than one identity at once (e.g. a logged-in user on a device-identified kiosk); POST /qz/printer writes a preference row for every identity present, so switching identity_priority later doesn't lose data. There is no unscoped, identity-less fallback — two different users/workstations can never read each other's stored printer.

Print Jobs

Cache & Setup

Demo & Test Pages

Installer Downloads

Frontend Usage — SmartPrint JS

SmartPrint is the JavaScript library that lives in public/vendor/qz-tray/js/smart-print.js. It handles the WebSocket connection, signing, queue, retry, and printer memory automatically.

Method 1 — HTML Data Attributes (Zero JS)

The simplest approach. Add data-qz-print to any button or element. No JavaScript needed.

Method 2 — JavaScript API

Full control via the SmartPrint global object.

Method 3 — Global Shorthand Functions

These global helpers are available anywhere on the page:

Print Types Reference

All Data Attributes Reference

Full SmartPrint API Reference

Printing

Printer Management

Print Job Promises (v1.1.0+)

print(), printRaw(), printZPL(), and printESC() all return a Promise that resolves once the job actually reaches the printer (or the browser fallback dialog), and rejects on failure — including if the user cancels the printer-selection modal. Prior releases documented this but it silently resolved to undefined; it now behaves as documented.

Connection

Queue Management

Cache

Settings

Events Reference

Listen to events using SmartPrint.on(event, callback):

Remove an event listener:

Printing Use Cases

Print a PDF Invoice

Your Laravel route just returns a PDF response as normal:

Print a ZPL Label (Zebra)

Laravel route returning ZPL:

Print an ESC/POS Receipt (Thermal)

Or generate the receipt server-side and fetch it:

Auto-Print on Page Load

Print automatically when the page loads, with no button click needed:

With a delay (useful for "print after save" flows):

Using JavaScript:

Print with Copies and Delay

Printer Switcher Modal

Show a modal for the user to pick a printer:

Or use the keyboard shortcut: Press Ctrl + Shift + P anywhere on the page.

The modal shows all available printers. The user clicks one and it is saved (per-page by default) in localStorage.

To set a printer programmatically:

Print Queue with Retry

SmartPrint automatically queues jobs and processes them one by one. Jobs that fail are saved to a retry buffer.

Add the built-in queue UI to your page:

Offline Queue (Print When Reconnected)

If QZ Tray is offline when a job is submitted, SmartPrint saves it to localStorage. When QZ Tray reconnects, the jobs print automatically.

Listen to Print Events

Use events to update your UI, track completions, or log to your backend:

Using the ZPL Adapter

The package includes a ZPL helper (public/vendor/qz-tray/js/adapters/zpl.js). Include it alongside smart-print.js:

Using the ESC/POS Adapter

Include adapters/escpos.js:

Laravel Backend Printing (Server-Side)

You can trigger a print from a Laravel controller — for example, after saving an order:

Or redirect with a flash variable:

Database — Print Job Logging

Two tables ship with this package. Both are optional — the package works with neither migrated (job logging and server-synced printer memory just silently no-op), but you'll want both for anything beyond a single-page demo.

qz_print_jobs

Every POST /qz/print request writes a row here (that's what smart-print.js calls internally after each successful qz.print() — see Full SmartPrint API Reference). You don't need to write to it manually.

Querying your own job history:

Enable request-level logging (separate from the DB rows above — this writes to your Laravel log file, not the database):

qz_printer_preferences

Server-side backup for printer memory (the client-side source of truth is localStorage; this table exists so a cleared browser profile or a fresh browser on the same physical workstation can pick its printer back up — see Printer Switcher Modal). One row per (tenant_id, identity_type, identity_value, path) combination.

Rows aren't pruned automatically — see qz:prune-preferences in Artisan Commands.

Multi-Tenant Support

Every table above is tenant-aware. tenant_id (and qz_print_jobs' user_id/user_type) are natively typed — uuid or unsignedBigInteger — and follow id_type: same setting, same convention, one config to change.

This assumes your project uses one PK convention throughout — if your tenant/project table and your User model are both bigint-keyed (or both uuid-keyed), set id_type to match and everything lines up with real, indexed, natively-typed columns instead of an untyped string. If a single project genuinely mixes a bigint tenant table with a uuid-keyed User model (or vice versa) — uncommon, but it happens — this config can only match one of them; you'd need to fork the migration for that specific column if you hit this.

Auto-tagging every request without passing it at every call site — set a resolver once in config, used only when the request doesn't supply tenant_id/project_id explicitly:

Filtering print jobs by tenant:

Scoping printer memory to a tenant too (not just job history) — pass the same tenant_id/project_id on POST /qz/printer, or set it once page-wide from your Blade layout so smart-print.js sends it automatically on every printer-memory and job-logging call:

The GET /qz/jobs queue listing also narrows by tenant when one is present, on top of its existing per-device/per-user scoping — see All Available Routes / API Endpoints.

On qz_printer_preferences specifically: its tenant_id is nullable (no default) regardless of id_type, and — unlike the earlier string-based version of this table — a native uuid column can't use an empty-string sentinel for "no tenant" (Postgres rejects '' outright as invalid UUID format). This means the uniqueness constraint is a slightly weaker safety net for single-tenant uuid-mode installs than it was before: setPrinter()/getPrinter() always match on explicit conditions rather than relying on the DB constraint, so this doesn't affect correctness in normal use, only how hard the database itself guards against a genuine race condition.

Security

Route Protection

By default routes have only web middleware. Add auth in production:

Or apply additional middleware:

CSRF Protection

All POST requests from SmartPrint.js automatically include the CSRF token from the <meta name="csrf-token"> tag. No extra setup needed.

Certificate Security

• The private key (storage/qz/private-key.pem) is only used server-side to sign requests. It is never sent to the browser.
• The public certificate (storage/qz/digital-certificate.txt) is sent to QZ Tray so it knows to trust your domain.
• QZ Tray uses this certificate to verify that print requests genuinely came from your application.
• Never enable allow_public_cert_generate in production.

Rate Limiting

The signing endpoint is the most sensitive — consider adding rate limiting:

Environment Variables Reference

None of these are required — every one has a working default and the package runs fully without a .env entry for any of them. Add only the ones you want to override.

Copy-paste block — every variable at its package default (harmless to add as-is; edit only what you're actually changing):

A realistic production override — name your printer, generate the cert once via php artisan qz:generate-certificate instead of auto-generating it, and turn on job logging:

Troubleshooting

"Certificate not found"

Check that storage/qz/ is writable:

"Could not connect — is QZ Tray running?"

1. Install QZ Tray from qz.io/download
2. Start QZ Tray — look for the icon in the system tray
3. Check it's running on port 8181 (default)
4. Make sure the browser page is served over http:// or https:// (not file://)

Connection works but prints fail

• Open /qz/status — check certificate and private_key are both "present"
• Open /qz/test — test the connection interactively
• Make sure <meta name="csrf-token" content="{{ csrf_token() }}"> is in your <head>
• Check browser console for errors

"CSRF token mismatch" on /qz/sign

Ensure the CSRF meta tag is present:

And that /qz/sign is not excluded in VerifyCsrfToken:

Printer list is empty

The printer list comes from QZ Tray via WebSocket — not from the server. If empty:

1. Confirm QZ Tray is running (system tray icon visible)
2. Confirm the browser connected (check /qz/smart for status indicator)
3. Try clicking "Refresh Printers" on /qz/smart

Printing works in development but not production (HTTPS)

QZ Tray 2.x supports HTTPS. Ensure:

• Your site is on https://
• The certificate at /qz/certificate loads without errors
• QZ Tray 2.x is installed (not 1.x)

"openssl_sign failed"

The private key may be corrupted. Regenerate:

Clear all caches

File Structure

After running php artisan qz:install, the following files are published:

Package source (inside vendor/bitdreamit/laravel-qz-tray/):

Upgrade Guide

From v0.x to v1.0

1. Update composer:

2. Re-publish assets (use --force to overwrite):

3. Regenerate certificate:

4. Run migrations:

5. Update HTML — replace old data-smart-print attributes with data-qz-print:

FAQ

Q: Does this package require a license from QZ Tray? A: QZ Tray Community Edition is free for internal/self-hosted use. A commercial license is required for redistribution. See qz.io/pricing.

Q: Does this work on mobile devices? A: No. QZ Tray is a desktop application. Mobile browsers cannot connect to a local WebSocket server. Mobile devices need to use the standard browser print dialog.

Q: Can multiple users print to different printers at the same time? A: Yes. Each browser tab has its own WebSocket connection to QZ Tray on that machine. Users on different machines print to their own locally-connected printers independently.

Q: What happens if QZ Tray is not installed on a client machine? A: SmartPrint falls back to opening the browser's print dialog (if fallback.enabled = true in config). You can also listen to the connection-failed event and show a download link.

Q: Can I use this with React, Vue, or Livewire? A: Yes. SmartPrint is a plain JavaScript object on window. Call it from any framework:

Q: Can I print to a network printer (not USB)? A: Yes — both USB and network printers work the same way from this package's side, because QZ Tray doesn't maintain its own printer list at all. It reads whatever printers the operating system already has registered, and hands you that exact list via WebSocket (SmartPrint.getPrinters()). So "supported" really means "known to Windows/macOS/Linux":

• USB: install the manufacturer's driver as normal. It shows up like any other local printer.
• Network (standard PDF/document printing): add it in the OS as a network printer — e.g. Windows: Add Printer → "The printer that I want isn't listed" → Add a printer using a TCP/IP address, pointing at the printer's IP. macOS: System Settings → Printers & Scanners → Add → IP. Once it's in the OS printer list, it's in QZ Tray's list too — no separate configuration.
• Network thermal/label printers sending raw ZPL/ESC-POS (the common case for the receipt/label printing this package is built for): same idea, but add it as a raw/generic printer over a Standard TCP/IP Port (Windows) or a raw queue via CUPS socket:// (macOS/Linux) rather than the manufacturer's PostScript/graphics driver — QZ Industries has step-by-step tutorials for Windows and macOS. Some drivers (e.g. Zebra ZDesigner) support both raw and standard printing in one driver — prefer that over the generic driver if available, since the generic raw driver can't print PDFs/images.

Either way, once it's registered in the OS, use its exact OS-assigned name as the printer value — same as any USB printer.

Q: Is the private key secure? A: Yes — the private key lives in storage/qz/ which is not web-accessible. It is used only by PHP to sign requests, and is never sent to the client.

Q: The certificate expires after 20 years — do I need to renew it? A: Yes, but after 20 years. You can regenerate at any time with php artisan qz:generate-certificate --force — just ensure the new certificate is pushed to production.

License

MIT License — see LICENSE for details.

Support

• GitHub Issues: github.com/bitdreamit/laravel-qz-tray/issues
• Email: [email protected]
• QZ Tray Documentation: qz.io/api

Made with ❤️ by Bit Dream IT