V3: Simplified multi-provider captcha architecture (3 providers) - #336
Open
nenes25 wants to merge 11 commits into
Open
V3: Simplified multi-provider captcha architecture (3 providers)#336nenes25 wants to merge 11 commits into
nenes25 wants to merge 11 commits into
Conversation
This major release introduces a modular architecture supporting multiple captcha providers: **New Features:** - Multi-provider architecture with 4 captcha systems: * Google reCAPTCHA v2/v3 (existing, refactored) * Google reCAPTCHA Enterprise (with Google Cloud integration) * hCaptcha (privacy-focused alternative) * Math Captcha (native, no external dependencies) - Provider abstraction layer: * CaptchaProviderInterface: common contract for all providers * AbstractCaptchaProvider: shared functionality * CaptchaFactory: dynamic provider instantiation * Provider-specific templates - Enhanced configuration: * Provider selection dropdown in admin * Dynamic configuration fields per provider * Math Captcha difficulty levels (easy/medium/hard) * Google Enterprise project/key configuration **Technical Changes:** - Refactored eicaptcha.php to use provider pattern - Updated ConfigForm.php for provider management - Enhanced Debugger.php with provider checks - Added upgrade script for migration from 2.x - All templates now use provider includes for flexibility **Backward Compatibility:** - Automatic migration from 2.x to 3.0 - Defaults to google_recaptcha provider - All existing configurations preserved - Upgrade script: upgrade/upgrade-3.0.0.php **Architecture:** - PSR-4 compliant provider structure - Lazy loading of providers via factory - Session-based validation for Math Captcha - CSRF protection for Math Captcha - Extensible: new providers can be registered Breaking changes: Version bumped to 3.0.0 due to architectural changes
- Complete guide for creating custom captcha providers - Step-by-step implementation instructions - Code examples for all required methods - Template creation guidelines - Best practices and security recommendations - Real-world examples (Cloudflare Turnstile) - Troubleshooting and testing checklist
Cloudflare Turnstile is a free, privacy-friendly alternative to reCAPTCHA: - No Google tracking - Free tier: 1M requests/month - Modern, user-friendly interface - Support for light, dark, and auto themes - Compact and normal widget sizes **New Provider:** - TurnstileProvider: Full implementation with API validation - Template: turnstile.tpl with theme and size options - Configuration fields: Site Key, Secret Key, Theme, Size **API Integration:** - Endpoint: https://challenges.cloudflare.com/turnstile/v0/siteverify - Response field: cf-turnstile-response - Dashboard: https://dash.cloudflare.com/ **Architecture Improvements:** - Added getResponseFieldName() to CaptchaProviderInterface - Default implementation in AbstractCaptchaProvider - Dynamic field name support in _validateCaptcha() - Math and Turnstile providers now declare custom field names **Configuration:** - 4 new config keys (site/secret keys, theme, size) - Default theme: auto (follows system preferences) - Default size: normal - Full integration in ConfigForm and Installer This brings the total to 5 captcha providers: 1. Google reCAPTCHA v2/v3 2. Google reCAPTCHA Enterprise 3. hCaptcha 4. Math Captcha (native) 5. Cloudflare Turnstile (new)
**Problem:** - Configuration fields were hardcoded in ConfigForm.php - Adding new providers required editing ConfigForm in 3 places - Inconsistent with provider architecture where providers define their own fields **Solution:** - Created getProviderSpecificFields() to dynamically load from current provider - Split fields into logical groups (provider, common, advanced) - Generic postProcess() loops through all fields automatically - Generic getConfigFieldsValues() loads all values dynamically - Added getAllConfigurationFields() helper for field aggregation **Result:** - Adding new provider now requires ZERO changes to ConfigForm.php - Only need to implement getConfigFields() in provider class - Fully consistent with provider architecture - ~200 lines of hardcoded fields removed **Changes:** - src/ConfigForm.php: Complete refactoring with new methods: * getProviderSpecificFields(): Loads fields from current provider * getCommonFields(): Returns always-visible common fields * getAdvancedFields(): Returns advanced configuration * getAllConfigurationFields(): Aggregates all fields from all sources * Simplified postProcess(): Generic loop through all fields * Simplified getConfigFieldsValues(): Generic value loading **Impact:** Provider developers now only need to: 1. Create Provider class with getConfigFields() 2. Register in CaptchaFactory 3. Create template file No ConfigForm.php modifications needed when adding new providers.
- Remove MathCaptchaProvider and TurnstileProvider
- Remove math.tpl and turnstile.tpl templates
- Fix template dispatch: use providerTemplatePath (getTemplatePath()) instead of
dynamic {$provider}.tpl include, which broke for google_enterprise
- Fix HCaptchaProvider: override getResponseFieldName() to return h-captcha-response
- Rewrite hookDisplayEicaptchaVerification.tpl to use provider pattern
- Clean up Installer, ConfigForm, upgrade-3.0.0 from removed provider configs
… Google Enterprise soft-dependency
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
renderContactFormWidget()to the provider interface for per-provider contact form injectionTest plan