poster-php

字数统计: 3.8k字   |   阅读时长: 20分   |  本文总阅读量0次

poster-php

PHP 图片验证码与海报生成工具包 —— 框架无关核心 + Laravel / ThinkPHP / Webman / Hyperf 适配。

English Documentation | 架构设计图

功能

验证码（三种方式 + 随机切换）

类型 说明
点击验证 click 用户按顺序点击图片上的目标文字
旋转验证 rotate 用户拖动滑块将图片旋转回正确角度
滑块验证 slider 用户拖动拼图块到缺口位置
随机切换 random 随机选取以上三种验证码之一

海报生成

链式 Builder API，支持 14 种元素：

元素 方法 说明
文字 addText() 自动换行，对齐，多行
图片 addImage() 缩放裁剪，圆角，阴影
头像 addAvatar() 圆形裁剪，边框
二维码 addQrcode() 纯 PHP 生成，中心 Logo，底部文案
形状 addShape() 矩形/圆形/圆角，填充/描边
分割线 addLine() 颜色，宽度
水印 addWatermark() 平铺文字，角度，间距
表格 addTable() 表头，斑马纹，列宽
图表 addChart() 柱状图 / 折线图 / 饼图
日历 addCalendar() 月历，高亮日期，标注
艺术字体 addArtisticText() 描边 / 阴影 / 渐变 / 霓虹
Emoji addEmoji() 彩色 emoji 表情渲染
字体图标 addIcon() FontAwesome 图标渲染
颜文字 addEmoticon() 日式颜文字 / 自定义表情

安装

1
composer require erikwang2013/poster-php

系统要求：PHP >= 8.0，GD 扩展。

可选扩展：

  • ext-imagick：ImageMagick 图像驱动（性能更好，功能更强）
  • ext-redis：Redis 验证码存储（分布式部署）

使用说明

一、验证码

1. 点击验证码 (ClickCaptcha)

用户需要按顺序点击图片上的目标文字（如”树””鸟””花”），验证人类操作。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
// 通过辅助函数（框架无关）
$result = captcha_create('click', [
    'difficulty' => 'medium',    // 'easy'(2目标) | 'medium'(3目标) | 'hard'(4目标)
    'background' => null,        // 自定义背景图路径，null=自动生成
]);

// 返回结果
// $result = [
//     'key'   => 'abc123...',           // 验证唯一标识，传给前端
//     'image' => 'data:image/png;base64,...', // 图片 base64
//     'extra' => [
//         'targets' => [
//             ['order' => 1, 'text' => '树', 'x' => 120, 'y' => 80],
//             ['order' => 2, 'text' => '鸟', 'x' => 200, 'y' => 150],
//             ['order' => 3, 'text' => '花', 'x' => 310, 'y' => 95],
//         ],
//     ],
// ];

// 前端根据 targets 渲染提示文字，用户依次点击对应位置
// 前端提交用户点击坐标 [[x1,y1], [x2,y2], [x3,y3]]
$pass = captcha_verify($result['key'], 'click', [[120, 80], [200, 150], [310, 95]]);
// 返回 true / false，容差半径 18px

// 通过 CaptchaManager（完整 API）
use Erikwang2013\Poster\Captcha\CaptchaManager;
use Erikwang2013\Poster\Drivers\DriverFactory;
use Erikwang2013\Poster\Storage\FileStorage;

$manager = new CaptchaManager(DriverFactory::create(), new FileStorage());
$captcha = $manager->create('click')
    ->setDifficulty('hard')
    ->setTargetCount(4)            // 自定义目标数量 1-5
    ->setTargetType('text')        // 'text' 文字 | 'icon' 图标
    ->setBackground('/path/to/bg.jpg');
$result = $captcha->generate();

$pass = $manager->verify($result['key'], [
    'type' => 'click',
    'data' => [[120, 80], [200, 150], [310, 95], [180, 60]],
]);

2. 旋转验证码 (RotateCaptcha)

系统随机旋转图片 30°~330°，用户拖动滑块将图片旋转回正。

1
2
3
4
5
6
7
8
9
10
// 通过辅助函数
$result = captcha_create('rotate');
// $result['extra'] 不含角度（验证答案），前端只展示旋转后的图片

$pass = captcha_verify($result['key'], 'rotate', 185);  // 用户旋转角度，±5° 容差

// 通过 CaptchaManager
$captcha = $manager->create('rotate')
    ->setAngleRange(45, 315)       // 自定义旋转角度范围
    ->generate();

