Getting Started

Minimal Setup

Install the Bundle Add to composer.json:

composer require elasticms/form-bundle

'providers' => [
    ElasticMS\FormBundle\FormBundle::class,
    // Other providers...
],

Configure ElasticMS Client Ensure elasticms/client-helper-bundle is installed and configured in .env:
```
ELASTICMS_API_URL=https://your-elasticms-instance/api
ELASTICMS_API_KEY=your_api_key_here
```
Define a Form in ElasticMS Create a form schema in ElasticMS (e.g., contact_form) with fields like:
- name (text)
- email (email)
- message (textarea)

Render the Form in Laravel Use Twig (if integrated) or Symfony’s FormRenderer in a Laravel controller:

use ElasticMS\FormBundle\Form\DynamicFormFactory;

public function showForm(DynamicFormFactory $formFactory)
{
    $form = $formFactory->create('contact_form');
    return view('form.show', ['form' => $form->createView()]);
}

Submit the Form Handle submission in a Laravel controller:

public function submitForm(Request $request, DynamicFormFactory $formFactory)
{
    $form = $formFactory->create('contact_form');
    $form->handleRequest($request);

    if ($form->isSubmitted() && $form->isValid()) {
        // Process data: $form->getData()
        return redirect()->route('thank_you');
    }
    return back()->withErrors($form);
}

Implementation Patterns

Core Workflows

1. Dynamic Form Generation

Pattern: Use DynamicFormFactory to generate forms from ElasticMS configurations.
```
$form = $formFactory->create('user_profile_form');
```
Use Case: Admin panels, user profiles, or multi-tenant forms where schemas change frequently.

Tip: Cache form configurations if ElasticMS API calls are slow:

$form = $formFactory->create('slow_to_load_form', ['cache' => true]);

2. Field-Specific Customization

Pattern: Extend or override field types via Symfony’s form type system.

// src/Form/Extension/CustomFieldType.php
namespace App\Form\Extension;

use ElasticMS\FormBundle\Form\Type\AbstractElasticFieldType;
use Symfony\Component\Form\Extension\Core\Type\TextType;

class CustomFieldType extends AbstractElasticFieldType
{
    public function getParent()
    {
        return TextType::class;
    }

    public function configureOptions(OptionsResolver $resolver)
    {
        $resolver->setDefaults([
            'attr' => ['class' => 'custom-field-class'],
        ]);
    }
}

Register the extension:

// config/services.yaml
elasticms_form.type.extensions:
    custom_field: App\Form\Extension\CustomFieldType

3. Validation Integration

Pattern: Leverage Symfony’s validator with Laravel’s validation rules.

// In ElasticMS configuration (YAML/JSON)
fields:
    email:
        type: email
        constraints:
            - NotBlank
            - Email
            - Custom: { rule: 'unique:users,email' } // Laravel-specific

Tip: Use Laravel’s FormRequest for additional validation:

use Illuminate\Foundation\Http\FormRequest;

class StoreUserProfile extends FormRequest
{
    public function authorize()
    {
        return true;
    }

    public function rules()
    {
        return [
            'phone' => ['required', 'phone_number'], // Custom rule
        ];
    }
}

4. Twig Integration

Pattern: Render forms in Twig templates (if using Laravel’s Twig bridge).

{{ form_start(form) }}
    {{ form_row(form.name) }}
    {{ form_row(form.email) }}
    {{ form_row(form.message) }}
{{ form_end(form) }}

Laravel Alternative: Use Blade with Symfony’s FormRenderer:

// In a Blade view
@php
    $formView = $form->createView();
@endphp
<form method="post">
    @foreach($formView->children as $child)
        <div class="form-group">
            {!! $child->label($child->getName()) !!}
            {!! $child->errors !!}
            {!! $child->widget !!}
        </div>
    @endforeach
    <button type="submit">Submit</button>
</form>

5. Form Submission Handling

Pattern: Process submissions in Laravel controllers.

public function handleSubmission(Request $request, DynamicFormFactory $formFactory)
{
    $form = $formFactory->create('contact_form');
    $form->handleRequest($request);

    if ($form->isSubmitted() && $form->isValid()) {
        $data = $form->getData();
        // Save to DB or send email
        Mail::to($data['email'])->send(new ContactFormMail($data));
        return redirect()->route('thank_you');
    }
    return back()->withErrors($form->getErrors(true));
}

Integration Tips

Laravel-Symfony Synergy

Service Container: Register Symfony services in Laravel’s container:

// bootstrap/app.php
$app->singleton(\ElasticMS\FormBundle\Form\DynamicFormFactory::class, function ($app) {
    return new \ElasticMS\FormBundle\Form\DynamicFormFactory(
        $app->make(\ElasticMS\ClientHelperBundle\Client\ClientInterface::class)
    );
});

Request Handling: Use Laravel’s Request with Symfony’s Form:

$form->handleRequest(new \Symfony\Component\HttpFoundation\Request($request->all()));

Performance Optimization

Cache Form Configurations:

$form = $formFactory->create('expensive_form', [
    'cache_key' => 'form_expensive_config',
    'ttl' => 3600, // Cache for 1 hour
]);

Lazy-Load Fields: Load only required fields for large forms:

$form = $formFactory->create('large_form', [
    'fields' => ['name', 'email'], // Explicitly load fields
]);

Testing

Unit Test Forms:

public function testFormCreation()
{
    $formFactory = $this->app->make(DynamicFormFactory::class);
    $form = $formFactory->create('test_form');

    $this->assertInstanceOf(\Symfony\Component\Form\FormInterface::class, $form);
    $this->assertCount(2, $form->all());
}

Mock ElasticMS API:

$client = Mockery::mock(\ElasticMS\ClientHelperBundle\Client\ClientInterface::class);
$client->shouldReceive('getForm')
       ->once()
       ->andReturn(['fields' => [...]]);

$formFactory = new DynamicFormFactory($client);

Gotchas and Tips

Pitfalls

1. Symfony-Laravel Request Conflicts

Issue: Symfony’s Form expects a Request object with specific methods (isMethod(), get()), while Laravel’s Request has slight differences.

Fix: Use a wrapper or adapter:

$symfonyRequest = new \Symfony\Component\HttpFoundation\Request(
    $laravelRequest->all(),
    $laravelRequest->query->all(),
    $laravelRequest->server->all(),
    $laravelRequest->cookies->all(),
    $laravelRequest->files->all(),
    $laravelRequest->request->all()
);
$form->handleRequest($symfonyRequest);

2. CSRF Token Mismatch

Issue: Laravel’s CSRF token (_token) may conflict with Symfony’s expectations.

Fix: Exclude the CSRF field from form handling or use Laravel’s middleware to validate tokens first:

// In FormType
public function configureOptions(OptionsResolver $resolver)
{
    $resolver->setDefaults([
        'csrf_protection' => false, // Disable if using Laravel's CSRF
    ]);
}

3. Validation Rule Gaps

Issue: Custom Laravel validation rules (e.g., unique:users,email) won’t work out-of-the-box in Symfony’s validator.

Fix: Create a custom constraint:

use Symfony\Component\Validator\Constraint;
use Symfony\Component\Validator\ConstraintValidator;

class UniqueUserEmailConstraint extends Constraint {}
class UniqueUserEmailValidator extends ConstraintValidator
{
    public function validate($value

Form Bundle Laravel Package