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.

<?php $ipp->setAuthentification("test","test"); // system username & password, need to be lpadmin $job = $ipp->last_job; // getting job uri $ipp->cancelJob($job); // cancelling job ?>

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,

Job's uri

Needed to CancelJob($job_uri).
Last job uri is in string $ipp->last_job
Can also be found in array $ipp->jobs_uri (1 key by operation);

Availables printers's uris

Found in array $ipp->available_printers, after a call to getPrinters().

getPrinters() is not part of IPP standard, thus it is implemented in (NameOfVendor)PrintIPP.

Printer's attributes

After a call to getPrinterAttributes(), founds in $ipp->printer_attributes.
example:
<?php $ipp = new PrintIPP(); $ipp->setHost("localhost"); $ipp->setPort(); $ipp->setPrinterURI("/printers/epson"); $ipp->getPrinterAttributes(); echo "Printer attributes for printer $i: <pre>\n"; print_r($ipp->printer_attributes); echo "</pre>"; /* Cups defines an attribute "printer -type" */ if (isset($ipp->printer_attributes->printer_type->_value2) && ($ipp->printer_attributes->printer_type->_value2) == 'print-black') echo "The printer can print black<br />\n"; if (isset($ipp->printer_attributes->printer_type->_value3) && ($ipp->printer_attributes->printer_type->_value3) == 'print-color') echo "The printer can print color<br />\n"; /* other attributes */ echo "Printer State: ".$ipp->printer_attributes->printer_state->_value0."<br />\n"; echo "Printer State message: ".$ipp->printer_attributes->printer_state_message->_value0."<br />"; echo "Document formats supported:<br /><pre>"; $pointer = "_value0"; for ($i = 0 ; isset($ipp->printer_attributes->document_format_supported->$pointer); $i++) { echo $ipp->printer_attributes->document_format_supported->$pointer . "\n"; $pointer = "_value" . ($i + 1); } echo "</pre>"; ?>

Job's attributes

After a call to *Job() (except "validateJob"), founds in $ipp->job_attributes.
Parsing: same method than Printer's attributes. see getJobAttributes() operation;

Jobs's attributes

After a call to getJobs(), founds in $ipp->jobs_attributes.
Parsing: same method than Printer's attributes, except that jobs are objects. See "getJobs()" operation for an example.

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.
Examples:
/* standard */ $ipp->setAttribute("job-billing", "Thomas"); /* with 1 set of xxx */ // add a start banner "confidential" and a end banner "secret" // I know, this example is unusual $ipp->setAttribute("job-sheets", array("confidential","secret")); /* special case for resolution: */ // dpi: dot per inch $ipp->setAttribute("printer-resolution","1440x720dpi"); // dpc: dot per centimeter $ipp->setAttribute("printer-resolution","320x200dpc");
setAttributes takes care of attribute-type: you have to enter the text string, comprised 'enum' types.
Will add a separate page to list attributes and parameters, but for starting you cant get most of them by "getPrinterAttributes()" and "getJobAttributes()" :)

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).

cancelJob($job_uri)

cancel job which have uri $uri, as which is given in $ipp->last_job or in array $ipp->jobs_uri ⇒ (one key by operation).

getPrinterAttributes()

Get printer's attributes of printer setted by setPrinterUri($uri), fill object $ipp->printer_attributes. see response parsing.

validateJob()

Verify if the job can be printed with it's attributes before sending document.
Example:
<?php [...] $ipp->setMimeMediaType("application/x-foobar"); echo "Validate-Job: ".$ipp->validateJob()."<br />"; foreach ($ipp->attributes as $name => $attribute) if ($attribute->_range == 'unsupported-attributes') printf('%s "%s": unsupported attribute<br />',$name,$attribute->_value0); reset($ipp->attributes); ?> Displays: Validate-Job: client-error-document-format-not-supported document_format "application/x-foobar": unsupported attribute

getJobAttributes($job_uri,subset="false",$attributes_group="all")

