Forms Bundle Laravel Package

Getting Started

v1.0.0 is the first stable tag for n-fasano/FormsBundle, but the release note is only a full-changelog link. Treat the README, composer.json, tests, and changelog as the source of truth before adopting it.

Minimal path:

1. Confirm the Packagist/Composer name in the README or composer.json; the GitHub repo is n-fasano/FormsBundle, but Laravel package names are usually lowercase/dashed.
2. Install with composer require n-fasano/forms-bundle once the exact package name is confirmed.
3. Check Laravel/PHP version constraints in composer.json before adding it to an existing app.
4. Publish any package assets if documented, typically:
   • php artisan vendor:publish --tag=forms-config
   • php artisan vendor:publish --tag=forms-migrations
   • php artisan vendor:publish --tag=forms-views
5. Run migrations if the package persists form definitions or submissions.
6. Look first at README.md, config/forms.php, the service provider, routes, and tests/.

First use case: replace a hand-rolled contact/lead form with a package-defined form that handles field definitions, validation, rendering, and submission persistence. Start with one simple form and one submission path before wiring it into admin screens or multi-step workflows.

Implementation Patterns

• Keep app-specific form definitions in app/Forms or app config, not in vendor files. Use the package as the form engine, not as the place for business rules.
• Use a controller/service flow: inject the package form builder or manager, validate through the package’s rules, persist through your own repository/model, then dispatch app events for notifications or audits.
• Render forms through the package’s Blade component/directive/helper if provided. Publish and override views only when you need markup changes, and keep overrides small.
• For dynamic/admin forms, store the form schema in your database only if the package explicitly supports DB-backed definitions. Version schemas and validate submissions against the normalized field map, not against raw JSON.
• For multi-step forms, persist drafts between steps and run the package’s full validation only on final submission. Keep step-level validation in app code.
• Integrate authorization at the app boundary: policies/gates should decide who can view, edit, and submit a form. Do not rely on package UI hiding alone.
• Use package events/listeners for submission-created, submission-updated, or notification hooks if available; otherwise dispatch your own events after persistence.
• Test the integration with feature tests: form renders, invalid submission fails, valid submission persists, authorization is enforced, and file uploads use the expected disk.
• If the package exposes custom field types or validators, prefer those extension points over branching inside Blade templates.

Gotchas and Tips

• v1.0.0 may be a breaking stabilization release from 0.x. Pin the version, read the full changelog/diff, and do not assume an upgrade path exists.
• The release note is sparse. Before production use, inspect the diff for config keys, migration changes, route names, view namespaces, and service-provider bindings.
• Verify the exact Composer package name and auto-discovery behavior. A repo named FormsBundle does not guarantee n-fasano/forms-bundle is the install name.
• Run php artisan config:clear and php artisan route:clear after publishing config or routes. Stale caches are a common source of “package not working” reports.
• Use php artisan vendor:publish --list or the package docs to confirm publish tags. Publishing the wrong tag can leave migrations or views missing.
• Do not edit files in vendor/. Publish config/views and extend through documented interfaces.
• Validate file uploads explicitly: disk, max size, MIME type, and cleanup behavior may be app responsibilities even if the package renders the input.
• Watch dynamic field names. Nested/array fields can collide with Laravel’s validation syntax; test old(), error bags, and repeated field groups.
• Enforce tenant scoping and route model binding yourself if forms/submissions are tenant-owned. Package queries may not include your global scopes unless documented.
• Debug with php artisan route:list, php artisan event:list, Laravel logs, and the package tests. If behavior is unclear, write a failing feature test against your integration before changing config.
• Extension points to check first: custom field types, custom validators, submission handlers, event listeners, view overrides, and config-driven field registration.