CRMEB/backend/driver/printer/DEVELOPMENT.md

打印驱动扩展开发指南

概述

打印驱动扩展位于 driver/printer/{Driver}/ 目录，负责对接各类云打印服务（飞鹅云、易联云等），用于订单小票打印。

系统通过 crmeb\services\driver\DriverRegistry 扫描各驱动包的 plugin.json 完成驱动注册。

已有驱动

驱动目录	驱动标识	说明
FeiEYun	—	飞鹅云打印机
YiLianYun	—	易联云打印机

开发步骤

1. 创建驱动目录

mkdir -p driver/printer/{DriverName}

2. 创建 plugin.json

{
    "key": "YourDriver",
    "name": "打印驱动名称",
    "description": "驱动描述",
    "version": "1.0.0",
    "author": "CRMEB",
    "type": "driver",
    "path": "driver/printer/YourDriver",
    "require": {
        "crmeb": "^6.0",
        "php": "^8.0"
    },
    "driver": {
        "name": "打印驱动名称",
        "driver_key": "YourDriver",
        "driver": "YourDriver",
        "icon": "",
        "description": "驱动描述",
        "config_fields": [
            {
                "field": "api_key",
                "label": "API Key",
                "type": "text",
                "required": true,
                "group": "基础配置",
                "tip": "输入说明"
            },
            {
                "field": "api_secret",
                "label": "API 密钥",
                "type": "password",
                "required": true,
                "group": "基础配置"
            },
            {
                "field": "device_sn",
                "label": "设备编号",
                "type": "text",
                "required": true,
                "group": "设备配置",
                "tip": "打印机设备编号（SN）"
            }
        ],
        "help_doc": {
            "title": "使用说明",
            "steps": ["步骤1", "步骤2"],
            "link": "https://example.com"
        }
    }
}

plugin.json driver 子对象字段说明

字段	类型	必填	说明
name	string	✅	驱动名称
driver_key	string	✅	驱动唯一标识
driver	string	✅	驱动目录名（打印驱动按目录名索引）
icon	string	❌	图标
description	string	❌	驱动描述
config_fields	array	❌	配置字段
help_doc	object	❌	帮助文档

顶层字段（key/name/description/version/author/type/path/require）与通用 driver 插件一致，参见 sms/DEVELOPMENT.md 的字段说明表。

3. 创建 Driver.php

<?php
namespace driver\printer\{DriverName};

use crmeb\services\printer\BasePrinter;

/**
 * {DriverName} 打印驱动
 */
class Driver extends BasePrinter
{
    /**
     * 初始化
     * @param array $config
     */
    protected function initialize(array $config): void
    {
        // 初始化配置
    }

    /**
     * 开始打印
     * @return bool|mixed|string
     * @throws \Exception
     */
    public function startPrinter()
    {
        if (!$this->printerContent) {
            return $this->setError('Missing print');
        }
        // 调用打印API
        $response = $this->accessToken->postRequest('http://api.example.com/open/', [
            'content' => $this->printerContent,
            'times' => $this->times,
        ]);
        $res = json_decode($response, true);
        if ($res['msg'] === 'ok') {
            return $res;
        }
        return $this->setError($res['msg']);
    }

    /**
     * 设置打印内容
     * @param string $content 打印内容
     * @param int $times 打印次数
     * @return $this
     */
    public function setPrinterContent($content, $times = 1): self
    {
        $this->times = $times;
        $this->printerContent = $content;
        return $this;
    }
}

4. 验证驱动

use crmeb\services\driver\DriverRegistry;

$drivers = DriverRegistry::scan('printer');                              // 全部打印驱动
$class   = DriverRegistry::getDriverClass('printer', 'your_driver_key'); // 完整类名 driver\printer\YourDriver\Driver

接口规范

必须实现的方法

方法	说明	返回值
startPrinter()	开始打印	bool|mixed|string

打印内容格式

打印内容通常包含以下要素，需按各打印服务商要求的格式组装：

// 小票打印内容示例
<center>**订单小票**</center>
--------------------------------
商品名称      数量    价格
--------------------------------
商品A         1      ¥29.90
商品B         2      ¥19.80
--------------------------------
合计：               ¥69.50
--------------------------------
订单号：ORD202501011234
时间：2025-01-01 10:00:00

典型配置字段

打印驱动通常需要以下配置：

字段	类型	说明
user_id	text	用户ID/开发者ID
app_id	text	应用ID
app_secret	password	应用密钥
device_sn	text	打印机设备编号（SN）
enable_voice	switch	语音播报开关

参考实现

• 飞鹅云打印机 — 飞鹅云API方式
• 易联云打印机 — 易联云API方式