3. 滑块验证码 (SliderCaptcha)

系统从背景切出拼图块并偏移，用户拖动拼图到缺口位置。

1
2
3
4
5
6
7
8
9
10
11
12
// 通过辅助函数
$result = captcha_create('slider');
// $result = [
//     'image' => '...',              // 带缺口的背景图
//     'extra' => [
//         'puzzle'   => '...',        // 拼图块图片
//         'puzzle_w' => 50,           // 拼图宽度
//         'puzzle_h' => 50,           // 拼图高度
//     ],
// ];

$pass = captcha_verify($result['key'], 'slider', 173);  // 用户滑动的 x 像素，±4px 容差

4. 随机切换 (RandomCaptcha)

系统随机从 click / rotate / slider 中选取一种验证码，增加破解难度。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// 通过辅助函数 — 一行代码随机生成
$result = captcha_create('random');
// $result['type'] 返回实际选中的类型: 'click' | 'rotate' | 'slider'

// 前端根据 type 渲染对应的交互组件
switch ($result['type']) {
    case 'click':
        // 渲染点击组件：展示图片，用户依次点击 targets
        break;
    case 'rotate':
        // 渲染旋转组件：展示图片，用户拖动旋转
        break;
    case 'slider':
        // 渲染滑块组件：展示缺口图 + 拼图块
        break;
}

// 验证时传入实际类型和用户操作数据
$pass = captcha_verify($result['key'], $result['type'], $userData);
// click: $userData = [[x1,y1],[x2,y2],...]
// rotate: $userData = 185 (角度)
// slider: $userData = 173 (像素)

// 通过 CaptchaManager
$captcha = $manager->create('random')->generate();
$pass = $manager->verify($captcha['key'], [
    'type' => $captcha['type'],
    'data' => $userData,
]);

验证安全特性

特性 说明
一次性 验证成功/超过最大次数后 key 删除
防暴力 默认最多验证 3 次（可配置）
有效期 默认 300 秒（可配置）
随机性 每次生成的背景颜色、噪声、目标位置均随机

二、海报生成

基础用法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
use Erikwang2013\Poster\Poster\PosterBuilder;
use Erikwang2013\Poster\Drivers\DriverFactory;

// 通过辅助函数
$builder = poster_create(750, 1334);  // 宽×高

// 或直接实例化
$builder = new PosterBuilder(DriverFactory::create());
$builder->width(750)->height(1334);

// 设置背景
$builder->background('#FFFFFF');                            // 纯色背景
$builder->background('/path/to/bg.jpg');                    // 图片背景（自动缩放）
$builder->backgroundGradient('#FF6B6B', '#FF8E53', 'vertical'); // 渐变背景
                                                            // 方向: vertical | horizontal

// 输出
$builder->save('/output/poster.jpg', 90);  // 保存到文件（路径, 质量 0-100）
$dataUrl = $builder->output('png', 90);    // 获取 base64 data URL

文字 addText()

1
2
3
4
5
6
7
8
9
10
11
$builder->addText('新品首发', [
    'x'        => 80,              // 横坐标
    'y'        => 120,             // 纵坐标（基线位置）
    'size'     => 48,              // 字号
    'color'    => '#333333',       // 颜色
    'font'     => '/path/to/font.ttf', // 字体文件，null=GD 内置
    'align'    => 'center',        // left | center | right
    'maxWidth' => 600,             // 最大宽度（自动换行）
    'lineHeight' => 72,            // 行高
    'angle'    => 0,               // 旋转角度
]);

图片 addImage()

1
2
3
4
5
6
7
8
9
10
11
12
13
$builder->addImage('/path/to/product.jpg', [
    'x'      => 75,
    'y'      => 280,
    'width'  => 600,              // 渲染宽度（自动缩放）
    'height' => 600,              // 渲染高度
    'radius' => 12,               // 圆角半径
    'shadow' => [                 // 阴影（可选）
        'color'    => '#00000033',
        'offsetX'  => 4,
        'offsetY'  => 4,
        'blur'     => 10,
    ],
]);

头像 addAvatar()

1
2
3
4
5
6
$builder->addAvatar('/path/to/avatar.jpg', [
    'x'      => 80,
    'y'      => 60,
    'size'   => 120,              // 头像尺寸（正方形）
    'border' => '#FF6B6B',        // 边框颜色（可选）
]);

二维码 addQrcode()