Get attributes from the job $job_uri. If (!$subset), gives $attributes_group="all" by default, or attributes_group = 'job-template' or 'job-description' if you fills third argument. if ($subset), gives only useful subset of attributes.
Example:
<?php [...] echo "Printing Job: ".$ipp->printJob()."<br />"; $ipp->getJobAttributes($ipp->last_job,false,'job-template'); $job_state = $ipp->job_attributes->job_state->_value0; echo "Job-State: $job_state<br />"; $job_state_reasons = $ipp->job_attributes->job_state_reasons->_value0; echo "Job-State-Reasons: $job_state_reasons<br />"; echo "<pre>";print_r($ipp->job_attributes); echo "</pre>"; ?> displays: Job-State: processing Job-State-Reasons: job-printing (or whatever is the job's status) stdClass Object ( [attributes_charset] => stdClass Object ( [_type] => charset [_range] => start operation-attributes [_value0] => utf-8 ) [attributes_natural_language] => stdClass Object ( [_type] => naturalLanguage [_range] => start operation-attributes [_value0] => fr-fr ) [job_uri] => stdClass Object ( [_type] => uri [_range] => start job-attributes [_value0] => http://geekette:631/jobs/202 ) [...]

getJobs($my_jobs=true,$limit=0,$which_jobs="",$subset='true')

get Jobs attribute's, by default only your jobs, except if you set first argument to "false", by default with no limit, except if you gives an integer (0 < x < 65535) in second argument, by default not-completed, excpt if you gives 'completed' as third argument, by default only a usefull subset of attributes, except if you gives 'false' as fourth argument.
Example:
<?php echo "Getting Jobs: ".$ipp->getJobs($my_jobs=true,$limit=0,"completed",true)."<br />"; echo "Job 0 state: ".$ipp->jobs_attributes->job_0->job_state->_value0."<br />"; echo "Job 0 state-reasons: ".$ipp->jobs_attributes->job_0->job_state_reasons->_value0."<br />"; echo "<pre>";print_r($ipp->jobs_attributes); echo "</pre>"; ?> Displays: Getting Jobs: successful-ok-ignored-or-substituted-attributes Job 0 state: processing Job 0 state-reasons: job-printing stdClass Object ( [job_0] => stdClass Object ( [job_more_info] => stdClass Object ( [_type] => uri [_range] => start job-attributes [_value0] => http://geekette:631/jobs/205 ) [job_uri] => stdClass Object ( [_type] => uri [_range] => start job-attributes [_value0] => http://geekette:631/jobs/205 ) [job_printer_up_time] => stdClass Object ( [_type] => integer [_range] => start job-attributes [_value0] => 1136224652 ) [job_name] => stdClass Object ( [_type] => nameWithoutLanguage [_range] => start job-attributes [_value0] => test-utf8.txt ) [job_state] => stdClass Object ( [_type] => enum [_range] => start job-attributes [_value0] => processing ) [job_state_reasons] => stdClass Object ( [_type] => keyword [_range] => start job-attributes [_value0] => job-printing ) ) [job_1] => stdClass Object [...] )

printURI($uri)

Implemented in ExtendedPrintIPP.

Print a single document, which uri is given in argument.

Not implemented in Cups server (OPTIONAL operation).

purgeJobs()

Function implemented in ExtendedPrintIPP

Purge jobs for printer designed by setPrinterUri($uri), for all printers if $uri is "/printers/".
Example:
<?php /* purging jobs for a printer */ $IPP = new ExtendedPrintIPP(); $ipp->setUserName("test"); $ipp->setAuthentification("test","test"); // username & password $ipp->setPrinterURI("ipp://localhost:631/printers/epson"); // Set printer URI here echo "Purge-Jobs: ". $ipp->purgeJobs() ."<br />"; /* purging jobs for all printers */ $ipp->setPrinterURI("ipp://localhost:631/printers/"); // => all printers echo "Purge-Jobs: ". $ipp->purgeJobs() ."<br />"; ?>

createJob()

Function implemented in ExtendedPrintIPP.

IPP Create-Job operation, before sending multi-documents with sendDocument($job); or sendURI($job,$uri).
See sendDocument example.

sendDocument($job_uri,$is_last=false)

Function implemented in ExtendedPrintIPP.

Send a document after a job has been created.
Example:
<?php function __autoload($class_name) { require_once $class_name . '.php'; } $IPP = new ExtendedPrintIPP(); $ipp->debug_level = 3; $ipp->setUserName("test"); $ipp->setCopies(2); $ipp->setAuthentification("test","test"); // username & password. MANDATORY echo "Create-Job: ".$ipp->createJob(). "<br />"; printf("Job is: %s<br />",$job = $ipp->last_job); echo "<pre>";print_r($ipp->job_attributes);echo "</pre>\n"; $ipp->setDocumentName("test-utf8.txt"); $ipp->setData("./testfiles/test-utf8.txt"); echo "Sending document: " . $ipp->sendDocument($job) . "<br />\n"; $ipp->setDocumentName("text string"); $ipp->setData("This is the string of second document"); echo "Sending document: " . $ipp->sendDocument($job,$last=true) . "<br />\n"; // must be refused. Hem: CUPS is very smart, it accepts :) echo "Sending document: " . $ipp->sendDocument($job,$last=true) . "<br />\n"; ?>

sendURI($uri,$job_uri,$is_last=false)

Function implemented in ExtendedPrintIPP.

Send a document after a job has been created.
Example:
<?php $uri = "http://localhost/"; echo "Create-Job: ".$ipp->createJob(). "<br />"; printf("Job is: %s<br />",$job = $ipp->last_job); echo "Sending URI: " . $ipp->sendURI($uri,$job,$last=true) . "<br />\n"; ?>

pausePrinter()

Function implemented in ExtendedPrintIPP.

Pause printer setted by setPrinterURI($uri).

resumePrinter()

Function implemented in ExtendedPrintIPP.

resume (restart) printer setted by setPrinterURI($uri).

holdJob($job_uri,$until='indefinite')

Function implemented in ExtendedPrintIPP.

Holds a job.
$until can be'no-hold','day-time','evening','night','weekend','second-shift','third-shift'.
Example:
<?php echo "printing document: " . $ipp->printJob("test"). "<br />\n"; echo "Holding Job: " .$ipp->holdJob($job,'night'); $ipp->getJobAttributes($ipp->last_job,false,'job-template'); $job_state = $ipp->job_attributes->job_state->_value0; echo "Job-State: $job_state<br />"; $job_state_reasons = $ipp->job_attributes->job_state_reasons->_value0; echo "Job-State-Reasons: $job_state_reasons<br />"; ?>

releaseJob($job_uri)

Function implemented in ExtendedPrintIPP.

Release a pending or holded job.

restartJob($job_uri)

Function implemented in ExtendedPrintIPP.

Restarts a completed job.
Example:
<?php echo "printing document: " . $ipp->printJob("test"). "<br />\n"; sleep (10); $ipp->setAttribute('job-hold-until','weekend'); $ipp->restartJob($ipp->last_job); ?> Will re-print the job in the week-end.

setJobAttributes($job_uri,array($deleted_attributes))

Function implemented in ExtendedPrintIPP.

Modify attributes with values previously setted by various setXXX operations.
Delete attributes which are in array of second argument.
Example:
/* deleting print-quality attribute */ $unset_attributes = array("print-quality"); /* setting copies to 2, printer resolution to 320x200dpi */ $ipp->setCopies(2); $ipp->setAttribute('printer-resolution','320x200dpi'); /* commit changes */ $ipp->setJobAttributes($ipp->last_job,$unset_attributes);

getPrinters()

Function implemented in (NameOfVendor)PrintIPP.

Get availables printers, fill array $ipp->available_printers with printers's uris.
Example:
<?php function __autoload($class_name) { require_once $class_name . '.php'; } $ipp = new CupsPrintIPP; $ipp->getPrinters(); $uri = $ipp->available_printers[0]; $ipp->setPrinterUri($uri); ?>

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.