Form Bundle Laravel Package

Getting Started

This is a Symfony 2-era bundle, so treat the first hour as a compatibility audit rather than a normal install.

1. Confirm the runtime. You need a Symfony 2.x application (likely 2.3–2.8), PHP 5.x/7.x as supported by the bundle, and Composer. Check composer.json in the repository for the exact Symfony and PHP constraints before running anything.
2. Install it.

   composer require ite/form-bundle
   

   If the package is not on Packagist under that exact name, add the VCS repository explicitly and pin a commit:

   {
     "repositories": [{ "type": "vcs", "url": "https://github.com/itedev/FormBundle" }],
     "require": { "ite/form-bundle": "dev-master" }
   }
   

3. Register the bundle in app/AppKernel.php using the bundle class name from the repository (copy it exactly; Symfony 2 bundle class names are case-sensitive):

   public function registerBundles()
   {
       $bundles = array(
           // ...
           new Ite\FormBundle\IteFormBundle(),
       );
   }
   

4. Publish assets. The bundle's value is largely its JavaScript integration, so install its public assets and include them after jQuery:

   php app/console assets:install web --symlink
   php app/console cache:clear
   

   Then add the bundle's CSS/JS plus any required jQuery plugins (jQuery UI, file upload, etc.) to your base Twig template. Verify what landed in web/bundles/ — the directory name tells you the asset path.
5. Look here first. Read Form/, Resources/config/, and Resources/views/ in the repository. The form types/extensions define the options you can pass; the Twig templates define the markup and data-* attributes the JS hooks into. The README is likely thin, so the source and any tests are the real documentation.
6. First use case. Take one existing form field — an entity picker, date field, or file upload — and replace the plain Symfony type with the bundle's corresponding type. Render the form, confirm the expected markup and JS initialization in the browser, and only then expand to other fields.

Implementation Patterns

Use bundle form types as drop-in replacements. The normal workflow is to swap a core type for the bundle's type inside an existing FormType:

$builder->add('category', 'ite_autocomplete', array(
    'class' => 'AppBundle:Category',
    'route' => 'category_autocomplete',
));

Exact type names and option keys must come from the bundle's Form/Type classes — do not assume them from the README.

Prefer form type extensions over rewriting types. If you want to keep standard Symfony types and add the bundle's behavior, register a FormTypeExtension or use the bundle's extension services. This keeps your form definitions portable if you later remove the bundle.

Wire AJAX-backed fields to a small JSON controller. For autocomplete/remote-source widgets, create a dedicated route that returns JsonResponse and point the form type option at it. Keep the endpoint narrow: accept a query string, apply your own authorization and query limits, and return only the fields the widget needs.

Handle collections with prototypes. For dynamic add/remove rows, render the collection with allow_add/allow_delete and let the bundle's JS bind to the prototype. In your controller, validate the submitted collection as normal — client-side add/remove must not bypass server-side validation.

$builder->add('items', 'collection', array(
    'type' => 'app_item',
    'allow_add' => true,
    'allow_delete' => true,
    'prototype' => true,
    'by_reference' => false,
));

Centralize JS options through bundle config. Put shared settings (selectors, plugin defaults, route names) in config.yml under the bundle's config key rather than scattering them across templates. If the bundle exposes services, override or decorate them in your application's service config instead of editing vendor files.

Customize via Twig form themes. Override the bundle's form theme blocks in app/Resources/views/Form/ or a project-specific theme. This is the safest extension point for markup changes because it survives Composer updates better than editing vendor/.

Test at two levels. Use functional tests to assert the form renders and submits correctly (including the data-* attributes and route options). Use a browser test (Selenium/PhantomJS in the Symfony 2 era) for the JS behavior, because unit tests will not catch plugin initialization failures.

Gotchas and Tips

• This is effectively a legacy dependency. Symfony 2 is end-of-life, the package has very few stars and zero dependents, and there is no sign of active maintenance. Do not introduce it into a new project. If you inherit it, pin the exact version/commit, isolate it behind your own form types, and plan a migration.
• Verify the bundle class and service names before writing code. Small bundles often have inconsistent naming between README, services.xml, and namespace. A failed AppKernel registration or a missing service ID is the most common first-hour problem.
• jQuery load order matters. The bundle assumes jQuery and its plugins are present globally. Load jQuery first, then plugins, then the bundle's scripts. If another part of your app loads a different jQuery version or uses a no-conflict mode, widgets will silently fail to initialize.
• Assets are a frequent source of "nothing happens." After install, confirm web/bundles/<bundle>/ exists, that your template references the correct path, and that you cleared the cache. In dev, disable asset combining/minification while debugging.
• Option names are the API. Because documentation is sparse, read the form type's setDefaultOptions/configureOptions method to see supported keys. Passing an unsupported option throws an InvalidOptionsException at form build time — useful as a fast feedback loop.
• Do not trust client-side behavior. Autocomplete routes, file uploads, and collection add/remove all need server-side validation, CSRF protection where appropriate, and authorization checks. The bundle improves UX; it does not secure your endpoints.
• Debug from the rendered HTML outward. Inspect the data-* attributes and classes the Twig template emits, then check the browser console for the plugin's initialization call. If the markup is right but the widget is dead, it is almost always a JS dependency or load-order issue.
• Extension points to prefer, in order: bundle configuration → service decoration/overrides → Twig theme overrides → form type extensions → editing vendor files (avoid). Keep a short list of every override so upgrades and removal are tractable.
• Migration path. Replace bundle types with core Symfony types plus a small, maintained JS integration (or a modern front-end component), and move AJAX endpoints into your own controllers. Because the bundle has no dependents and little community support, you are unlikely to find migration guides — budget time to reimplement the handful of widgets you actually use rather than porting the whole bundle.