1
2
3
4
5
6
7
8
9
10
$builder->addQrcode('https://example.com/page/123', [
    'x'     => 275,
    'y'     => 1050,
    'size'  => 200,               // 二维码尺寸
    'level' => 'H',               // 容错级别 L | M | Q | H
    'logo'  => '/path/to/logo.png', // 中心 Logo（可选）
    'label' => '扫码查看详情',      // 底部文案（可选）
    'label_size'  => 14,
    'label_color' => '#999999',
]);

形状 addShape()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// 矩形
$builder->addShape('rect', [
    'x' => 0, 'y' => 0, 'width' => 750, 'height' => 60,
    'color'  => '#FF6B6B',
    'filled' => true,             // true=填充 false=描边
    'radius' => 8,                // 圆角半径
    'opacity' => 0.8,             // 透明度 0-1
]);

// 圆形
$builder->addShape('circle', [
    'x' => 100, 'y' => 100, 'width' => 80, 'height' => 80,
    'color' => '#4ECDC4',
]);

分割线 addLine()

1
2
3
4
5
6
$builder->addLine([
    'x1' => 75, 'y1' => 800,
    'x2' => 675, 'y2' => 800,
    'color' => '#EEEEEE',
    'width' => 1,
]);

水印 addWatermark()

1
2
3
4
5
6
7
$builder->addWatermark('CONFIDENTIAL', [
    'size'    => 24,
    'color'   => '#00000020',     // 半透明
    'font'    => '/font.ttf',
    'angle'   => 30,              // 倾斜角度
    'spacing' => 200,             // 间距
]);

表格 addTable()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
$builder->addTable([
    'x'      => 50,
    'y'      => 800,
    'width'  => 650,
    'columns' => [150, 350, 150], // 列宽
    'header'  => ['序号', '项目', '价格'],
    'rows'    => [
        ['1', '商品A', '¥99'],
        ['2', '商品B', '¥199'],
        ['3', '商品C', '¥299'],
    ],
    'headerBg'     => '#333333',
    'headerColor'  => '#FFFFFF',
    'rowBg'        => ['#FFFFFF', '#F5F5F5'], // 斑马纹
    'rowColor'     => '#333333',
    'fontSize'     => 24,
    'cellPadding'  => 10,
]);

图表 addChart()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
// 柱状图
$builder->addChart('bar', [
    ['label' => '一月', 'value' => 120],
    ['label' => '二月', 'value' => 200],
    ['label' => '三月', 'value' => 150],
    ['label' => '四月', 'value' => 300],
], [
    'x' => 50, 'y' => 100, 'width' => 650, 'height' => 400,
    'colors' => ['#FF6B6B', '#4ECDC4', '#45B7D1', '#96CEB4'],
]);

// 折线图
$builder->addChart('line', [
    ['label' => '周一', 'value' => 10],
    ['label' => '周二', 'value' => 35],
    ['label' => '周三', 'value' => 25],
    ['label' => '周四', 'value' => 45],
    ['label' => '周五', 'value' => 30],
], [
    'x' => 50, 'y' => 100, 'width' => 650, 'height' => 400,
    'colors' => ['#FF6B6B'],
]);

// 饼图
$builder->addChart('pie', [
    ['label' => '电商', 'value' => 45],
    ['label' => '社交', 'value' => 25],
    ['label' => '搜索', 'value' => 15],
    ['label' => '其他', 'value' => 15],
], [
    'x' => 75, 'y' => 100, 'width' => 600, 'height' => 600,
    'colors' => ['#FF6B6B', '#4ECDC4', '#45B7D1', '#96CEB4'],
]);

日历 addCalendar()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
$builder->addCalendar([
    'x'     => 50,
    'y'     => 200,
    'year'  => 2026,
    'month' => 5,                   // 1-12
    'cellSize'    => 60,            // 格子大小
    'startDay'    => 0,             // 0=周日 1=周一
    'title'       => '2026年5月',    // 标题（默认自动生成）
    'highlights'  => [              // 高亮日期
        '2026-05-01' => ['bg' => '#FF6B6B', 'text' => '劳动节'],
        '2026-05-16' => ['bg' => '#FFEAA7', 'text' => '今天'],
    ],
    'headerBg'    => '#333333',     // 标题栏背景
    'headerColor' => '#FFFFFF',     // 标题栏文字颜色
    'cellBg'      => '#FFFFFF',     // 格子背景
    'cellBorder'  => '#DDDDDD',     // 格子边框
    'todayBg'     => '#FF6B6B',     // 今天背景色
    'highlightBg' => '#FFF3CD',    // 高亮默认背景色
    'textColor'   => '#333333',     // 日期文字颜色
    'dimColor'    => '#CCCCCC',     // 非本月/空白颜色
]);

