Filament Relationship Builder Laravel Package

Getting Started

Install the package and confirm Filament compatibility before wiring it into a resource:

composer require uni-deal/filament-relationship-builder

If the package ships a plugin class, register it in your panel provider:

->plugin(\UniDeal\FilamentRelationshipBuilder\FilamentRelationshipBuilderPlugin::make())

Publish any config or view assets if the README calls for it:

php artisan vendor:publish --tag="filament-relationship-builder-config"

Look first at the package README for the exact form component name and supported relationship types. The first practical use case is replacing a basic multi-select relationship field with a builder that lets users attach existing related records and create new ones inline, including pivot data.

A minimal resource form usage typically looks like:

use UniDeal\FilamentRelationshipBuilder\Forms\Components\RelationshipBuilder;

RelationshipBuilder::make('members')
    ->relationship('members')
    ->searchable(['name', 'email'])
    ->createOptionForm([
        TextInput::make('name')->required(),
        TextInput::make('email')->email()->required(),
    ]);

Start with a simple BelongsToMany relationship, confirm attach/detach works, then add pivot fields and inline creation.

Implementation Patterns

Use the builder for many-to-many relationships where users need to manage attachments without leaving the parent form. Keep the full CRUD experience in a RelationManager and use the builder for quick attach/detach plus pivot edits on the main resource form.

Common patterns:

• Pivot data editing: configure pivot fields so users can set extra columns per attached record, such as role, quantity, or sort order. Ensure the pivot table has those columns and the relationship uses withPivot().
• Inline creation: enable the create-option form so users can add a related record from the modal. Make sure the related model’s $fillable includes the fields, and that any required fields are included in the create form.
• Searchable selects: for larger related tables, configure searchable columns and avoid loading all options at once. Use an option label callback for display names.
• Authorization: hide the create option or disable attach/detach for users without the relevant policy permissions. Combine the component with Filament’s policy checks rather than relying on UI hiding alone.
• Validation: add rules for minimum/maximum attachments and validate pivot fields. For required relationships, use the component’s required state where available.
• Custom Livewire forms: include the component in a Filament form schema and ensure the form is bound to the correct model. The relationship name on the component must match the relationship method on the model.
• Testing: use Livewire tests against the Filament form. Fill the builder state, submit the form, and assert that pivot rows were created, updated, or deleted.

A typical workflow: define the relationship on both models, add the builder to the resource form, configure searchable columns, add pivot fields, enable inline creation, then test attach/detach and duplicate handling.

Gotchas and Tips

• First release: v1.0 is the initial version. Pin the package version in composer.json and review future changelogs for API changes before upgrading.
• Relationship setup: the relationship must exist on both models. For many-to-many, the pivot table must exist with the correct foreign keys. If you use a custom pivot model, verify the package supports it or configure the relationship with ->using().
• Duplicate attaches: unique constraints on pivot tables can cause errors when a user attaches the same record twice. Handle duplicates in validation or use sync-style behavior if the package provides it.
• Large datasets: searchable relationship fields can become slow. Eager load the columns used for labels and search, and avoid searching unindexed columns.
• File uploads in modals: if the inline create form includes file uploads, confirm the related model’s storage and disk configuration. Modal state can be lost if the modal closes before uploads complete.
• State hydration: when editing an existing record, verify the builder loads current attachments correctly. The component’s relationship name must match the model method and the form field name.
• Debugging: inspect the Livewire component state after mount and after attach/detach. Use Filament’s form state helpers or ray()/dd() to confirm the relationship is returning the expected records.
• Extension points: publish views if you need to customize the builder UI. Use extra attributes for styling, and consider a custom component class if you need to override behavior.
• Version compatibility: confirm the package supports your Filament major version and Laravel version. Filament v3 and v4 APIs differ, so test in a staging environment before rolling out.