- How do I install overtrue/laravel-qcloud-captcha in a Laravel app?
- Install it with Composer by running composer require overtrue/laravel-qcloud-captcha. The package ships a service provider that Laravel's package auto-discovery registers automatically, so no manual provider entry is normally needed. After installing, publish the configuration file and add your Tencent Cloud credentials before using the validation rule. If you run with discovery disabled, register the provider and any facade alias manually as described in the README.
- How do I publish the config file and set my Tencent Cloud CAPTCHA credentials?
- Run php artisan vendor:publish and select the laravel-qcloud-captcha provider or tag, which drops the package config file into your config directory. Put your Tencent Cloud SecretId and SecretKey in your .env file and reference them from that config file with env() calls so secrets never live in version control. Some setups also need the CAPTCHA app identifier and secondary-verification settings from the Tencent Cloud console. Confirm the exact file name and key names against the package README, since they are package-specific.
- How do I validate a Tencent CAPTCHA ticket and randstr in a Laravel form request?
- Your front-end TCaptcha widget produces a ticket and a randstr value, which you submit alongside the rest of the form payload. In a FormRequest rules() method you mark both fields as required and attach the CAPTCHA validation rule the package provides to the ticket field. When validation runs, the package performs the server-side check against Tencent Cloud and fails the request if verification does not succeed, so standard Laravel error handling and redirects apply. Check the README for the exact rule class or string alias to use.
- Can I use this package to protect a JSON API endpoint instead of a Blade form?
- Yes. Because verification is exposed as a Laravel validation rule, it works the same way inside a FormRequest or a Validator::make call in an API controller. Send the ticket and randstr from the client as JSON fields, and Laravel will return a 422 response with validation errors when the CAPTCHA check fails, provided the request expects JSON. No session or Blade rendering is required, so stateless endpoints and SPAs are supported.
- Which Laravel and PHP versions does overtrue/laravel-qcloud-captcha support?
- The 4.x line is documented as requiring Laravel 13.9 or newer and PHP 8.3 or newer, with CI covering PHP 8.3, 8.4 and 8.5. The 4.x release notes describe only dependency, toolchain and CI changes, so the runtime behaviour of the CAPTCHA verification itself is unchanged from 3.x. Applications still on Laravel 12 cannot install 4.x and should stay on the 3.x line unless they complete a framework upgrade. Always confirm the live constraints in the package's composer.json before planning an upgrade.
- How do I test CAPTCHA validation without calling Tencent Cloud in my test suite?
- Never let CI hit the real Tencent Cloud endpoint. Use Http::fake() to stub the outbound verification request and assert that a successful response passes validation while an error response fails it, or bind a fake implementation of the CAPTCHA client into the container for the test. Cover both the happy path and the failure path so you know your form rejects invalid tickets. This keeps tests fast, deterministic and free of credential requirements.
- Why does my Tencent CAPTCHA validation always fail even though the widget shows success?
- The most common causes are missing or incorrect SecretId and SecretKey values, a mismatch between the CAPTCHA app configured in the Tencent Cloud console and the one used by the front-end widget, or a ticket that has already been consumed or has expired. Tickets are single-use and short-lived, so re-submitting the same form payload will fail. Also check that the config file was actually published and that config caching (php artisan config:clear) is not holding stale values.
- Does the package verify the CAPTCHA server-side, and is that enough to stop bots?
- Yes, the package posts the ticket and randstr to Tencent Cloud from your server together with your credentials, so the client cannot fake a successful result by editing JavaScript or the DOM. That server-side check is the security-relevant part of TCaptcha. It should be combined with rate limiting, honeypots and normal input validation, since CAPTCHA alone does not defend against credential stuffing or abuse from solved challenges.
- Is overtrue/laravel-qcloud-captcha actively maintained, and what about the 3.x branch?
- The 4.x release shows CI running across PHP 8.3, 8.4 and 8.5 plus Composer validation and the package's own test suite, which indicates the maintainer is tracking new PHP releases. The release notes do not state a support policy for the 3.x line, so teams that cannot move to Laravel 13.9 should confirm whether security backports will continue. Watch the repository's release feed and issue tracker before depending on 3.x long term.
- What are the alternatives to overtrue/laravel-qcloud-captcha for Laravel CAPTCHA protection?
- Alternatives include Laravel packages for Google reCAPTCHA, hCaptcha or Cloudflare Turnstile, plus rolling your own validator around the official Tencent Cloud SDK. TCaptcha is usually the right pick when your users are in mainland China, where Google-hosted challenges are often unreachable. If you need a single package that covers multiple providers, look for a captcha abstraction package rather than mixing several provider-specific ones.