艺术字体 addArtisticText()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
// 描边效果
$builder->addArtisticText('SALE', 'stroke', [
    'x' => 80, 'y' => 120, 'size' => 72,
    'color'       => '#FF6B6B',    // 填充颜色
    'strokeColor' => '#000000',    // 描边颜色
    'strokeWidth' => 3,            // 描边宽度
]);

// 阴影效果
$builder->addArtisticText('新品', 'shadow', [
    'x' => 80, 'y' => 120, 'size' => 48,
    'color'         => '#333333',
    'shadowColor'   => '#00000033',
    'shadowOffsetX' => 4,
    'shadowOffsetY' => 4,
]);

// 渐变效果
$builder->addArtisticText('VIP', 'gradient', [
    'x' => 80, 'y' => 120, 'size' => 60,
    'color'  => '#FF6B6B',         // 顶部颜色
    'color2' => '#FF8E53',         // 底部颜色
]);

// 霓虹发光效果
$builder->addArtisticText('HOT', 'neon', [
    'x' => 80, 'y' => 120, 'size' => 56,
    'color'     => '#FF1493',
    'glowColor' => '#FF1493',
]);

Emoji addEmoji()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// 直接使用 emoji 字符
$builder->addEmoji('😀', ['x' => 100, 'y' => 100, 'size' => 64]);
$builder->addEmoji('🎉', ['x' => 180, 'y' => 100, 'size' => 64]);

// 使用 unicode 码点
$builder->addEmoji('', [
    'x' => 100, 'y' => 100, 'size' => 64,
    'codepoint' => 'U+1F600',      // 等同于 😀
]);

// 指定 emoji 字体（需系统支持彩色字体）
$builder->addEmoji('😀', [
    'x' => 100, 'y' => 100, 'size' => 64,
    'font' => '/System/Library/Fonts/Apple Color Emoji.ttc',
]);

系统会自动检测 macOS / Linux / Windows 上的 emoji 字体路径。

字体图标 addIcon()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// 使用内置 FontAwesome 图标名（需提供图标字体文件）
$builder->addIcon('heart', [
    'x' => 20, 'y' => 40, 'size' => 32,
    'color' => '#E74C3C',
    'font'  => '/path/to/fa-solid-900.ttf',  // 必须提供 FontAwesome TTF 字体
]);

$builder->addIcon('star',  ['x' => 60, 'y' => 40, 'color' => '#F39C12', 'font' => '/path/to/fa-solid-900.ttf']);
$builder->addIcon('check', ['x' => 100, 'y' => 40, 'color' => '#27AE60', 'font' => '/path/to/fa-solid-900.ttf']);

// 使用自定义 unicode 码点
$builder->addIcon('', [
    'x' => 20, 'y' => 40, 'size' => 32,
    'codepoint' => '\\u{F3C5}',    // map-marker
    'color' => '#E74C3C',
    'font' => '/path/to/fa-solid-900.ttf',
]);

// 内置图标名列表
// heart, star, user, clock, home, cog, check, times, search,
// envelope, phone, camera, play, pause, shopping-cart, tag,
// map-marker, calendar, comment, share, download, upload,
// lock, globe, link, image, music, video, bell, bookmark,
// thumbs-up, eye, trash, edit, plus, minus, arrow-*,
// location-dot, fire, gift, rocket

颜文字 addEmoticon()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// 使用内置颜文字
$builder->addEmoticon('happy', ['x' => 20, 'y' => 40, 'size' => 24]);
// 渲染: (｡•̀ᴗ-)✧

$builder->addEmoticon('love',  ['x' => 20, 'y' => 80, 'size' => 24]);
// 渲染: (♡°▽°♡)

$builder->addEmoticon('cry',   ['x' => 20, 'y' => 120, 'size' => 24]);
// 渲染: (╥﹏╥)

// 自定义表情文字
$builder->addEmoticon('', [
    'x' => 20, 'y' => 40, 'size' => 24,
    'text' => '(╯°□°）╯︵ ┻━┻',    // 自定义文字
    'color' => '#333333',
]);

