- How do I install scyllaly/hcaptcha in a Laravel app?
- Install it with composer require scyllaly/hcaptcha; Laravel's package discovery registers the service provider automatically. Publish the package config, add your hCaptcha keys, then render the widget in Blade and attach the validation rule to your forms. For a single form this is well under a day of work.
- Which Laravel versions does scyllaly/hcaptcha support?
- The package declares support across Laravel 5.x through 11.x, so it will install on almost any modern Laravel app. That breadth comes from permissive Composer constraints rather than proof on every version, so pin an exact tag and run your own form tests on your Laravel release. Gate major Laravel upgrades on a CI job that exercises the rule against the new tag.
- How do I configure the hCaptcha site and secret keys?
- Publish the package config and supply the hCaptcha site key and secret key, preferably through environment variables so they are never committed. The site key is public and rendered into the widget; the secret key stays server-side and is used only for the siteverify call. Use separate keys per environment and rotate the secret if it leaks.
- How do I add the hCaptcha widget to a Blade form?
- Place the package's Blade directive inside your form tag where the widget should appear; it outputs the hCaptcha script and the widget container. The browser then submits an h-captcha-response field alongside the rest of your form data. If you use a component or Livewire view, include the directive in that template so the script loads on every page that renders the form.
- How do I use the hCaptcha validation rule in a form request?
- Add the package's hCaptcha rule to the rules array of your form request or validator, next to your other field rules. On validation it reads the h-captcha-response token, posts it to hCaptcha's siteverify endpoint server-side, and fails when verification does not succeed. Give the rule a clear custom message so a rejected user sees something actionable rather than a generic error.
- What happens when the hCaptcha siteverify request fails or times out?
- Because verification is a server-side call, a timeout or non-200 response from hCaptcha is a failure path you must define before rollout. Check the rule source in your POC to confirm whether it throws, fails validation, or passes, since fail-open versus fail-closed is a per-form policy choice. Log rejections with enough context to tell bot traffic apart from an hCaptcha outage.
- Can I test hCaptcha validation in CI without calling the live API?
- The package does not document a fake helper, so any test that triggers the rule will call the live siteverify endpoint unless you intercept it. Use Laravel's HTTP fake to stub the outbound request, or bind a stub implementation in the container for feature tests. Keep one manual smoke test against the real API before each release.
- Does scyllaly/hcaptcha support invisible or passive hCaptcha mode?
- The Blade directive renders the standard checkbox widget; invisible or passive mode is configured through hCaptcha's JavaScript API rather than documented by the wrapper. If you need invisible mode, render the widget yourself with hCaptcha's JS and keep the package's rule for server-side verification of the token. Confirm the accessibility fallback in hCaptcha's docs for whichever mode you choose.
- How do I migrate from Google reCAPTCHA to hCaptcha in Laravel?
- Replace the reCAPTCHA rule with the hCaptcha rule, swap the widget markup and script, and update the request field name from g-recaptcha-response to h-captcha-response in custom request classes or JavaScript. Keep the old integration behind a feature flag for a full traffic cycle so rollback is a config flip. Review your privacy notice while you are at it, since data handling is often the reason teams pick hCaptcha.
- Is scyllaly/hcaptcha safe for production and actively maintained?
- Treat it as a small, single-maintainer package: the code surface is tiny and the siteverify protocol is stable, but the bus factor and adoption footprint are low. Pin an exact version and gate Laravel major upgrades on CI that runs your form tests against the new tag. Also review hCaptcha's terms and availability, since that vendor dependency sits outside the package's control.