How to Add Annotation‑Based Rate Limiting to Webman Projects

Introduction

The Webman rate‑limiter provides annotation‑based request throttling and supports APCu, Redis, and in‑memory drivers.

Installation

composer require webman/rate-limiter

Usage

Import the annotation classes and apply them to controller methods:

<?php

namespace app\controller;

use Webman\RateLimiter\Annotation\RateLimiter;
use Webman\RateLimiter\Limiter;

/**
 * test‑users
 */
class UserController
{
    #[RateLimiter(limit: 10)]
    public function index(): string
    {
        // default IP limit, 1‑second window
        return '每个ip每秒最多10个请求';
    }

    #[RateLimiter(limit: 100, ttl: 60, key: RateLimiter::UID)]
    public function search(): string
    {
        // limit by user ID (session('user.id') must be set)
        return '每个用户每分钟最多100次搜索';
    }

    #[RateLimiter(limit: 1, ttl: 60, key: RateLimiter::SID, message: '每人每分钟只能发一次邮件')]
    public function sendMail(): string
    {
        // limit by session ID
        return '每人每分钟只能发一次邮件';
    }

    #[RateLimiter(limit: 100, ttl: 24 * 60 * 60, key: 'coupon', message: '今天的优惠券已经发完，请明天再来')]
    public function coupon(): string
    {
        // global key "coupon"
        return '优惠券发送成功';
    }

    public function sendCms(string $mobile): string
    {
        // manual limit using mobile number as key
        Limiter::check($mobile, 5, 24 * 60 * 60, '每个手机号一天最多5条短信');
        return '短信发送成功';
    }

    #[RateLimiter(limit: 5, ttl: 24 * 60 * 60, key: [UserController::class, 'getMobile'], message: '每个手机号一天最多5条短信')]
    public function sendCms2(): string
    {
        return '短信发送成功';
    }

    /**
     * Custom key: get mobile number
     * @return string
     */
    public static function getMobile(): string
    {
        return request()->get('mobile');
    }
}

Configuration

config/plugin/webman/rate-limiter/app.php

<?php
return [
    'enable' => true,
    'driver' => 'auto', // auto, apcu, memory, redis
    'stores' => [
        'redis' => [
            'connection' => 'default',
        ],
    ],
    // IPs listed here bypass rate limiting (effective only for RateLimiter::IP)
    'ip_whitelist' => [
        // '127.0.0.1',
    ],
];

enable : toggle the limiter on or off.

driver : choose auto, apcu, memory or redis. auto picks the best available between APCu and Redis.

stores : Redis connection configuration, referencing the connection name defined in config/redis.php.

ip_whitelist : IP addresses that are exempt from rate limiting when the key is RateLimiter::IP.

Driver Selection

memory

Introduction : No extensions required; offers the best performance.

Usage limits : Limits apply only to the current process; not shared across processes or clusters.

Typical scenarios : Local development, non‑critical throttling, basic CC‑attack mitigation.

apcu

Installation : Requires the apcu PHP extension and enabling it in php.ini (e.g., apc.enabled=1, apc.enable_cli=1).

Introduction : Slightly slower than memory but shares data across processes.

Usage limits : Does not support clustering.

Use cases : Any development environment, single‑node production, or scenarios where moderate sharing is needed.

Find your php.ini location with php --ini if unsure.

redis

Dependencies : Install the Redis PHP extension and the illuminate/redis component via composer require -W illuminate/redis illuminate/events.

Introduction : Lower performance than APCu but supports precise throttling in both single‑node and clustered deployments.

Applicable scenarios : Development, single‑machine production, and clustered environments requiring accurate rate limits.