Ayah Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   • Add "blackknight467/ayah-bundle": "2.*" to composer.json and run composer update.
   • Enable the bundle in app/AppKernel.php under registerBundles().

2. Configuration:

   • Add ayah keys to app/config/config.yml:

     ayah:
         publisher_key: 'your_publisher_key'
         scoring_key: 'your_scoring_key'
     

3. First Use Case:

   • Add the ayah field to a form type:

     $builder->add('ayah', 'ayah');
     

   • Render the form in a template (e.g., Twig) and submit it. The bundle handles the validation automatically.

Where to Look First

• Bundle Docs: The README.md in the repository (though minimal, it covers core usage).
• Form Type: The AYAHType class (likely in blackknight467\AYAHBundle\Form\Type\AYAHType.php) for customization.
• Configuration: app/config/config.yml for keys and error messages.

Implementation Patterns

Usage Patterns

1. Basic Integration:

   • Add the ayah field to any form type (e.g., contact forms, registration):

     use Symfony\Component\Form\AbstractType;
     use Symfony\Component\Form\FormBuilderInterface;
     
     class ContactType extends AbstractType
     {
         public function buildForm(FormBuilderInterface $builder, array $options)
         {
             $builder
                 ->add('name')
                 ->add('email')
                 ->add('ayah', 'ayah'); // Simple integration
         }
     }
     

2. Validation Workflow:

   • The bundle validates the "Are You a Human" test on form submission. If failed, Symfony’s validation system throws an error (customizable via config).
   • Example error handling in a controller:

     public function submitForm(Request $request)
     {
         $form = $this->createForm(ContactType::class);
         $form->handleRequest($request);
     
         if ($form->isSubmitted() && !$form->isValid()) {
             // Handle validation errors (e.g., ayah failure)
             $this->addFlash('error', $form->getErrors(true)->first()->getMessage());
             return $this->redirectToRoute('contact');
         }
         // Proceed if valid
     }
     

3. Template Rendering:

   • The ayah field renders as a hidden input (likely with JavaScript for the challenge). Ensure your template includes the bundle’s assets:

     {{ form_row(form.ayah) }}
     

   • If using JavaScript, ensure the AYAH script is loaded (check the bundle’s assets or docs for specifics).

Integration Tips

• Symfony Forms: Works seamlessly with Symfony’s form system. No need for manual validation logic.
• Custom Error Messages: Override the default error message via config (see below).
• Asset Management: If the bundle relies on JavaScript/CSS, ensure it’s properly registered in app/config/config.yml or via asset bundles.
• Testing: Mock the AYAH service in tests to avoid hitting real API endpoints:

  $this->get('ayah.ayah_service')->method('validate')->willReturn(true);
  

Gotchas and Tips

Pitfalls

1. API Dependencies:

   • The bundle relies on the Are You a Human (AYAH) service. Ensure your publisher_key and scoring_key are correct and active. Invalid keys will cause silent failures or validation errors.
   • Debugging Tip: Check the AYAH service logs or Symfony’s profiler for API response errors.

2. Archived Bundle:

   • The package is archived (no active maintenance). Expect no updates or bug fixes. Use at your own risk.
   • Mitigation: Fork the repository if you need modifications (e.g., Symfony 5+ compatibility).

3. Hidden Field Assumption:

   • The ayah field likely renders as a hidden input with JavaScript handling the challenge. If JavaScript is disabled, the form may fail silently.
   • Workaround: Add a fallback (e.g., a visible checkbox) or document the requirement in your UX.

4. Configuration Overrides:

   • Custom error messages must be defined in config.yml under the ayah key. Typos or incorrect indentation will cause the default message to persist.

5. Symfony Version:

   • Minimum Symfony 2.7: The bundle may not work with newer Symfony versions (e.g., 4.x/5.x) without modifications. Test thoroughly.

Debugging

1. Validation Errors:

   • If the form fails validation without clear feedback, check:
     • The ayah.error_message in config.yml is correctly set.
     • The AYAH service is receiving valid requests (use browser dev tools to inspect network calls).
     • Symfony’s validation events (e.g., FORM_ERROR in Twig templates).

2. Service Not Found:

   • If the ayah field doesn’t render or throws errors, verify:
     • The bundle is enabled in AppKernel.php.
     • Composer dependencies are installed (composer dump-autoload).

3. JavaScript Issues:

   • If the challenge doesn’t appear, ensure:
     • The AYAH script is loaded (check the bundle’s assets or base.html.twig).
     • No ad-blockers or browser extensions are blocking the script.

Tips

1. Customization:

   • Extend the AYAHType class to modify behavior (e.g., change the field name or add attributes):

     use blackknight467\AYAHBundle\Form\Type\AYAHType as BaseAYAHType;
     
     class CustomAYAHType extends BaseAYAHType
     {
         public function getName()
         {
             return 'custom_ayah';
         }
     }
     

     Then use it in your form:

     $builder->add('ayah', 'custom_ayah');
     

2. Testing:

   • Mock the AYAH service in PHPUnit tests to avoid rate limits or API costs:

     $ayahService = $this->createMock(AYAHService::class);
     $ayahService->method('validate')->willReturn(true);
     $container->set('ayah.ayah_service', $ayahService);
     

3. Fallback for No-JS:

   • Add a visible fallback (e.g., a checkbox) to ensure accessibility:

     {# app/Resources/views/Form/ayah_widget.html.twig #}
     {% if app.request.isXmlHttpRequest or app.request.headers.get('X-Requested-With') == 'XMLHttpRequest' %}
         {{ form_widget(form) }}
     {% else %}
         <div>
             {{ form_label(form) }}
             {{ form_widget(form) }}
             <p class="ayah-fallback">Check this box if you're human: {{ form_widget(form.no_js_fallback) }}</p>
         </div>
     {% endif %}
     

   • Update the form type to include the fallback field.

4. Rate Limiting:

   • AYAH may throttle requests. Cache the validation result if the challenge is expensive:

     // In a custom service or form event listener
     $cache = $this->get('cache');
     $key = 'ayah_validation_' . $request->getClientIp();
     if (!$cache->has($key)) {
         $result = $ayahService->validate($request);
         $cache->set($key, $result, 60); // Cache for 1 minute
     }
     

5. Error Handling:

   • Catch AYAH API failures gracefully. Extend the service or add a listener:

     $form->addError(new FormError('AYAH service unavailable. Please try again later.'));