Build a Scalable Distributed Captcha Login with PHP Webman and Redis

Overview

Front‑end/back‑end separation in modern web applications makes the classic session‑based captcha unsuitable for distributed or micro‑service deployments. This guide shows a high‑performance, secure distributed captcha login built on the PHP Webman framework using the open‑source tinywan/captcha plugin.

Why a Distributed Captcha Login?

Traditional captcha stores the verification text in the server session, tightly coupling UI and API and preventing horizontal scaling. By moving the captcha state to Redis and using a token‑based authentication flow, the system gains:

Scalability across multiple nodes

Cross‑origin support

Improved security (no session fixation, key‑based verification)

Traditional Captcha Scheme

Generation

Front‑end requests a captcha.

Back‑end creates an image, stores the text in the session.

Image is returned to the front‑end for display.

Verification

User submits username, password, and captcha text.

Back‑end reads the stored text from the session and compares it.

On success the server redirects the user.

This works for monolithic apps but breaks when the UI and API are decoupled.

Distributed Captcha Solution

Generation Process

Front‑end requests a captcha.

Back‑end generates the image and text, stores the text in Redis with a unique key.

Base64‑encoded image and the key are returned to the front‑end.

Redis guarantees consistency across distributed nodes.

Verification Process

User submits username, password, captcha text, and the previously received key.

Back‑end fetches the stored text from Redis using the key and validates it.

If validation succeeds, a JWT (or other) token is returned; otherwise an error is sent.

The front‑end includes the token in subsequent API calls.

This design fully decouples UI from API, making it suitable for micro‑services and cloud deployments.

Project Example with Webman

The example integrates tinywan/captcha, which generates Base64 images without writing files.

Installation

composer require tinywan/captcha

Ensure the PHP environment has the GD or Imagick extension for image generation.

Generating a Captcha

Call Captcha::base64() to obtain a Base64 image and a unique key:

<?php
declare(strict_types=1);

namespace app\home\v1\controller;

use support\Request;
use support\Response;

class IndexController
{
    public function captcha(Request $request): Response
    {
        $captcha = \Tinywan\Captcha\Captcha::base64();
        return json($captcha);
    }
}

Requesting http://127.0.0.1:8288/home/v1/index/captcha returns JSON similar to:

{
  "key": "$2y$10$3bSPqTNT33WdwOQnG7TXQOfqlTBJKhv5AwcDFrQZQxuGKVArJcszy",
  "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

key

: unique identifier for later verification. base64: image data that can be embedded directly in an <img src="..."> tag.

Example image preview:

Verifying the Captcha

In the login endpoint use Captcha::check($code, $key):

use Tinywan\Captcha\Captcha;

$code = $request->get('code'); // user‑entered captcha
$key  = $request->get('key');  // key from generation step
if (false === Captcha::check($code, $key)) {
    return '验证码错误';
}
return '验证码正确'; // proceed to generate JWT token, etc.

After successful verification, issue a JWT token to achieve stateless authentication.

Summary

High Availability : Redis ensures captcha consistency across distributed nodes.

Security : Base64 avoids filesystem exposure; the key prevents forgery.

Easy Integration : Webman’s coroutine model makes generation and verification fast.

Front‑End/Back‑End Decoupling : UI handles presentation, API focuses on business logic.

Source code and plugin are available at https://github.com/Tinywan and the Workerman plugin repository https://www.workerman.net/plugin/33.