Auth Captcha Laravel Package

Getting Started

This release targets Laravel 9+ only, so before anything else confirm your app's framework version:

php artisan --version   # must be 9.x or newer
composer show | grep -i <package-name>

Install/upgrade:

composer require <vendor>/<package>:^3.0

First place to look after installing is the package's published config (php artisan vendor:publish --provider="<Vendor>\<Package>\ServiceProvider" --tag=config) — the new rate-limiting parameters in 3.0.0 are configured there. Read the config block end-to-end before wiring anything, because defaults changed shape between majors.

First use case: the simplest end-to-end path is a single route or artisan command that exercises the package's primary feature, with the rate limit left at its default. Verify that works before layering the limiter into production endpoints.

Upgrade order for existing 2.x users: bump Laravel first, then the package, then republish the config and diff it against your existing copy rather than overwriting it.

Implementation Patterns

Config-driven limits over hardcoded values. The new rate-limiting parameters should be read from config in your service layer, not passed inline at every call site. That keeps per-environment tuning (local vs production) possible without code changes.

Layered limiting. If your application already has RateLimiter::for() definitions in a service provider, decide which layer owns the limit. Running package-level limiting alongside middleware-level limiting produces confusing 429s — pick one authoritative source and document it.

Feature-flag the upgrade. For multi-service deployments, ship 3.0.0 behind a config flag so you can flip between old and new limiting behavior without a redeploy:

'limiting' => [
    'enabled' => env('PACKAGE_RATE_LIMIT_ENABLED', true),
    'max_attempts' => env('PACKAGE_RATE_LIMIT_MAX', 60),
    'decay_seconds' => env('PACKAGE_RATE_LIMIT_DECAY', 60),
],

Test the limit explicitly. Rate-limiting behavior is easy to add and easy to never verify. Use Illuminate\Support\Facades\RateLimiter::clear() in setUp() and write one test that asserts the 429 on the N+1th call — this is also your regression guard for the next major bump.

Queue and job context. If the package's limiting applies to queued work, remember workers hold their own process state; in-memory limiters won't coordinate across workers. Confirm the package uses a cache-backed store before relying on it in a multi-worker setup.

Gotchas and Tips

This is a hard breaking change. 3.0.0 drops support for Laravel 8 and below entirely — not a deprecation, a removal. Any app still on 8.x must stay on 2.x. Pin accordingly:

"require": { "<vendor>/<package>": "^2.0" }

Run composer why-not <vendor>/<package> 3.0 to find transitive constraints blocking the upgrade.

Config file drift is the top upgrade failure mode. Republished configs in majors often rename keys. If you overwrite your published config you'll silently lose local customization; if you don't republish you'll get Undefined array key errors on the new limiting parameters. Diff both, then merge by hand.

429s are caching artifacts more often than logic bugs. If limits trigger earlier than expected in testing, check whether your cache driver is array (per-request, resets constantly) versus redis/file (persists across requests). The limiter's behavior changes completely with the store. php artisan cache:clear before re-testing is not cheating, it's necessary.

Check the changelog for the exact parameter names. The release notes state rate-limiting parameters were added but don't enumerate them or their defaults. Read the package's CHANGELOG.md and the config stub directly rather than inferring from an older tutorial — naming conventions for limit/decay/attempt keys vary widely between packages.

Extension point worth knowing: if the package resolves its limiter through the container, you can bind your own implementation in a service provider to wrap logging, metrics, or custom key generation (e.g. limiting per-tenant rather than per-IP) without forking the package.

Debugging tip: emit the limiter's current attempt count into your logs (or a /debug/limits route gated to non-production) during rollout. When a 429 appears in production, you'll want to know whether the counter is shared across users, per-IP, or per-authenticated-user — and that's determined by the key resolver, not the limit value.