Mosparo Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require arnaud-ritti/mosparo-bundle
   

2. Register the bundle in config/bundles.php:

   Mosparo\MosparoBundle\MosparoBundle::class => ['all' => true],
   

3. Configure .env with your Mosparo instance credentials:

   MOSPARO_INSTANCE_URL=https://your-mosparo-instance.com
   MOSPARO_UUID=your-project-uuid
   MOSPARO_PUBLIC_KEY=your-public-key
   MOSPARO_PRIVATE_KEY=your-private-key
   

4. Add config in config/packages/mosparo.yaml:

   mosparo:
     instance_url: '%env(MOSPARO_INSTANCE_URL)%'
     uuid: '%env(MOSPARO_UUID)%'
     public_key: '%env(MOSPARO_PUBLIC_KEY)%'
     private_key: '%env(MOSPARO_PRIVATE_KEY)%'
   

First Use Case: Protect a Contact Form

Add the MosparoType to your form class:

use Mosparo\MosparoBundle\Form\Type\MosparoType;

class ContactType extends AbstractType {
    public function buildForm(FormBuilderInterface $builder, array $options) {
        $builder
            ->add('name', TextType::class)
            ->add('email', EmailType::class)
            ->add('message', TextareaType::class)
            ->add('mosparo', MosparoType::class, [
                'project' => 'default',
                'loadCssResource' => true
            ]);
    }
}

Implementation Patterns

1. Multi-Project Configuration

Use separate configurations for different form types (e.g., login vs. contact forms):

# config/packages/mosparo.yaml
mosparo:
  default_project: '%env(MOSPARO_DEFAULT)%'
  projects:
    login:
      instance_url: '%env(MOSPARO_LOGIN_URL)%'
      uuid: '%env(MOSPARO_LOGIN_UUID)%'
      # ...
    contact:
      instance_url: '%env(MOSPARO_CONTACT_URL)%'
      uuid: '%env(MOSPARO_CONTACT_UUID)%'
      # ...

Usage in Form:

$builder->add('mosparo', MosparoType::class, ['project' => 'contact']);

2. Dynamic Field Filtering

Override default ignored/verifiable field types via event listeners:

// src/EventListener/MosparoFieldListener.php
use Mosparo\MosparoBundle\Event\FilterFieldTypesEvent;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\Form\Extension\Core\Type\PasswordType;

#[AsEventListener]
class MosparoFieldListener {
    public function __invoke(FilterFieldTypesEvent $event) {
        $event->setIgnoredFieldTypes(array_diff(
            $event->getIgnoredFieldTypes(),
            [PasswordType::class]
        ));
        $event->setVerifiableFieldTypes(array_merge(
            $event->getVerifiableFieldTypes(),
            [PasswordType::class]
        ));
    }
}

3. Testing Workflow

Disable Mosparo in test environments:

# config/packages/mosparo.yaml
mosparo:
  enabled: '%env(bool:MOSPARO_ENABLED)%'  # Set to `false` in .env.test

# .env.test
MOSPARO_ENABLED=0

4. Performance Optimization

• Cache CSS Resources: Set cssResourceUrl to a cached path:

  $builder->add('mosparo', MosparoType::class, [
      'cssResourceUrl' => '/cached/mosparo.css',
      'loadCssResource' => false
  ]);
  

• Disable Browser Validation: For API-heavy forms:

  $builder->add('mosparo', MosparoType::class, [
      'allowBrowserValidation' => false
  ]);
  

5. Form Integration

For Symfony Forms:

// Twig template
{{ form_start(form) }}
    {{ form_row(form.name) }}
    {{ form_row(form.email) }}
    {{ form_row(form.mosparo) }}  <!-- Renders hidden token + JS -->
{{ form_end(form) }}

For API Submissions:

• Use allowBrowserValidation: false and validate server-side via Mosparo’s API.

Gotchas and Tips

Pitfalls

1. SSL Verification Errors:

   • If Mosparo uses a self-signed certificate, disable verification:

     mosparo:
       verify_ssl: '%env(bool:MOSPARO_VERIFY_SSL)%'
     

     MOSPARO_VERIFY_SSL=0
     

   • Warning: Only use this in development/staging.

2. Field Name Conflicts:

   • Mosparo ignores fields with _mosparo_ in their name. Avoid naming conventions like submit_mosparo_token.

3. Token Mismatches:

   • If using requestSubmitTokenOnInit: true, ensure the form’s CSRF token is compatible with Mosparo’s token. Reset the form carefully:

     $form->reset();
     $form->submit($data); // Mosparo token will auto-reload
     

4. JavaScript Dependencies:

   • Mosparo requires jQuery. Ensure it’s loaded before the Mosparo script:

     <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
     {{ form_widget(form.mosparo) }}  <!-- Auto-loads Mosparo JS -->
     

Debugging Tips

1. Check Mosparo Logs:

   • Enable debug mode in mosparo.yaml:

     mosparo:
       debug: true
     

   • Logs appear in Symfony’s var/log/dev.log.

2. Validate API Responses:

   • Use Mosparo’s API docs to manually test endpoints with your credentials.

3. Form Submission Issues:

   • Verify the inputFieldSelector matches your form’s structure:

     $builder->add('mosparo', MosparoType::class, [
         'inputFieldSelector' => '[data-mosparo="enabled"]' // Custom selector
     ]);
     

Extension Points

1. Custom Validation Logic:

   • Extend the MosparoType class to add pre/post-validation hooks:

     use Mosparo\MosparoBundle\Form\Type\MosparoType as BaseMosparoType;
     
     class CustomMosparoType extends BaseMosparoType {
         public function configureOptions(OptionsResolver $resolver) {
             $resolver->setDefaults([
                 'custom_option' => null,
             ]);
         }
     }
     

2. Event-Driven Extensions:

   • Listen to mosparo.form.submit events to intercept submissions:

     #[AsEventListener(event: 'mosparo.form.submit')]
     public function onMosparoSubmit(MosparoEvent $event) {
         if ($event->isValid()) {
             // Custom logic
         }
     }
     

3. Multi-Tenant Support:

   • Dynamically switch projects based on user context:

     $project = $this->getMosparoProjectForUser($user);
     $builder->add('mosparo', MosparoType::class, ['project' => $project]);
     

Performance Quirks

• CSS Loading: If loadCssResource: true, the bundle injects a <link> tag. For SPAs, preload the CSS manually.
• Token Overhead: Each form submission generates a new token. For high-traffic forms, consider caching tokens client-side (e.g., in localStorage).

Security Notes

• Private Key Exposure: Never commit .env files. Use Symfony’s env() function in code:

  $this->container->getParameter('mosparo.private_key');
  

• Project Isolation: Use separate Mosparo projects for sensitive forms (e.g., login vs. contact) to limit blast radius.