Friendly Captcha Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony/Laravel Compatibility: The package is explicitly designed for Symfony, not Laravel. While Laravel shares some PHP/Symfony ecosystem similarities (e.g., bundles, service containers), this bundle cannot be directly integrated without significant refactoring or a wrapper layer.
  • Key Limitation: Laravel lacks Symfony’s Kernel/Bundle system, requiring a custom adapter or middleware-based implementation.
• Use Case Alignment: FriendlyCaptcha is a privacy-friendly alternative to reCAPTCHA, ideal for:
  • Form submissions (login, contact, checkout).
  • GDPR/compliance-heavy applications.
  • Reducing bot traffic without intrusive UX.
• Architectural Overhead: If adopted, the TPM must decide between:
  1. Full Symfony Migration (unlikely for Laravel projects).
  2. Hybrid Approach: Use the bundle’s core logic (API calls, validation) via Laravel’s HTTP client and service container, bypassing the bundle structure.

Integration Feasibility

• Core Features:
  • Frontend: The bundle provides a Twig field for Symfony. In Laravel, this would require:
    • Custom Blade directives or JavaScript integration (FriendlyCaptcha’s SDK is JS-based).
    • Manual form handling (e.g., request()->input('fc-token')).
  • Backend: Validation logic (e.g., verifying siteverify API responses) can be replicated in Laravel using:
    • Guzzle or Illuminate\HttpClient for API calls.
    • Custom validation rules (e.g., FriendlyCaptchaValidator service).
• Dependencies:
  • Requires symfony/http-client (for API calls). Laravel’s http facade can replace this.
  • No hard dependencies on Symfony’s FrameworkBundle if extracted properly.

Technical Risk

• High Risk Areas:
  1. Bundle-Specific Logic: The bundle’s CORSFriendlyCaptchaBundle class ties to Symfony’s event system (e.g., KernelEvents). Replicating this in Laravel would require:
     • Custom middleware or service providers.
     • Manual event dispatching (e.g., Events::dispatch()).
  2. Configuration Management: The YAML config (cors_friendly_captcha) would need to be ported to Laravel’s config/friendly_captcha.php.
  3. Testing: No Laravel-specific tests exist; validation edge cases (e.g., API rate limits, token expiration) must be manually tested.
• Mitigation Strategies:
  • Wrapper Library: Create a lightweight Laravel package (e.g., laravel-friendly-captcha) that abstracts the bundle’s logic.
  • Incremental Rollout: Start with API-only validation, then add frontend integration.
  • Fallbacks: Implement graceful degradation (e.g., disable Captcha for admins or during outages).

Key Questions for the TPM

1. Business Justification:
   • Why FriendlyCaptcha over alternatives (e.g., hCaptcha, Cloudflare Turnstile)? Does it meet compliance/UX goals?
   • Is the team willing to invest in a custom Laravel integration vs. using a native package (e.g., spatie/laravel-honeypot for simpler bot protection)?
2. Technical Trade-offs:
   • Should we prioritize a Symfony migration (if other bundles are needed) or stick with Laravel?
   • What’s the cost of maintaining a custom wrapper vs. using the bundle as-is (Symfony-only)?
3. Security/Compliance:
   • Are there data residency requirements (e.g., EU endpoints) that influence endpoint choices?
   • How will we handle token validation failures (e.g., retries, user notifications)?
4. Performance:
   • What’s the latency impact of API calls during peak traffic? Are caching strategies needed?
5. Vendor Lock-in:
   • FriendlyCaptcha’s API changes could break the integration. How will we handle version upgrades?

Integration Approach

Stack Fit

• Laravel Compatibility:
  • Frontend: Use FriendlyCaptcha’s official JavaScript SDK directly in Blade views or Vue/React components. Example:

    <script src="https://api.friendlycaptcha.com/js/friendlycaptcha.js"></script>
    <div id="fc-example-g"></div>
    <script>
      FriendlyCaptcha.render('fc-example-g', {
        sitekey: 'YOUR_SITEKEY',
        theme: 'dark'
      });
    </script>
    

  • Backend: Replace the bundle’s logic with:
    • Service Class: app/Services/FriendlyCaptcha.php to handle API calls (e.g., validateToken()).
    • Validation Rule: Extend Laravel’s FormRequest or use a custom rule:

      use Illuminate\Contracts\Validation\Rule;
      class ValidateFriendlyCaptcha implements Rule {
          public function passes($attribute, $value) {
              return $this->validateToken($value);
          }
          private function validateToken($token) {
              $response = Http::post(config('friendly_captcha.validation.endpoint'), [
                  'response' => $token,
                  'secret' => config('friendly_captcha.secret'),
              ]);
              return $response->json('success');
          }
      }
      

• Symfony vs. Laravel:
  • Avoid the Bundle: The bundle’s CORSFriendlyCaptchaBundle is not needed in Laravel. Focus on:
    • Configuration (move YAML to Laravel’s config/).
    • API integration (use Laravel’s HTTP client).
    • Frontend JS (use FriendlyCaptcha’s SDK directly).

Migration Path

1. Phase 1: API-Only Validation (Low Risk)
   • Implement FriendlyCaptcha service class.
   • Add config file (config/friendly_captcha.php).
   • Test validation in a single form (e.g., contact page).
2. Phase 2: Frontend Integration (Medium Risk)
   • Add FriendlyCaptcha JS to forms.
   • Update Blade templates or frontend framework components.
   • Test token submission flow.
3. Phase 3: Full Rollout (High Risk)
   • Replace existing bot protection (e.g., reCAPTCHA) with FriendlyCaptcha.
   • Monitor false positives/negatives.
   • Set up error handling (e.g., API failures).

Compatibility

• Laravel Versions: Tested with Laravel 10/11 (PHP 8.1+). Ensure compatibility with your version.
• Frontend Frameworks:
  • Blade: Direct JS integration.
  • Vue/React: Use FriendlyCaptcha’s SDK with component props.
• Existing Packages:
  • Conflict risk with other bot protection packages (e.g., spatie/laravel-honeypot). Audit dependencies.
  • Ensure no duplicate HTTP clients or config keys.

Sequencing

Operational Impact

Maintenance

• Pros:
  • No Symfony Dependency: Avoids maintaining a full Symfony stack.
  • Decoupled Components: Service class and JS SDK can be updated independently.
• Cons:
  • Custom Logic: The Laravel wrapper requires maintenance (e.g., API endpoint updates, token validation logic).
  • Vendor Changes: FriendlyCaptcha API deprecations may need service updates.
• Maintenance Tasks:
  • Quarterly: Review FriendlyCaptcha’s API docs for breaking changes.
  • Annual: Audit token validation logic for edge cases (e.g., malformed responses).
  • Incident Response: Monitor API status (e.g., FriendlyCaptcha Status Page).

Support

• Debugging:
  • Frontend Issues: JS console errors (e.g., sitekey misconfiguration).
  • Backend Issues: API response parsing errors (e.g., json('success') failing).
• Common Support Tickets:
  1. "Captcha not loading" → Check JS SDK inclusion, sitekey.
  2. "Validation failing" → Verify secret key, API response structure.
  3. "High latency" → Implement caching for API responses.
• Documentation:
  • Create internal docs for: