README

Internet Printing Protocol (IPP) 的 PHP 客户端实现。该实现实现了在 RFC2911 & RFC2910 中定义的原始 IPP 协议，并且可以与任何 IPP 打印机或IPP 打印服务器（如CUPS）一起工作。

此实现的目的是尽可能紧密地遵循 IPP 规范，并以尽可能简单的方式提供对该协议的原始接口。

请注意：当前版本处于开发中，尚未发布稳定版。预计不久将发布稳定版（请参阅项目状态部分）。

安装

最简单的方法是使用 composer 并在 require 部分添加 obray/IPP

"require": {
    "obray/ipp": "dev-master"
}

然后只需运行 composer install 或 composer update。或者，您可以克隆仓库或下载源代码，并按需使用。

用法

使用此实现的最低级方法是创建一个 Printer 对象，并像这样调用 printJob 方法

$printer = new \obray\IPP\Printer(
  {printer-uri},
  {username}, // optional
  {password},    // optional
  {curlOptions} // optional
);
$response = $printer->printJob({raw document}, {attributes});

根据打印机和您要打印的文档，上述方法可能无法提供您期望的结果（例如，将 PDF 打印为纯文本、黑色页面等）。打印机通常只能打印特定的文档格式。要找出您的打印机支持哪些格式，可以列出打印机属性，如下所示

$printer = new \obray\IPP\Printer(
  {printer-uri},
  {username}, // optional
  {password},    // optional
  {curlOptions} // optional
);
$attributes = $printer->getPrinterAttributes();

这将给出类似于以下结构的结构（编码为 JSON）

{
    "versionNumber": "1.1",
    "requestId": 1,
    "statusCode": "successful-ok",
    "operationAttributes": {
        "attributes-charset": "utf-8",
        "attributes-natural-language": "en-us"
    },
    "jobAttributes": null,
    "printerAttributes": {
    
        ...
        
        "document-format-supported": [
            "application\/octet-stream",
            "image\/urf",
            "image\/pwg-raster",
            "application\/pdf",
            "image\/jpeg",
            "application\/postscript",
            "application\/vnd.hp-PCL",
            "text\/plain"
        ],
        
        ...
        
    }
}

要将 PDF 打印到这台打印机，您将这样做

$printer = new \obray\IPP\Printer(
  {printer-uri},
  {username}, // optional
  {password}, // optional
  {curlOptions}, // optional
);
$attributes = $printer->printJob(
   {raw document},
   123, // optional request ID
   [
     'document-format': 'application/pdf'
   ]
);

直接连接到打印机或 CUPS

此库支持直接连接到网络打印机、打印文档或将文档打印到安装了 CUPS 的服务器或计算机。

要直接连接到网络打印机，通常只需获取其主机名并使用如下方式之一

ipp://network.hostname.of.printer
ipp://network.hostname.of.printer/ipp

要使用此库与 cups 一起工作，它的工作方式完全相同，除了通常 URL 是类似于 ipp://hostname.of.cups/ipp/{printer-name-goes-here} 的形式。

要使用此库与 USB 打印机或其他类型的打印机一起工作，您需要使用 CUPS。在安装了 CUPS 的计算机上安装打印机，然后您可以通过此库通过 CUPS 打印到打印机。

要查看其他可用方法，请参阅以下关于打印机对象和方法以及作业对象和方法的文档。

打印机对象和方法

打印机对象根据指定的 URI 定义打印机。当在打印机上调用方法时，它将尝试连接并发送请求，并解释响应。

打印机构造函数

通过指定打印机的URI和（如果需要）凭据来创建一个打印机对象。一旦有了打印机，就可以调用它的方法。

用法

$printer = new \obray\IPP\Printer(
  {printer-uri},
  {username},   // optional
  {password},    // optional
  {curlOptions} // optional
);

方法 `printJob`

RFC 2911 3.2.1：这个必需操作允许客户端提交包含一个文档的打印作业，并供应文档数据（而不是仅提供数据的引用）。

用法

$response = $printer->printJob(
  {raw document},
  {request-id},  // optional
  {[attributes]} // optional
);

方法 `PrintURI`

尚未实现

RFC 2911 3.2.2：这个可选操作与Print-Job操作相同，但客户端使用“document-uri”操作属性（在第1组中）提供对文档数据的URI引用，而不是包含文档数据本身。在返回响应之前，打印机必须验证打印机支持URI隐含的检索方法（例如http、ftp等），并必须检查URI的语法是否有效。如果客户端提供的URI方案不受支持，即该值不在打印机对象的“referenced-uri-scheme-supported”属性中，则打印机对象必须拒绝请求并返回’tclient-error-uri-scheme-not-supported’状态代码。

方法 `validateJob`

RFC 2911 3.2.3：这个必需操作与Print-Job操作类似，但客户端不提供文档数据，打印机也不分配资源（即，它不会创建一个新的作业对象）。此操作仅用于验证打印机对象的功能与客户端在Validate-Job请求中提供的任何属性是否匹配。通过使用Validate-Job操作，客户端可以验证具有相同文档数据的Print-Job操作会被接受。Validate-Job操作还执行与Print-Job操作相同的网络安全协商，以便客户端在执行Print-Job操作之前检查客户端和打印机对象的安全要求是否可以满足。

用法

$response = $printer->validateJob({request-id}, {[attributes]});

方法 `createJob`

尚未实现

RFC 2911 3.2.4：这个可选操作与Print-Job操作类似，但在Create-Job请求中，客户端不提供文档数据或对文档数据的任何引用。此外，客户端也不提供“document-name”、“document-format”、“compression”或“document-natural-language”操作属性。此操作后面跟有一个或多个Send-Document或Send-URI操作。在那些操作请求中的每一个，客户端可选择性地为多文档作业对象中的每个文档提供“document-name”、“document-format”和“document-natural-language”属性。

方法 `getPrinterAttributes`

RFC 2911 3.2.5：这个必需操作允许客户端请求打印机对象的属性值。在请求中，客户端提供一组感兴趣的打印机属性名和/或属性组名。在响应中，打印机对象返回一个相应的属性集，其中填充了适当的属性值。默认情况下，此方法将获取所有可用的属性。

用法

$response = $printer->getPrinterAttributes({request-id});

方法 `getJobs`

RFC 2911 3.2.6：这个必需操作允许客户端检索属于目标打印机对象的作业对象的列表。客户端还可以提供一组作业属性名和/或属性组名（默认情况下包括所有组名）。对于返回的每个作业对象，将返回一个作业对象属性组。

用法

$response = $printer->getJobs({request-id});

方法 `pausePrinter`

RFC 2911 3.2.7：此可选操作允许客户端停止打印机对象在其所有设备上安排作业。根据实现方式，暂停打印机操作还可能停止打印机处理当前作业或多个作业。任何正在打印的作业要么在实现允许的情况下立即停止，要么完成，具体取决于实现。打印机对象必须仍然接受创建操作以创建新作业，但必须防止任何作业进入'处理'状态。

如果支持暂停打印机操作，则必须支持恢复打印机操作，反之亦然。

用法

$response = $printer->pausePrinter({request-id});

方法 `resumePrinter`

RFC 2911 3.2.8：此操作允许客户端恢复打印机对象在其所有设备上安排作业。如果存在，打印机对象必须从打印机对象的"printer-state-reasons"属性中删除'暂停'和'moving-to-paused'值。如果没有其他原因使设备保持暂停（例如介质卡住），IPP打印机可以根据是否有作业需要处理分别自由地转换到'处理'或'空闲'状态，并相应地恢复处理作业。

如果支持暂停打印机操作，则必须支持恢复打印机操作，反之亦然。

用法

$response = $printer->resumePrinter({request-id});

方法 `purgeJobs`

RFC 2911 3.2.9：此可选操作允许客户端从IPP打印机对象中删除所有作业，无论其作业状态如何，包括打印机对象作业历史中的作业（见第4.3.7.2节）。执行Purge-Jobs操作后，打印机对象必须在随后的Get-Job-Attributes和Get-Jobs响应中返回无作业（直到提交新作业）。

清除作业（和获取作业）操作是否以与通过IPP打印机对象提交到设备的作业相同的方式影响从其他来源提交到设备的作业，取决于实现，即IPP协议是否用作通用管理协议或仅用于管理IPP作业。

用法

$response = $printer->purgeJobs({request-id});

作业对象和方法

方法 `sendDocument`

尚未实现

RFC 2911 3.3.1：此可选操作允许客户端创建一个多文档作业对象，该对象最初是"空的"（不包含任何文档）。在创建作业响应中，打印机对象返回作业对象的URI（"job-uri"属性）和作业对象的32位标识符（"job-id"属性）。对于客户端希望添加的每个新文档，客户端使用发送文档操作。每个发送文档请求包含一个文档的全部数据流。

方法 `sendURI`

尚未实现

