Customizing Webman Rate Limiter to Return Precise 429 Errors

Overview

The official Webman rate‑limiter component supports annotation‑based limiting and offers APCu, Redis, and memory drivers. Documentation:

https://www.workerman.net/doc/webman/components/rate-limiter.html

.

Interface Rate Limiter

Example controller using the limiter:

class IndexController {
    /**
     * @param Request $request
     * @return Response
     */
    public function sendSms(Request $request): Response {
        $mobile = $request->get('mobile', '1388888888');
        Limiter::check($mobile, 5, 24*60*60, '每个手机号一天最多5条短信');
        return response_json('短信发送成功');
    }
}

Successful request returns HTTP 200 with JSON {"code":0,"message":"短信发送成功","data":[]}. When the limit is exceeded the limiter throws an exception, which the framework turns into a generic HTTP 500 response, not the desired format.

To unify error handling, the Webman exception plugin is enabled by editing config/exception.php:

return [
    // configure exception handler class
    '' => \Tinywan\ExceptionHandler\Handler::class,
];

After enabling the plugin, the exception is still returned as HTTP 500. The required status code is 429 with the message "每个手机号一天最多5条短信".

Modify the controller to catch any throwable and re‑throw a TooManyRequestsHttpException:

use Tinywan\ExceptionHandler\Exception\TooManyRequestsHttpException;

class IndexController {
    /**
     * @param Request $request
     * @return Response
     * @throws TooManyRequestsHttpException
     */
    public function sendSms(Request $request): Response {
        $mobile = $request->get('mobile', '1388888888');
        try {
            Limiter::check($mobile, 5, 24*60*60, '每个手机号一天最多5条短信');
        } catch (\Throwable $throwable) {
            throw new TooManyRequestsHttpException($throwable->getMessage());
        }
        return response_json('短信发送成功');
    }
}

Now the API returns HTTP 429 with JSON

{"code":0,"msg":"每个手机号一天最多5条短信","data":{}}

.

Annotation Rate Limiter

Using annotations simplifies the limit definition. Add the annotation above the method:

use Webman\RateLimiter\Annotation\RateLimiter;

class IndexController {
    /**
     * @param Request $request
     * @return Response
     */
    #[RateLimiter(3, 60, [IndexController::class, 'getMobile'], '每个手机号一天最多5条短信！')]
    public function sendSms(Request $request): Response {
        return response_json('短信发送成功');
    }

    /**
     * @desc Custom key, must be static
     * @return string
     */
    public static function getMobile(): string {
        return request()->get('mobile', '1388888888');
    }
}

Initially the response is still HTTP 500. To produce the correct 429 status, specify the custom exception class in the annotation's fifth argument:

#[RateLimiter(3, 60, [IndexController::class, 'getMobile'], '每个手机号一天最多5条短信！', TooManyRequestsHttpException::class)]
public function sendSms(Request $request): Response {
    return response_json('短信发送成功');
}

After this change, the API returns HTTP 429 with JSON

{"code":0,"msg":"每个手机号一天最多5条短信","data":{}}

, matching the desired behavior.