// 内置颜文字表达式
// happy, love, cry, angry, surprised, cool, sleepy,
// wave, think, shrug, tableflip, lenny

三、模板系统

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
use Erikwang2013\Poster\Poster\PosterTemplate;

// 定义模板（JSON 可序列化）
$template = PosterTemplate::fromConfig([
    'width'  => 750,
    'height' => 1334,
    'elements' => [
        ['type' => 'shape', 'color' => '#FF6B6B', 'x' => 0, 'y' => 0, 'width' => 750, 'height' => 300],
        ['type' => 'text', 'text' => '{{title}}', 'x' => 80, 'y' => 100, 'size' => 48, 'color' => '#FFFFFF'],
        ['type' => 'text', 'text' => '{{subtitle}}', 'x' => 80, 'y' => 180, 'size' => 28, 'color' => '#FFE0E0'],
        ['type' => 'image', 'src' => '{{cover}}', 'x' => 75, 'y' => 350, 'width' => 600, 'height' => 600, 'radius' => 12],
        ['type' => 'qrcode', 'content' => '{{url}}', 'x' => 275, 'y' => 1050, 'size' => 200, 'label' => '扫码查看详情'],
    ],
]);

// 使用模板 + 变量渲染
$builder->useTemplate($template)->with([
    'title'    => '新品首发',
    'subtitle' => '限时特惠 · 买一送一',
    'cover'    => '/path/to/product.jpg',
    'url'      => 'https://m.example.com/product/123',
])->save('/output/poster.jpg');

// 模板支持的元素类型: text, image, qrcode, avatar, shape, line, watermark, table,
//                      chart, calendar, artistic-text, emoji, icon, emoticon

框架集成

Laravel

1
2
3
4
5
use Erikwang2013\Poster\Adapters\Laravel\Facades\Captcha;
use Erikwang2013\Poster\Adapters\Laravel\Facades\Poster;

$result = Captcha::create('click')->generate();
Poster::width(750)->height(1334)->background('#FFF')->save('poster.jpg');
1
php artisan vendor:publish --tag=poster-config

ThinkPHP

config/web.php:

1
2
3
4
'services' => [
    Erikwang2013\Poster\Adapters\ThinkPHP\CaptchaService::class,
    Erikwang2013\Poster\Adapters\ThinkPHP\PosterService::class,
],

Webman

config/bootstrap.php:

1
2
3
4
return [
    Erikwang2013\Poster\Adapters\Webman\CaptchaPlugin::class,
    Erikwang2013\Poster\Adapters\Webman\PosterPlugin::class,
];

Hyperf

通过 ConfigProvider 自动注册。

配置

见 config/poster.php，支持 .env 覆盖（参考 .env.example）。

目录结构

1
2
3
4
5
6
7
8
src/
├── Captcha/        # 验证码模块
├── Poster/         # 海报模块
│   └── Elements/   # 14 种渲染元素
├── Drivers/        # 图像驱动（GD / ImageMagick）
├── Qrcode/         # 纯 PHP 二维码生成器
├── Storage/        # 验证数据存储（File / Session / Redis）
└── Adapters/       # 框架适配层

开源不易，欢迎支持

微信 支付宝
微信 支付宝

License

MIT License — Copyright (c) 2026 erik erik@erik.xyz — https://erik.xyz

本文作者： 艾瑞可erik
本文链接： https://erik.xyz/open/poster-php.html
版权声明： 本作品采用 知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议 进行许可。转载请注明出处！
赏

一只PHP开发的程序猿，偶尔搞搞摄影、画画、写作、顺便睡觉。

支付宝
微信

扫一扫，分享到微信

微信分享二维码

tag:

    缺失模块。
    1、请确保node版本大于6.2
    2、在博客根目录（注意不是yilia根目录）执行以下命令：
    npm i hexo-generator-json-content --save

    3、在根目录_config.yml里添加配置： 

      jsonContent:
    meta: false
    pages: false
    posts:
      title: true
      date: true
      path: true
      text: false
      raw: false
      content: false
      slug: false
      updated: false
      comments: false
      link: false
      permalink: false
      excerpt: false
      categories: false
      tags: true

<ul> <li>介绍：已有十多年开发经验，主要语言PHP、Web、Go、Java、Python等，有涉及R、Rust、Ruby。 最大的收获就是学好一门语言，其他的更好学。</li> <li>站长：艾瑞可erik</li> <li>邮箱：erik@erik.xyz</li></ul>