README

Symfony Bundle

This bundle adds the required functionality to use mosparo in your Symfony form.

Description

With this PHP library you can connect to a mosparo installation and verify the submitted data.

Requirements

To use the plugin, you must meet the following requirements:

• A mosparo project
• Symfony 5.4 or greater
• PHP 8.0 or greater

Installation

Install this bundle by using composer:

composer require arnaud-ritti/mosparo-bundle

Configuration

1. Register the bundle

Register bundle into config/bundles.php:

return [
    //...
    Mosparo\MosparoBundle\MosparoBundle::class => ['all' => true],
];

2. Add configuration files

Setup bundle's config into 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)%'

Add your variables to your .env file:

###> mosparo/mosparo-bundle ###
MOSPARO_INSTANCE_URL=https://example.com
MOSPARO_UUID=<your-project-uuid>
MOSPARO_PUBLIC_KEY=<your-project-public-key>
MOSPARO_PRIVATE_KEY=<your-project-private-key>
###< mosparo/mosparo-bundle ###

Handle multiples configurations

Into your configuration file. ex: config/packages/mosparo.yaml:

mosparo:
  default_project: '%env(MOSPARO_DEFAULT)%'
  projects:
    forms:
      instance_url: '%env(MOSPARO_FORMS_INSTANCE_URL)%'
      uuid: '%env(MOSPARO_FORMS_UUID)%'
      public_key: '%env(MOSPARO_FORMS_PUBLIC_KEY)%'
      private_key: '%env(MOSPARO_FORMS_PRIVATE_KEY)%'
    login:
      instance_url: '%env(MOSPARO_LOGIN_INSTANCE_URL)%'
      uuid: '%env(MOSPARO_LOGIN_UUID)%'
      public_key: '%env(MOSPARO_LOGIN_PUBLIC_KEY)%'
      private_key: '%env(MOSPARO_LOGIN_PRIVATE_KEY)%'

Inside your .env files

###> mosparo/mosparo-bundle ###
MOSPARO_DEFAULT=<your-default-config>

MOSPARO_FORMS_INSTANCE_URL=<your-forms-project-instance>
MOSPARO_FORMS_UUID=<your-forms-project-uuid>
MOSPARO_FORMS_PUBLIC_KEY=<your-forms-project-public-key>
MOSPARO_FORMS_PRIVATE_KEY=<your-forms-project-private-key>

MOSPARO_LOGIN_INSTANCE_URL=<your-login-project-instance>
MOSPARO_LOGIN_UUID=<your-login-project-uuid>
MOSPARO_LOGIN_PUBLIC_KEY=<your-login-project-public-key>
MOSPARO_LOGIN_PRIVATE_KEY=<your-login-project-private-key>
###< mosparo/mosparo-bundle ###

Usage

How to integrate mosparo in Symfony form:

<?php

use Mosparo\MosparoBundle\Form\Type\MosparoType;

class TaskType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder->add('mosparo', MosparoType::class, [
            'project' => 'default',
            'allowBrowserValidation' => false,
            'cssResourceUrl' => '',
            'designMode' => false,
            'inputFieldSelector' => '[name]:not(.mosparo__ignored-field)',
            'loadCssResource' => true,
            'requestSubmitTokenOnInit' => true,
        ]);
    }
}

Additional options

Ignored fields

Automatically ignored fields

mosparo automatically ignores the following fields:

• All fields which do not have a name (attribute name)
• HTML field type
  • password
  • file
  • hidden
  • checkbox
  • radio
  • submit
  • reset
• HTML button type
  • submit
  • button
• Fields containing _mosparo_ in the name

Manually ignored fields

CSS class

If you give a form field the CSS class mosparo__ignored-field, the field will not be processed by mosparo.

JavaScript initialisation

When initializing the JavaScript functionality, you can define the selector with which the fields are searched (see Parameters of the mosparo field).

Override allowed and verifiable field types

You can also register event listeners (or subscribers) to add or remove field types.

We use here a listener for example.

// src/EventListener/FilterFieldTypesListener.php
namespace App\EventListener;

use Mosparo\MosparoBundle\Event\FilterFieldTypesEvent;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

#[AsEventListener]
class FilterFieldTypesListener
{
    public function __invoke(FilterFieldTypesEvent $event): FilterFieldTypesEvent
    {
        // Remove PasswordType from the ignored list
        $event->setIgnoredFieldTypes(array_diff(
          $event->getIgnoredFieldTypes(), 
          [
            PasswordType::class
          ]
        ));
        
        // Add PasswordType to the verifiable list
        $event->setVerifiableFieldTypes(array_merge(
          $event->getVerifiableFieldTypes(), 
          [
            PasswordType::class
          ]
        ));

        return $event;
    }
}

How to deal with functional and e2e testing:

Mosparo won't allow you to test your app efficiently unless you disable it for the environment you are testing against.

# config/packages/mosparo.yaml
mosparo:
  enabled: '%env(bool:MOSPARO_ENABLED)%'

#.env.test or an environment variable
MOSPARO_ENABLED=0

How to disable SSL verification:

In order to support invalid SSL certificats you will need to disable the SSL check.

# config/packages/mosparo.yaml
mosparo:
  ...
  verify_ssl: '%env(bool:MOSPARO_VERIFY_SSL)%'

#.env or an environment variable
MOSPARO_VERIFY_SSL=0

For multiples configurations:

# config/packages/mosparo.yaml
mosparo:
  projects:
    forms:
      ...
      verify_ssl: '%env(bool:MOSPARO_FORMS_VERIFY_SSL)%'
    login:
      ...
      verify_ssl: '%env(bool:MOSPARO_LOGIN_VERIFY_SSL)%'

#.env or an environment variable
MOSPARO_FORMS_VERIFY_SSL=0
MOSPARO_LOGIN_VERIFY_SSL=0

License

mosparo is open-sourced software licensed under the MIT License. Please see the LICENSE file for the full license.

Contributing

See CONTRIBUTING