Form Serializer Bundle Laravel Package

Getting Started

• Install with composer require simplethings/form-serializer-bundle, then register it (AppKernel or config/bundles.php). Check composer.json first — the bundle dates from the Symfony 2.x era, so confirm it is compatible with your Symfony version and its dependency on the Form component plus whichever serializer/encoder layer you plan to use.
• Where to look first: the bundle's Resources/config/services.xml (or DI extension) to confirm the exact service ID and constructor arguments, then the README snippet, then Serializer/FormSerializer.php to see which formats/encoders are supported. Service IDs have drifted between releases, so resolve from the container rather than hardcoding.
• First use case: reuse an existing form type as the schema for a read endpoint.

// GET /products/{id}
$product = $repository->find($id);
$form     = $this->createForm(ProductType::class, $product);

$serializer = $this->get('simplethings_form_serializer.form_serializer'); // verify ID
return new JsonResponse($serializer->serialize($form, 'json'));

The write path reuses the same type:

$form = $this->createForm(ProductType::class, new Product());
$data = $serializer->deserialize($form, $request->getContent(), 'json');
$form->submit($data, false); // clearMissing=false for PATCH semantics

if (!$form->isValid()) {
    return new JsonResponse(['errors' => (string) $form->getErrors(true)], 400);
}

Start with a type containing two or three scalar fields and one nested form; add a CollectionType only once the basic round-trip works.

Implementation Patterns

• Form type as single schema. The bundle's value is defining the object graph once and using it for HTML forms, API input, and API output. Keep one type per resource and vary it with options/validation groups instead of duplicating types.
• Read endpoints: never submit. Build the form bound to an entity (createForm(Type::class, $entity)), skip submit() and validation, and serialize. This keeps read serialization free of request semantics.
• Write endpoints: deserialize → submit → validate → persist. deserialize() produces an array shaped to the form tree; submit() then runs transformers, listeners, and mapping. Treat this as the canonical flow and keep controllers thin.
• PUT vs PATCH. Pass clearMissing explicitly to submit(): true for replacements (missing fields become null), false for partial updates. This is the most common source of “my PATCH wiped fields” bugs.
• Nested resources and collections. CollectionType maps to JSON arrays/lists. Set allow_add, allow_delete, and by_reference deliberately; they affect both rendering and deserialization.
• Error envelopes. On validation failure, serialize $form->getErrors(true) into the same JSON/XML shape your success responses use, or define a small error form type so clients get structured field errors.
• Context-specific views. Drive included/excluded fields and validation groups through form options (e.g. ['api' => true]) rather than branching in the type.
• Integration points. Wrap the serializer in a thin application service used by controllers; optionally bridge it into FOSRestBundle or the Symfony Serializer chain if your version supports it. This isolates service-ID drift and encoder choices.
• Custom encoders/normalizers. Register your own encoder if the built-in JSON/XML handling doesn't match your API contract (root element naming, attribute vs element, date formatting).

Gotchas and Tips

• Forms are request-shaped, not a general serializer. Fields with mapped => false, empty_data, and data_class => null behave differently than an ORM-backed normalizer. Audit each type used for API output.
• Transformers run in both directions. A transformer written to accept request strings can mangle values on output. Test a round-trip (serialize → deserialize → submit) for every type, not just one direction.
• Choose the right data accessor. getData(), getNormData(), and getViewData() differ after transforms; the bundle typically reads child data post-transform. Inspect FormSerializer when writing custom normalizers.
• Disable CSRF for API forms ('csrf_protection' => false) and set the method correctly; otherwise submit() fails in confusing ways.
• Listeners fire on deserialize. PRE_SUBMIT/POST_SUBMIT handlers and FormEvents execute during the deserialize-submit flow — guard against side effects (logs, dispatches, file moves) that were meant only for human submissions.
• Validation group consistency. The groups used on $form->submit()/validation and any manual $validator->validate() call must match, or payloads silently pass or fail.
• XML quirks. Root element naming and repeated elements for lists come from the encoder; test one nested object and one collection explicitly because failures surface only in XML.
• Performance. A form graph is built per object; deeply nested forms over large collections are slow. For hot list endpoints, serialize scalars directly or use a dedicated normalizer.
• Debugging. Dump the array returned by deserialize() before submit(), call $form->getErrors(true, true) for nested errors, and use the profiler's form panel. Verify which Symfony/JMS serializer versions are actually wired, since encoder availability differs by release.
• Maintenance risk. Low star count and an older dependency footprint mean the bundle is best treated as legacy-compatible glue. Pin versions, expect to write small shims for newer Symfony releases, and prefer Symfony Serializer groups or API Platform for new surfaces. Use this bundle where reusing existing form types has a clear payoff (admin-style CRUD APIs) rather than as a greenfield serialization layer.