PHPackages                             phgors/gocaptcha - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. phgors/gocaptcha

ActiveLibrary[Image & Media](/categories/media)

phgors/gocaptcha
================

PHP 行为验证码库（点选/滑动/旋转），go-captcha 生态 PHP 后端实现

v1.0.0(today)00Apache-2.0PHPPHP >=7.4CI passing

Since Jun 18Pushed todayCompare

[ Source](https://github.com/phgors/gocaptcha)[ Packagist](https://packagist.org/packages/phgors/gocaptcha)[ Docs](https://github.com/phgors/gocaptcha)[ RSS](/packages/phgors-gocaptcha/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (1)Versions (2)Used By (0)

phgors/gocaptcha
================

[](#phgorsgocaptcha)

PHP 行为验证码库（点选 / 滑动 / 旋转），[go-captcha](https://github.com/wenlng/go-captcha) 生态的 PHP 后端实现。 基于 GD，开箱即用，纯无状态，框架无关，内置默认字体 / 背景 / 拼图素材。

> 📖 **完整文档**：[docs/usage.md](docs/usage.md)（环境要求 / 快速开始 / 三种验证码详解 / 配置参考 / 素材规范 / 前端对接 / 框架集成 / FAQ / API 速查）

特性
--

[](#特性)

- **点选验证码**：文本点选与图形点选双模式，含主图 + 缩略图
- **滑动验证码**：基本模式与区域拖拽模式，支持任意拼图素材
- **旋转验证码**：圆形缩略图角度对齐
- **纯无状态**：所有校验器为静态纯函数，答案由调用方存 Session / Cache
- **内置素材**：自带字体、背景图、拼图套件，零配置即可生成
- **PHP 7.4+**，仅依赖 `ext-gd`（建议启用 FreeType）

安装
--

[](#安装)

```
composer require phgors/gocaptcha
```

要求：PHP >= 7.4，`ext-gd`（建议启用 FreeType 以支持中文字符渲染）。

点选验证码
-----

[](#点选验证码)

```
use Phgors\GoCaptcha\Click\ClickBuilder;
use Phgors\GoCaptcha\Assets\DefaultAssets;
use Phgors\GoCaptcha\Click\ClickValidator;

$captcha = ClickBuilder::make()
    ->setBackgrounds(DefaultAssets::backgrounds())
    ->setFonts(DefaultAssets::fonts())
    ->setChars(DefaultAssets::chineseChars())
    ->build();

$data = $captcha->generate();

// 返回给前端
$payload = $data->toArray(); // ['masterImage' => ..., 'thumbImage' => ...]
// $data->getDots() 自行存 Session / Cache 作为答案

// 校验（下一次请求，用户点击的点）
$ok = ClickValidator::validate($storedDots, $userPoints, $padding = 10);
```

图形点选模式使用 `buildShape()`，并通过 `setShapes()` 传入图形映射。

滑动验证码
-----

[](#滑动验证码)

```
use Phgors\GoCaptcha\Slide\SlideBuilder;
use Phgors\GoCaptcha\Slide\GraphImage;
use Phgors\GoCaptcha\Assets\DefaultAssets;
use Phgors\GoCaptcha\Slide\SlideValidator;

$graphs = array_map(function ($dir) {
    return new GraphImage("$dir/overlay.png", "$dir/mask.png", "$dir/shadow.png");
}, DefaultAssets::tileSets());

$captcha = SlideBuilder::make()
    ->setBackgrounds(DefaultAssets::backgrounds())
    ->setGraphs($graphs)
    ->build(); // 或 ->buildRegion() 区域拖拽模式

$data = $captcha->generate();
$payload = $data->toArray();     // masterImage + tileImage
$block = $data->getBlock();      // 存 Session / Cache

$ok = SlideValidator::validate($block, $userX, $userY, $padding = 5);
```

旋转验证码
-----

[](#旋转验证码)

```
use Phgors\GoCaptcha\Rotate\RotateBuilder;
use Phgors\GoCaptcha\Assets\DefaultAssets;
use Phgors\GoCaptcha\Rotate\RotateValidator;

$captcha = RotateBuilder::make()
    ->setBackgrounds(DefaultAssets::backgrounds())
    ->build();

$data = $captcha->generate();
$payload = $data->toArray();
$angle = $data->getBlock()->getAngle(); // 存 Session / Cache

$ok = RotateValidator::validate($angle, $userAngle, $padding = 8);
```

配置
--

[](#配置)

每种验证码通过 `with*()` 方法构造不可变的 Options 对象，再用 `setOptions()` 注入 Builder。 下面给出常用项，完整选项见 `src/` 下各 `*Options.php` 的默认值。

```
use Phgors\GoCaptcha\Click\ClickOptions;
use Phgors\GoCaptcha\Base\Size;
use Phgors\GoCaptcha\Base\RangeVal;

$options = (new ClickOptions())
    ->withImageSize(new Size(300, 220))        // 主图尺寸
    ->withThumbSize(new Size(150, 40))         // 缩略图尺寸
    ->withRangeLen(new RangeVal(4, 5))         // 生成字符个数范围
    ->withRangeVerifyLen(new RangeVal(2, 4))   // 需点击个数范围
    ->withRangeSize(new RangeVal(26, 34))      // 字号范围
    ->withDisplayShadow(true);                 // 文字阴影

$captcha = ClickBuilder::make()
    ->setBackgrounds(DefaultAssets::backgrounds())
    ->setFonts(DefaultAssets::fonts())
    ->setChars(DefaultAssets::chineseChars())
    ->setOptions($options)
    ->build();
```

`SlideOptions` 提供 `withImageSize`、`withRangeGraphSize`、`withGraphNumber`、 `withEnableGraphVerticalRandom`；`RotateOptions` 提供 `withImageSquareSize`、 `withThumbSquareSize`、`withRangeAngle`、`withThumbAlpha`。

自定义素材
-----

[](#自定义素材)

有两种方式：

1. **替换默认目录中的文件**：把素材放入 `resources/fonts`（`.ttf` / `.otf` 自动加载）、 `resources/backgrounds`（`.jpg`）、`resources/tiles//`（`overlay.png` / `mask.png` / `shadow.png`）， `DefaultAssets` 会自动发现。
2. **传入绝对路径**：直接把素材路径数组传入对应 Builder 的 setter， 或构造自定义 `AssetLoader` 指向自己的资源目录。

协议
--

[](#协议)

- 本库源码：**Apache-2.0**
- 内置字体（Noto Sans SC）：**SIL Open Font License 1.1**，声明见 `resources/fonts/LICENSE-OFL.txt`

依据 OFL 条款，字体的版权声明与许可证全文随字体一同再分发。

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance100

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity33

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

0d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/102591402?v=4)[Phgors](/maintainers/phgors)[@phgors](https://github.com/phgors)

---

Top Contributors

[![phgors](https://avatars.githubusercontent.com/u/102591402?v=4)](https://github.com/phgors "phgors (53 commits)")

---

Tags

phpgdcaptcharotate captchaslide-captchago-captchaclick-captchabehavioral-captcha

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/phgors-gocaptcha/health.svg)

```
[![Health](https://phpackages.com/badges/phgors-gocaptcha/health.svg)](https://phpackages.com/packages/phgors-gocaptcha)
```

###  Alternatives

[stefangabos/zebra_image

A single-file, lightweight PHP library designed for efficient image manipulation featuring methods for modifying images and applying filters

138115.5k7](/packages/stefangabos-zebra-image)[nikkanetiya/laravel-color-palette

Laravel Wrapper for `ksubileau/color-thief-php`. Grabs the dominant color or a representative color palette from an image. Uses PHP and GD or Imagick.

3312.7k](/packages/nikkanetiya-laravel-color-palette)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)