Form Bundle Laravel Package

Getting Started

Reality check first: kunstmaan/form-bundle is a Symfony 2 bundle, not a Laravel package. It is tightly coupled to the Kunstmaan CMS stack (kunstmaan/node-bundle, kunstmaan/pagepart-bundle, kunstmaan/admin-bundle) and to Doctrine. You cannot composer require it into a Laravel app and expect it to work. Treat this assessment as "what can I learn from / port out of it," not "how do I install it."

Version note: the current release line is 2.3.x (latest v2.3.14), which means the 2.x branch is still receiving patch-level bugfixes — even though the design and dependencies are frozen in the Symfony 2 era. Do not read "still patched" as "actively developed."

If you are genuinely working inside a Kunstmaan CMS project:

1. Require the bundle and its dependencies:

   composer require kunstmaan/form-bundle
   

2. Register Kunstmaan\FormBundle\KunstmaanFormBundle in app/AppKernel.php (and the PagePart/Node/Admin bundles it depends on).
3. Run the schema tool / migrations so the form submission tables exist:

   app/console doctrine:schema:update --force
   

4. Add FormPagePart to the page part configuration of whichever page type should host a form (app/config/config.yml → kunstmaan_pageparts section).
5. In the admin UI, edit a page, add the "Form" page part, and add fields (text, textarea, choice, checkbox, email, file).

Where to look first:

• PageParts/FormPagePart — the entity that binds a form to a page and holds the field collection.
• The form field type classes under Form/ and their entity counterparts under Entity/ — this is where field behavior lives. ChoiceFormSubmissionFieldType in particular is the one that just changed in v2.3.14.
• The form handler / submission controller — this is where validation, persistence, notification, and (relevant to the latest release) export happen.

First use case: a contact form on a marketing page whose submissions land in an admin list, export to CSV/XLSX, and trigger an email. That is 90% of what this bundle does, and it is exactly the shape of a Laravel FormRequest + Notification + Model trio.

Implementation Patterns

Page-part-driven form definition. The defining pattern is that forms are page content, not code. A FormPagePart is attached to a page in the CMS; fields are child entities with a sequence, a label, a required flag, and a type discriminator. Rendering happens through Twig templates provided by the bundle, which iterate the fields and delegate to per-type widgets.

Adding a custom field type. The bundle's extension point is a pair: a form type (Symfony AbstractType subclass) plus an entity/submission-field class for storing the value. You register the new type so the admin UI can offer it and so the handler knows how to persist, render, and export it. In Laravel terms this is the equivalent of writing a custom Blade component plus a cast/mutator pair.

Submission handling and side effects. Submissions are stored as a FormSubmission with a collection of FormSubmissionField rows keyed by the originating field. The handler persists first, then triggers notification/redirect logic. The common integration pattern is to hook after persistence — an event listener or a decorated handler — to push the submission into a CRM, Slack, or a queue.

Choice fields and export. ChoiceFormSubmissionFieldType stores the raw option string for each selectable choice. Because those options are entered as free text in the CMS, a trailing newline is trivially introduced. Since v2.3.14, ChoiceFormSubmissionFieldType trims newlines out of its possible choices — this is what fixes the previously corrupted CSV/XLSX exports. If you maintain a fork, this is the minimal diff to backport.

Email notification. Each form page part carries recipient/subject configuration; on submit the bundle renders the submission into an email. Keep this in a service, not in the page part, so you can swap the mailer.

Overriding templates. Bundle inheritance: create app/Resources/KunstmaanFormBundle/views/... with a matching path to shadow the shipped Twig templates. This is the Symfony analogue of Laravel's vendor:publish + override, except it is fragile and version-sensitive.

Mapping to a Laravel build. If you are porting the idea rather than the code:

• FormPagePart → a Form model with a JSON schema column (field definitions).
• Field entities → rows in a form_fields table with a type column, or JSON.
• FormSubmission + FormSubmissionField → FormSubmission with a JSON payload column, or a submission_values table.
• Validation → build a FormRequest dynamically from the schema, or validate against a generated rule array.
• Notifications → Notification class per form; render with a Blade view over the payload.
• Admin listing / export → a simple Filament/Nova resource with a CSV/XLSX exporter (and remember to trim() option values — this is the exact class of bug v2.3.14 just fixed upstream).

That port keeps the good part of this bundle's design (schema-as-data, submissions as first-class records) and drops the Symfony coupling.

Gotchas and Tips

Frozen design, but not fully abandoned. The release line is 2.3.x (latest v2.3.14) and still receives patch fixes. However, the codebase targets Symfony 2.x and PHP 5.3–5.6 idioms (app/console instead of bin/console, pre-short-array-syntax in places). It will not run on modern PHP without patching, and the Kunstmaan CMS itself has been discontinued. Patches arrive; the platform does not.

Choice options can carry whitespace — v2.3.14 fixed part of this. The release trims newline characters from ChoiceFormSubmissionFieldType's possible choices, because an embedded \n was breaking CSV/XLSX exports. Two implications:

• If you are on < 2.3.14, exported files from any form with choice fields are suspect — trim option values in your own export code or upgrade.
• The fix trims newlines; it does not strip other leading/trailing whitespace. Options edited with stray spaces will still look wrong in exports and in stored submission values. Trim on input in your own custom field types.

Doctrine inheritance is load-bearing. Field types are mapped via inheritance, so adding a new type means touching both the form type and the Doctrine mapping. A missed mapping produces "unknown discriminator" errors at render time, not at boot — budget debugging time there.

Template overrides break silently. Symfony bundle inheritance resolves by path; a renamed template upstream makes your override a no-op rather than an error. After any patch bump (including v2.3.14) re-check that your custom widget actually renders.

File fields are the usual pain point. Uploaded files are persisted relative to a web-root path and referenced by the submission field. Moving the app, changing the upload directory, or forgetting to copy the files breaks old submissions with dead links. Audit the upload path config before launch.

Required vs. validated are not the same. The required flag controls the HTML attribute and a basic not-blank check; don't assume it does type validation (email format, numeric ranges). Add explicit constraints per field type or you'll get valid-looking garbage in the admin list.

Debugging submissions. If a submission silently doesn't appear: check (1) Doctrine flush is actually called in the handler, (2) the form page part is the one you think it is (page parts are per-page, easy to test against a stale page), and (3) CSRF token/session config, which on Symfony 2 fails quietly in some setups.

Notification delivery is synchronous. Mail is sent inline during the request. On a slow SMTP host the form appears to hang, and a mail failure can surface as a 500 after the row was already persisted. Wrap notification in a try/catch or push it to a queue if you must keep this running.

Extension points worth knowing: the form handler (for post-persist side effects), the per-field form type classes (for new widgets and for fixes like the v2.3.14 trim), event dispatchers around submission, and Twig template overrides. Everything else requires forking.

Bottom line for a Laravel team: don't integrate it. Read FormPagePart, the field type classes, and the submission entities as a reference design for "user-defined forms with stored submissions," then implement the mapping above with native Laravel primitives. The v2.3.14 fix is a good illustration of the kind of low-level bug you inherit when CMS-entered content feeds directly into an export path — one you avoid for free by validating schema input on the way in.