darvis / printserver

v1.2.0 2026-10-28 10:56 UTC

Requires

• php: ^8.2
• laravel/framework: ^11.0|^12.0|^13.0

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.0
• orchestra/testbench: ^9.0|^10.0|^11.0
• pestphp/pest: ^3.0|^4.0
• pestphp/pest-plugin-laravel: ^3.0|^4.0
• phpunit/phpunit: ^11.0|^12.0|^13.0

MIT

• Arvid de Jong

• laravel
• printing
• zebra
• CUPS
• ipp
• laravel-boost
• print-server

Published on Packagist.org on 2026-10-28 10:56 UTC

README

Print on a printer that stands somewhere else, without opening a port on the router there.

Your application queues a print job. A small box on location (a mini pc or a Raspberry Pi with CUPS) asks this application every few seconds whether there is work, fetches the file over HTTPS and prints it on its own network. All traffic is outgoing from that location, so the printers are not reachable from the internet at all.

That is the point of this package. Sending bytes straight to port 9100 of a printer behind a port forward works until a scanner finds the port, and then the printer starts producing other people's pages.

Requirements

• PHP 8.2 or higher
• Laravel 11, 12 or 13
• A database and a filesystem disk
• A box on location that runs the agent, with CUPS and the printers installed

Install

composer require darvis/printserver
php artisan migrate
php artisan print:token amsterdam

print:token writes the token into PRINTSERVER_TOKENS in your .env and shows the token for the box. With more than one location, also set the administration of this installation:

PRINTSERVER_ADMINISTRATION=amsterdam
PRINTSERVER_TOKENS="amsterdam:amsterdam:3f9a..."

Then queue a job from your application:

use Darvis\Printserver\Services\PrintQueue;

app(PrintQueue::class)->queue('ZEBRA01', $zpl, 'Label order 12345', 'zpl');
app(PrintQueue::class)->queue('PRINTER01', $pdf, 'Packing slip 12345');

And schedule the cleanup, or the disk keeps every document that was ever printed:

Schedule::command('print:cleanup')->daily();

Installation has the full steps, including the box on location.

The endpoints

The box uses four endpoints, all behind a bearer token:

Method	Url	What it does
POST	print/claim	Returns the waiting jobs and marks them claimed in one transaction
GET	print/file/{uuid}	The content of one job
POST	print/done/{uuid}	Printed; the file is dropped
POST	print/failed/{uuid}	Failed, with the reason

A claimed job is never handed out again, and a failed job is not queued again on purpose: better a sheet that does not come out than one that comes out twice.

More than one location

A token is name:administration:token. The administration is the lock: a box of one branch that points at the installation of another gets a 403 instead of its work, and claim only ever returns the jobs of its own administration. Leave the administration out when there is only one. One installation can also serve several locations by giving each printer its administration; see Configuration.

Documentation

• Installation: the application, the box, and how to check it works
• Queueing jobs: the service, formats, and what the printer receives
• The box on location: the agent, its configuration and CUPS
• Configuration: every setting and its .env variable
• How it works: the pull design, the claim lock and what it does not do
• Security: tokens, addresses and what to close on the router
• Troubleshooting: nothing prints, double sheets, and every message
• FAQ: short answers to common questions

License

MIT. See LICENSE.