phpqrcode png参数如何设置？

PHP QR Code 是一个非常流行的、用纯 PHP 编写的二维码生成库，它主要通过 QRcode::png() 这个静态方法来生成并直接输出 PNG 格式的二维码图片。

核心方法签名

我们来看一下 QRcode::png() 方法的基本结构：

QRcode::png(
    string $text,
    ?string $outfile = null,
    int $level = QR_ECLEVEL_L,
    int $size = 3,
    int $margin = 4,
    bool $saveandprint = false,
    int $structured = 0,
    int $blocksize = 1,
    int $border = 4,
    bool $cmyk = false
)

下面,我们将逐一解释这些参数，特别是那些与最终 PNG 图片外观和功能直接相关的参数。

参数详解

$text (必需)

• 类型: string
• 说明: 这是你要编码生成二维码的文本内容，可以是网址、文本、电子邮件地址等任何信息。
• 示例: 'https://www.example.com'

$outfile (可选)

• 类型: string 或 null
• 默认值: null
• 说明: 这个参数决定了二维码的输出方式。
  • 如果设置为 null (默认): 函数会直接将生成的 PNG 图片输出到浏览器，当你直接访问一个包含此代码的 PHP 文件时，浏览器会下载或显示一个二维码图片。
  • 如果设置为一个文件路径 ('qrcode.png'): 函数会将二维码图片保存到服务器的指定路径，而不会在浏览器中显示。注意：如果文件已存在，它将被覆盖，确保 PHP 进程对该目录有写入权限。
• 示例:
  • 直接输出: QRcode::png($text);
  • 保存到文件: QRcode::png($text, './my_qr_codes/image.png');

$level (可选) - 容错级别

• 类型: int
• 默认值: QR_ECLEVEL_L (对应的值是 0)
• 说明: 这个参数定义了二维码的容错能力，即当二维码部分被遮挡或损坏时，依然能被正确扫描的能力，容错级别越高，二维码上用于存储数据的“模块点”就越多，二维码也越复杂。
  • QR_ECLEVEL_L (Level L, 约 7%): 低容错。
  • QR_ECLEVEL_M (Level M, 约 15%): 中等容错 (默认值，是一个很好的平衡点)。
  • QR_ECLEVEL_Q (Level Q, 约 25%): 较高容错。
  • QR_ECLEVEL_H (Level H, 约 30%): 最高容错。
• 如何使用: 你需要从库中定义的常量来指定。
  • use Endroid\QRCode\ErrorCorrectionLevel; (如果使用新版)
  • 或者直接使用 QRcode::png($text, null, QR_ECLEVEL_H); (使用旧版常量)
• 建议: 对于大多数场景，M 或 H 是不错的选择，特别是当二维码可能被打印在小尺寸或容易被刮花的材质上时。

$size (可选) - 模块大小

• 类型: int
• 默认值: 3
• 说明: 这个参数定义了二维码中每个“小黑点”（模块）的像素大小，数值越大，二维码的整体尺寸也越大，图片也越清晰。
• 示例:
  • $size = 3: 每个点是 3x3 像素。
  • $size = 5: 每个点是 5x5 像素，二维码会更大。
• 注意: 不要设置得太小，否则可能难以扫描；也不要设置得太大，否则图片文件体积会急剧增加。

$margin (可选) - 空白边距

• 类型: int
• 默认值: 4
• 说明: 这个参数定义了二维码图像四周的空白边距大小，单位是模块的数量（不是像素），设置一个合适的边距有助于扫描设备识别二维码的边界。
• 示例: $margin = 4 表示二维码四周有 4 个模块宽的空白区域。

$saveandprint (可选)

• 类型: bool
• 默认值: false
• 说明: 这个参数与 $outfile 配合使用。
  • true: $outfile 被设置为一个文件路径，二维码会先被保存到文件，然后再同时输出到浏览器。
  • false (默认): 只根据 $outfile 的设置进行一种输出（保存或显示）。
• 用途: 适用于需要同时保存到服务器并让用户下载的场景。

高级参数 (通常使用默认值即可)

$structured (可选)

• 类型: int
• 默认值: 0
• 说明: 用于生成结构化二维码（通常是二维码叠加），非常用场景，保持默认值 0。

$blocksize (可选)

• 类型: int
• 默认值: 1
• 说明: 控制块大小，用于某些特殊二维码格式，保持默认值 1 即可。

$border (可选)

• 类型: int
• 默认值: 4
• 说明: 控制边框，功能与 $margin 类似，保持默认值即可。

$cmyk (可选)

• 类型: bool
• 默认值: false
• 说明: 是否输出为 CMYK 模式。false 表示输出为标准的 RGB 模式，CMYK 主要用于印刷，如果你只是用于屏幕显示或普通打印，保持 false 即可。

完整示例代码

示例 1：直接输出到浏览器（最常用）

<?php
// 引入自动加载文件（如果你使用 Composer 安装）
require 'vendor/autoload.php';
// 如果你没有使用 Composer，可以直接引入核心文件
// require_once 'path/to/qrlib.php';
// 1. 准备要编码的文本
$data = 'https://www.php.net/';
// 2. 定义生成参数
$params = [
    'level' => QR_ECLEVEL_H, // 高容错
    'size'  => 10,           // 模块大小为10像素
    'margin'=> 2,            // 边距为2个模块
];
// 3. 直接生成并输出PNG到浏览器
// 注意：确保此PHP文件没有被其他HTML内容包裹
QRcode::png($data, null, $params['level'], $params['size'], $params['margin']);
?>

将上面的代码保存为 generate_qr.php，然后用浏览器访问这个文件，就会看到一个二维码图片。

示例 2：保存到服务器文件

<?php
require 'vendor/autoload.php';
// require_once 'path/to/qrlib.php';
$data = 'Hello, this is a test QR code saved to a file!';
$filePath = './output/my_qr_code.png';
// 检查目录是否存在，如果不存在则创建
$directory = dirname($filePath);
if (!is_dir($directory)) {
    mkdir($directory, 0777, true);
}
// 生成二维码并保存到文件
// 注意：outfile参数不为null，就不会输出到浏览器
QRcode::png($data, $filePath, QR_ECLEVEL_M, 5, 4);
if (file_exists($filePath)) {
    echo "二维码已成功保存到: " . realpath($filePath);
} else {
    echo "保存失败，请检查目录权限。";
}
?>

通过组合这些参数,你可以完全控制生成 PNG 二维码的外观和用途，对于大多数应用场景，重点关注 $text, $level, $size, 和 $margin 这几个参数就足够了。