RFC 2911 3.3.2：此可选操作与发送文档操作（见第3.3.1节）相同，但客户端必须提供URI引用（"document-uri"操作属性）而不是文档数据本身。如果打印机对象支持此操作，客户端可以使用发送URI或发送文档操作将新文档添加到现有的多文档作业对象。但是，如果客户端需要指示上一个发送URI或发送文档是最后一个文档，客户端必须使用不带文档数据的发送文档操作并将"last-document"标志设置为'true'（而不是使用不带"document-uri"操作属性的发送URI操作）。

打印机对象在返回响应之前必须验证提供的URI的语法和URI方案，就像在打印URI操作中一样。IPP打印机可以在操作过程中或之后（见第3.2.2节）验证文档的可用性。

方法 `cancelJob`

RFC 2911 3.3.3：此必需操作允许客户端在打印作业从创建到完成、取消或中止的过程中取消该作业。由于作业可能在收到取消作业请求时已经开始打印，因此在实际终止作业之前，可能已经打印了一些媒体页。

用法

$response = $job->cancelJob({request-id});

方法 `getJobAttributes`

RFC 2911 3.3.4：此必需操作允许客户端请求作业对象的属性值，它与“获取打印机属性”操作（见3.2.5节）几乎相同。唯一的不同之处在于，该操作针对的是作业对象而不是打印机对象，在查询作业对象时没有使用“文档格式”操作属性，并且返回的属性组是一组作业对象属性而不是一组打印机对象属性。

用法

$response = $job->getJobAttributes({request-id});

方法 `holdJob`

RFC 2911 3.3.5：此可选操作允许客户端在队列中挂起待处理的作业，使其不适用于调度。如果支持挂起作业操作，则必须支持释放作业操作，反之亦然。可选的“作业挂起直到”操作属性允许客户端指定是否无限期挂起作业或直到指定的时间段（如果支持）。

用法

$response = $job->holdJob({request-id});

方法 `releaseJob`

RFC 2911 3.3.6：此可选操作允许客户端释放之前挂起的作业，使其再次适用于调度。如果支持挂起作业操作，则必须支持释放作业操作，反之亦然。

此操作从在创建或最近的挂起作业或重启作业操作中提供的作业对象中删除（如果存在）“作业挂起直到”作业属性，并删除其对作业的影响。IPP对象必须从作业的“作业状态原因”属性中删除（如果存在）'作业挂起直到指定的'值。

用法

$response = $job->releaseJob({request-id});

方法 `restartJob`

RFC 2911 3.3.7：此可选操作允许客户端重新启动在处理完成后保留在队列中的作业。

用法

$response = $job->restartJob({request-id});

打印机 URI

每个打印机对象由一个唯一的URI标识，必须在打印机构造函数中提供。以下是几个可能的打印机URI示例

如果您指定IPP作为协议，则假定端口631。或者您可以指定端口号

ipp://hostname/ipp/

ipp://hostname:port/ipp/

ipp://hostname/ipp/port1

如果您的打印机不支持直接IPP，通常可以设置一个CUPS服务器，在那里安装打印机，然后将所有请求发送到CUPS服务器。一个例子可能是这样的

ipp:///printers/{printer-name-in-cups}

在这种情况下，CUPS将安装在本地主机上，并监听端口631（默认IPP端口）。

项目状态

目前，这个库没有稳定的版本，但一旦有，它将完全支持IPP/1.1。其他版本将在未来的版本中得到支持。目前，这个库与每个版本的要求和建议相比的状态如下。

obray / ipp

维护者

详细信息

README

目录

安装

用法

直接连接到打印机或 CUPS

打印机对象和方法

打印机构造函数

用法

方法 printJob

用法

方法 PrintURI

方法 validateJob

用法

方法 createJob

方法 getPrinterAttributes

用法

方法 getJobs

用法

方法 pausePrinter

用法

方法 resumePrinter

用法

方法 purgeJobs

用法

作业对象和方法

方法 sendDocument

方法 sendURI

方法 cancelJob

用法

方法 getJobAttributes

用法

方法 holdJob

用法

方法 releaseJob

用法

方法 restartJob

用法

打印机 URI

项目状态

方法 `printJob`

方法 `PrintURI`

方法 `validateJob`

方法 `createJob`

方法 `getPrinterAttributes`

方法 `getJobs`

方法 `pausePrinter`

方法 `resumePrinter`

方法 `purgeJobs`

方法 `sendDocument`

方法 `sendURI`

方法 `cancelJob`

方法 `getJobAttributes`

方法 `holdJob`

方法 `releaseJob`

方法 `restartJob`