PHP PrintIPP usage

Introduction

PHP PrintIPP is a PHP5 class library. It is designed to easier usage of Internet Printing Protocol.

It makes easy simple actions like print and cancel a document, and not difficult complex tasks as print a text document on 2 pages per sheet, dual sided, with staples on center (provided your printer and print server does).

Basic usage

As we said, simple things are simple:

<?php require_once(PrintIPP.php); $ipp = new PrintIPP(); $ipp->setHost("localhost"); $ipp->setPrinterURI("/printers/epson"); $ipp->setData("./testfiles/test-utf8.txt"); // Path to file. $ipp->printJob(); ?>

You can replace filename by a string.

A little more

Now, we making little more complex tasks:

<?php /* printing an utf-8 file, two-sided, two pages per sheet */ require_once(PrintIPP.php); $ipp = new PrintIPP(); $ipp->setHost("localhost"); $ipp->setPrinterURI("/printers/epson"); $ipp->debug_level = 3; // Debugging very verbose $ipp->setLog('/tmp/printipp','file',3); // logging very verbose $ipp->setUserName("foo bar"); // setting user name for server $ipp->setDocumentName("testfile with UTF-8 characters"); $ipp->setCharset('utf-8'); $ipp->setAttribute('number-up',2); $ipp->setSides() // by default: 2 = two-sided-long-edge // other choices: 1 = one-sided // 2CE = two-sided-short-edge $ipp->setData("./testfiles/test-utf8.txt");//Path to file. echo sprintf(_("Job status: %s"), $ipp->printJob()); // Print job, display job status $ipp->printDebug() // display debugging output ?>
<?php /* printing selected pages from document */ $ipp->setDocumentName("Selected parts of GNU FDL"); $ipp->setAttribute('number-up',4); // 4 pages per sheet $ipp->setAttribute('media','A7'); // very little pages $ipp->setPageRanges('1:2 5:6'); // print only pages 1 to 2 and 5 to 6 $ipp->setData("./documentation/COPYING");//Path to file. $ipp->printJob(); $ipp->setPageRanges(''); // reset page ranges ?>
<?php /* printing strings, no form feed */ $ipp->setRawText(); $ipp->unsetFormFeed(); $ipp->setData("This is a line\n"); $ipp->printJob(); $ipp->setData("This is half a line "); $ipp->printJob(); $ipp->setData("This is a end of line\n"); $ipp->printJob("epson"); // set copies to 2 (same sheet of paper: form feed is unset) $ipp->setData("This lines must appeared twice\r\n"); $ipp->setCopies(2); $ipp->printJob(); $ipp->setCopies(1); // printing string, then form feed $ipp->setFormFeed(); $ipp->setData("End of test"); $ipp->printJob(); $ipp->setBinary(); // reset to normal use echo "Jobs URIs:"; // display jobs uris echo "<pre>\n"; print_r($ipp-<jobs_uri); echo "</pre>"; ?>

Raw text is not usable for laser printers.

Response parsing

Operation's status

Returned by operations functions.
Can also be found in array $ipp->status (1 key by operation).

Operations functions returns false in case of HTTP error,

Functions reference

Setup

setPort($port='631')

Select port which IPP server listen. By default port is setted to IANA assigned port (631).

setHost($host='localhost')

Select host which is located IPP server (IP or resolvable hostname/FQDN). Mandatory.

setPrinterUri($uri)

Select printer.
/* examples */ $ipp->setPrinterUri('/printers/epson'); $ipp->setPrinterUri('ipp://localhost:631/printers/epson')
Mandatory, automatically done by CupsPrintIPP if not set.

setData($data)

string to be printed or filename of a readable file. Mandatory for printing operations PrintJob() & sendDocument().

setRawText()

Force data to be interpreted as raw text, and be sent directly to printer. It prepends a "SYN" and postpend a "Form Feed" characters to the data or file.

Can be used only on dot-matrix and ink-jet printers.

unsetRawText()

Unset previous operation (setRawText()).

setBinary()

Alias for unsetRawText().

setFormFeed()

When rawText is set, forces a form feed after printing. Automatically set at setRawText() call.

unsetFormFeed()

Causes not form feed in RawText mode.

Must be called after each occurence of setRawText.

setCharset($charset)

Set request's charset. Automatically setted to "us-ascii" if not set.

setLanguage($language)

Set request's natural language. Automatically setted to "en_us" if not set.

setMimeMediaType($mime_media_type='application/octet-stream')

Set type of document. By default: application/octet-stream ⇒ autodetection.

setCopies($nbrcopies=1)

Set number of copies.

setDocumentName($document_name)

Set document name (as for title page).

setJobName($jobname='(PHP)',$absolute=false)

Set job name. If $absolute is not 'true' (default), a count is automatically appended (MMDDHHMMSScount).

setUserName($username='PHP-SERVER')

Set user name as displayed on server and title pages. Automatically set to "PHP-SERVER" if not.

setAuthentification($username,$password)

Set system user name and password when server needs authentification for operation. (e.g. cancelJob() on CUPS with standard settings).

You need to install SASL to use authentification. See INSTALL

setSides($sides=2)

Set sides on printed document.
Possibles values are:
1: one-sided
2: two-sided-long-edge
2CE: two-sided-short-edge

setFidelity()

If printer can't respect all attributes, do not print.

unsetFidelity()

Print anyway (replace attributes as needed), after a call to setFidelity ().

setMessage($message)

Set message given to user, especially with CancelJob().

Cups does not reply this message

setPageRanges($page_ranges)

Set ranges of pages to be printed. $page_ranges == string, e.g.:" 1-2 5-6 8-14".

an empty string resets page-ranges.

setAttribute($attribute,$value)

For attributes which have not dedicated function. $attribute and $value are the correspondent text strings in RFC2911. Returns false on failure.

unsetAttribute($attribute)

Unset given attribute for next jobs, for attributes which have not dedicated function.

Operations

printJob()

Print a single string or document, previously setted by setdata($data).

Logging / debugging

setLog($log_destination,$destination_type='file',$level=2)

$destination_type can be "file", "logger", "e-mail".
$log_destination is a (new) writeable file in a writeable directory, or e-mail.
$level is
0 ⇒ quiet;
1 to 3 ⇒ less to more verbose.

printDebug()

Display debugging informations.
Verbosity setted from 0 to 3 in $ipp->debug_level.

getDebug()

Returns debugging informations.
Verbosity setted from 0 to 3 in $ipp->debug_level.