Altcha Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require contao-components/altcha
   

   Ensure your project uses Contao 4.x (LTS) with PHP 8.0+.

2. Enable the Bundle Register in config/bundles.php:

   return [
       ContaoComponents\AltchaBundle\AltchaBundle::class => ['all' => true],
   ];
   

   Clear Contao’s cache:

   php bin/console contao:clear-cache
   

3. First Use Case

   • Frontend Form: Add the altcha widget to a Contao form via the Form Builder (under "CAPTCHA" widgets).
   • Backend Form: Use the AltchaWidget in a custom DCA field:

     $GLOBALS['TL_DCA']['tl_form']['fields']['captcha'] = [
         'inputType' => 'altcha',
         'eval'      => ['tl_class' => 'altcha'],
     ];
     

Implementation Patterns

Core Workflows

1. Form Integration

   • Dynamic Widgets: Leverage Contao’s Widget system to inject ALTCHA into forms:

     use ContaoComponents\AltchaBundle\Widget\AltchaWidget;
     
     $widget = new AltchaWidget('my_form', 'captcha');
     echo $widget->generate();
     

   • Hook-Based: Attach ALTCHA to form submission via Form::onSubmit:

     $GLOBALS['TL_HOOKS']['formOnSubmit'][] = function ($form) {
         if ($form->id === 'contact_form') {
             $validator = new \ContaoComponents\AltchaBundle\Validator\AltchaValidator();
             if (!$validator->validate(\Input::post('ALTCHA_RESPONSE'))) {
                 $form->addError('CAPTCHA validation failed.');
             }
         }
     };
     

2. Configuration Management

   • Centralized Settings: Use Contao’s System::getContainer() to access ALTCHA config:

     $apiKey = \System::getContainer()->getParameter('altcha.api_key');
     $siteKey = \System::getContainer()->getParameter('altcha.site_key');
     

   • Environment Variables: Override defaults in .env:

     ALTCHA_API_KEY=your_key_here
     ALTCHA_SITE_KEY=your_site_key
     

3. Theming and Assets

   • Template Overrides: Copy default templates from: vendor/contao-components/altcha/src/Resources/views/ to templates/altcha/.
   • Asset Bundling: Register custom JS/CSS in Contao’s assets directory and load via:

     $this->addToTemplate('altchaJs', '<script src="%s/assets/altcha/custom.js"></script>');
     

4. Validation Logic

   • Reusable Validator: Extend the base validator for custom rules:

     use ContaoComponents\AltchaBundle\Validator\AltchaValidator;
     
     class CustomAltchaValidator extends AltchaValidator {
         protected function validateResponse($response) {
             // Add custom logic (e.g., rate-limiting)
             return parent::validateResponse($response);
         }
     }
     

Gotchas and Tips

Common Pitfalls

1. Session Conflicts

   • Issue: ALTCHA tokens may expire if Contao’s session handling interferes.
   • Fix: Configure ALTCHA to use Contao’s session namespace:

     $altcha = new \ContaoComponents\Altcha\Altcha();
     $altcha->setSessionNamespace('TL_SESSION');
     

2. Caching Issues

   • Issue: ALTCHA’s dynamic tokens may be cached by Contao’s page cache.
   • Fix: Exclude ALTCHA routes from caching in config/packages/framework.yaml:

     framework:
         cache:
             pools:
                 app.cache.warmup:
                     paths: ['^/(?!altcha/).*$']
     

3. JavaScript Dependencies

   • Issue: ALTCHA’s JS may fail to load if Contao’s asset pipeline is misconfigured.
   • Fix: Ensure the bundle’s assets are registered in config/packages/altcha.yaml:

     altcha:
         assets:
             js: '%kernel.project_dir%/vendor/contao-components/altcha/src/Resources/public/altcha/altcha.js'
             css: '%kernel.project_dir%/vendor/contao-components/altcha/src/Resources/public/altcha/altcha.css'
     

4. Multilingual Sites

   • Issue: ALTCHA lacks built-in language support for Contao’s multilingual forms.
   • Fix: Override the generate() method in AltchaWidget to pass the current language:

     $widget->setLanguage(\Input::get('lang') ?: \System::getContainer()->get('request_stack')->getCurrentRequest()->getLocale());
     

Debugging Tips

• Enable Debug Mode: Add to config/packages/dev/altcha.yaml:

  altcha:
      debug: true
  

  This logs token generation/validation to Contao’s log file.

• Validation Errors: Check tl_error table for CAPTCHA-related errors:

  SELECT * FROM tl_error WHERE message LIKE '%ALTCHA%';
  

• Network Requests: Use browser dev tools to verify ALTCHA’s API calls to https://api.altcha.org.

Extension Points

1. Custom Validation

   • Extend AltchaValidator to add rate-limiting or IP-based checks:

     class RateLimitedAltchaValidator extends AltchaValidator {
         public function validate($response) {
             $ip = \Input::get('REMOTE_ADDR');
             if ($this->isRateLimited($ip)) {
                 throw new \Exception('Too many requests.');
             }
             return parent::validate($response);
         }
     }
     

2. Alternative Storage

   • Replace session-based tokens with a database-backed solution:

     $altcha->setStorage(new \ContaoComponents\Altcha\Storage\DatabaseStorage(\Database::getInstance()));
     

3. Backend Integration

   • Add ALTCHA to Contao’s user registration via a custom field:

     $GLOBALS['TL_DCA']['tl_member']['fields']['altcha'] = [
         'inputType' => 'altcha',
         'eval'      => ['mandatory' => true, 'tl_class' => 'altcha'],
     ];
     

4. Fallback Mechanism

   • Implement a text-based CAPTCHA fallback for JS-disabled users:

     if (\Input::get('js_enabled') === 'false') {
         $widget = new \Contao\Widget\TextCaptchaWidget();
     } else {
         $widget = new AltchaWidget();
     }