> ## Documentation Index
> Fetch the complete documentation index at: https://filamentphp.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Relation managers
export const EditOnGitHub = ({version, path}) => {
const url = `https://github.com/filamentphp/filament/edit/${version}/${path}`;
return ;
};
export const Footer = () => {
const sponsorsByTier = JSON.parse(`{
"agency_partner": [
{
"name": "Kirschbaum",
"url": "https://kirschbaumdevelopment.com/solutions/filament-development",
"filename": "kirschbaum.svg"
}
],
"gold": [
{
"name": "Agiledrop",
"url": "https://www.agiledrop.com/laravel?utm_source=filament",
"filename": "agiledrop.svg"
},
{
"name": "Baiz.ai",
"url": "https://baiz.ai",
"filename": "baiz-ai.svg"
},
{
"name": "CMS Max",
"url": "https://cmsmax.com?ref=filamentphp.com",
"filename": "cms-max.svg"
},
{
"name": "Mailtrap",
"url": "https://mailtrap.io/email-sending?utm_source=community&utm_medium=referral&utm_campaign=filament",
"filename": "mailtrap.svg"
},
{
"name": "SerpApi",
"url": "https://serpapi.com/?utm_source=filamentphp",
"filename": "serpapi.svg"
}
]
}`);
function shuffleArray(items) {
const result = [...items];
for (let index = result.length - 1; index > 0; index--) {
const randomIndex = Math.floor(Math.random() * (index + 1));
[result[index], result[randomIndex]] = [result[randomIndex], result[index]];
}
return result;
}
const sponsors = Object.entries(sponsorsByTier).flatMap(([, sponsors]) => shuffleArray(sponsors));
return ;
};
You are currently viewing the documentation for Filament 2.x, which is a previous version of Filament.
Looking for the current stable version? Visit the [5.x documentation](/5.x).
## Getting started
"Relation managers" in Filament allow administrators to list, create, attach, associate, edit, detach, dissociate and delete related records without leaving the resource's Edit page. Resource classes contain a static `getRelations()` method that is used to register relation managers for your resource.
To create a relation manager, you can use the `make:filament-relation-manager` command:
```bash theme={"theme":"gruvbox-dark-hard"}
php artisan make:filament-relation-manager CategoryResource posts title
```
* `CategoryResource` is the name of the resource class for the parent model.
* `posts` is the name of the relationship you want to manage.
* `title` is the name of the attribute that will be used to identify posts.
This will create a `CategoryResource/RelationManagers/PostsRelationManager.php` file. This contains a class where you are able to define a [form](./getting-started#forms) and [table](./getting-started#tables) for your relation manager:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms;
use Filament\Resources\Form;
use Filament\Resources\Table;
use Filament\Tables;
public static function form(Form $form): Form
{
return $form
->schema([
Forms\Components\TextInput::make('title')->required(),
Forms\Components\MarkdownEditor::make('content'),
// ...
]);
}
public static function table(Table $table): Table
{
return $table
->columns([
Tables\Columns\TextColumn::make('title'),
// ...
]);
}
```
You must register the new relation manager in your resource's `getRelations()` method:
```php theme={"theme":"gruvbox-dark-hard"}
public static function getRelations(): array
{
return [
RelationManagers\PostsRelationManager::class,
];
}
```
For relationships with unconventional naming conventions, you may wish to include the `$inverseRelationship` property on the relation manager:
```php theme={"theme":"gruvbox-dark-hard"}
protected static ?string $inverseRelationship = 'section'; // Since the inverse related model is `Category`, this is normally `category`, not `section`.
```
Once a table and form have been defined for the relation manager, visit the [Edit](./editing-records) or [View](./viewing-records) page of your resource to see it in action.
### Handling soft deletes
By default, you will not be able to interact with deleted records in the relation manager. If you'd like to add functionality to restore, force delete and filter trashed records in your relation manager, use the `--soft-deletes` flag when generating the relation manager:
```bash theme={"theme":"gruvbox-dark-hard"}
php artisan make:filament-relation-manager CategoryResource posts title --soft-deletes
```
You can find out more about soft deleting [here](#deleting-records).
## Listing records
Related records will be listed in a table. The entire relation manager is based around this table, which contains actions to [create](#creating-records), [edit](#editing-records), [attach / detach](#attaching-and-detaching-records), [associate / dissociate](#associating-and-dissociating-records), and delete records.
As per the documentation on [listing records](./listing-records), you may use all the same utilities for customization on the relation manager:
* [Columns](./listing-records#columns)
* [Filters](./listing-records#filters)
* [Actions](./listing-records#actions)
* [Bulk actions](./listing-records#bulk-actions)
Additionally, you may use any other feature of the [table builder](../../tables).
### Listing with pivot attributes
For `BelongsToMany` and `MorphToMany` relationships, you may also add pivot table attributes. For example, if you have a `TeamsRelationManager` for your `UserResource`, and you want to add the `role` pivot attribute to the table, you can use:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms;
use Filament\Resources\Form;
use Filament\Tables;
public static function table(Table $table): Table
{
return $table
->columns([
Tables\Columns\TextColumn::make('name'),
Tables\Columns\TextColumn::make('role'),
]);
}
```
Please ensure that any pivot attributes are listed in the `withPivot()` method of the relationship *and* inverse relationship.
## Creating records
### Creating with pivot attributes
For `BelongsToMany` and `MorphToMany` relationships, you may also add pivot table attributes. For example, if you have a `TeamsRelationManager` for your `UserResource`, and you want to add the `role` pivot attribute to the create form, you can use:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms;
use Filament\Resources\Form;
use Filament\Tables;
public static function form(Form $form): Form
{
return $form
->schema([
Forms\Components\TextInput::make('name')->required(),
Forms\Components\TextInput::make('role')->required(),
// ...
]);
}
```
Please ensure that any pivot attributes are listed in the `withPivot()` method of the relationship *and* inverse relationship.
### Customizing data before saving
Sometimes, you may wish to modify form data before it is finally saved to the database. To do this, you may use the `mutateFormDataUsing()` method, which accepts the `$data` as an array, and returns the modified version:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Tables\Actions\CreateAction;
CreateAction::make()
->mutateFormDataUsing(function (array $data): array {
$data['user_id'] = auth()->id();
return $data;
})
```
### Customizing the creation process
You can tweak how the record is created using the `using()` method:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Tables\Actions\CreateAction;
use Filament\Tables\Contracts\HasRelationshipTable;
use Illuminate\Database\Eloquent\Model;
CreateAction::make()
->using(function (HasRelationshipTable $livewire, array $data): Model {
return $livewire->getRelationship()->create($data);
})
```
### Customizing the save notification
When the record is successfully created, a notification is dispatched to the user, which indicates the success of their action.
To customize the text content of this notification:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Tables\Actions\CreateAction;
CreateAction::make()
->successNotificationTitle('User registered')
```
And to disable the notification altogether:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Tables\Actions\CreateAction;
CreateAction::make()
->successNotification(null)
```
### Lifecycle hooks
Hooks may be used to execute code at various points within an action's lifecycle.
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Tables\Actions\CreateAction;
CreateAction::make()
->beforeFormFilled(function () {
// Runs before the form fields are populated with their default values.
})
->afterFormFilled(function () {
// Runs after the form fields are populated with their default values.
})
->beforeFormValidated(function () {
// Runs before the form fields are validated when the form is submitted.
})
->afterFormValidated(function () {
// Runs after the form fields are validated when the form is submitted.
})
->before(function () {
// Runs before the form fields are saved to the database.
})
->after(function () {
// Runs after the form fields are saved to the database.
})
```
### Halting the creation process
At any time, you may call `$action->halt()` from inside a lifecycle hook or mutation method, which will halt the entire creation process:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Notifications\Actions\Action;
use Filament\Notifications\Notification;
use Filament\Resources\RelationManagers\RelationManager;
use Filament\Tables\Actions\CreateAction;
CreateAction::make()
->before(function (CreateAction $action, RelationManager $livewire) {
if (! $livewire->ownerRecord->team->subscribed()) {
Notification::make()
->warning()
->title('You don\'t have an active subscription!')
->body('Choose a plan to continue.')
->persistent()
->actions([
Action::make('subscribe')
->button()
->url(route('subscribe'), shouldOpenInNewTab: true),
])
->send();
$action->halt();
}
})
```
If you'd like the action modal to close too, you can completely `cancel()` the action instead of halting it:
```php theme={"theme":"gruvbox-dark-hard"}
$action->cancel();
```
## Editing records
### Editing with pivot attributes
For `BelongsToMany` and `MorphToMany` relationships, you may also edit pivot table attributes. For example, if you have a `TeamsRelationManager` for your `UserResource`, and you want to add the `role` pivot attribute to the edit form, you can use:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms;
use Filament\Resources\Form;
use Filament\Tables;
public static function form(Form $form): Form
{
return $form
->schema([
Forms\Components\TextInput::make('name')->required(),
Forms\Components\TextInput::make('role')->required(),
// ...
]);
}
```
Please ensure that any pivot attributes are listed in the `withPivot()` method of the relationship *and* inverse relationship.
### Customizing data before filling the form
You may wish to modify the data from a record before it is filled into the form. To do this, you may use the `mutateRecordDataUsing()` method to modify the `$data` array, and return the modified version before it is filled into the form:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Tables\Actions\EditAction;
EditAction::make()
->mutateRecordDataUsing(function (array $data): array {
$data['user_id'] = auth()->id();
return $data;
})
```
### Customizing data before saving
Sometimes, you may wish to modify form data before it is finally saved to the database. To do this, you may define a `mutateFormDataUsing()` method, which accepts the `$data` as an array, and returns it modified:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Tables\Actions\EditAction;
EditAction::make()
->mutateFormDataUsing(function (array $data): array {
$data['last_edited_by_id'] = auth()->id();
return $data;
})
```
### Customizing the saving process
You can tweak how the record is updated using the `using()` method:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Tables\Actions\EditAction;
use Illuminate\Database\Eloquent\Model;
EditAction::make()
->using(function (Model $record, array $data): Model {
$record->update($data);
return $record;
})
```
### Customizing the save notification
When the record is successfully updated, a notification is dispatched to the user, which indicates the success of their action.
To customize the text content of this notification:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Tables\Actions\EditAction;
EditAction::make()
->successNotificationTitle('User updated')
```
And to disable the notification altogether:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Tables\Actions\EditAction;
EditAction::make()
->successNotification(null)
```
### Lifecycle hooks
Hooks may be used to execute code at various points within an action's lifecycle.
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Tables\Actions\EditAction;
EditAction::make()
->beforeFormFilled(function () {
// Runs before the form fields are populated from the database.
})
->afterFormFilled(function () {
// Runs after the form fields are populated from the database.
})
->beforeFormValidated(function () {
// Runs before the form fields are validated when the form is saved.
})
->afterFormValidated(function () {
// Runs after the form fields are validated when the form is saved.
})
->before(function () {
// Runs before the form fields are saved to the database.
})
->after(function () {
// Runs after the form fields are saved to the database.
})
```
### Halting the saving process
At any time, you may call `$action->halt()` from inside a lifecycle hook or mutation method, which will halt the entire saving process:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Notifications\Actions\Action;
use Filament\Notifications\Notification;
use Filament\Resources\RelationManagers\RelationManager;
use Filament\Tables\Actions\EditAction;
EditAction::make()
->before(function (EditAction $action, RelationManager $livewire) {
if (! $livewire->ownerRecord->team->subscribed()) {
Notification::make()
->warning()
->title('You don\'t have an active subscription!')
->body('Choose a plan to continue.')
->persistent()
->actions([
Action::make('subscribe')
->button()
->url(route('subscribe'), shouldOpenInNewTab: true),
])
->send();
$action->halt();
}
})
```
If you'd like the action modal to close too, you can completely `cancel()` the action instead of halting it:
```php theme={"theme":"gruvbox-dark-hard"}
$action->cancel();
```
## Attaching and detaching records
Filament is able to attach and detach records for `BelongsToMany` and `MorphToMany` relationships.
When generating your relation manager, you may pass the `--attach` flag to also add `AttachAction`, `DetachAction` and `DetachBulkAction` to the table:
```bash theme={"theme":"gruvbox-dark-hard"}
php artisan make:filament-relation-manager CategoryResource posts title --attach
```
Alternatively, if you've already generated your resource, you can just add the actions to the `$table` arrays:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Resources\Table;
use Filament\Tables;
public static function table(Table $table): Table
{
return $table
->columns([
// ...
])
->headerActions([
// ...
Tables\Actions\AttachAction::make(),
])
->actions([
// ...
Tables\Actions\DetachAction::make(),
])
->bulkActions([
// ...
Tables\Actions\DetachBulkAction::make(),
]);
}
```
### Preloading the attachment modal select options
By default, as you search for a record to attach, options will load from the database via AJAX. If you wish to preload these options when the form is first loaded instead, you can use the `preloadRecordSelect()` method of `AttachAction`:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Tables\Actions\AttachAction;
AttachAction::make()->preloadRecordSelect()
```
### Attaching with pivot attributes
When you attach record with the `Attach` button, you may wish to define a custom form to add pivot attributes to the relationship:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms;
use Filament\Tables\Actions\AttachAction;
AttachAction::make()
->form(fn (AttachAction $action): array => [
$action->getRecordSelect(),
Forms\Components\TextInput::make('role')->required(),
])
```
In this example, `$action->getRecordSelect()` outputs the select field to pick the record to attach. The `role` text input is then saved to the pivot table's `role` column.
Please ensure that any pivot attributes are listed in the `withPivot()` method of the relationship *and* inverse relationship.
### Scoping the options
You may want to scope the options available to `AttachAction`:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Tables\Actions\AttachAction;
use Illuminate\Database\Eloquent\Builder;
AttachAction::make()
->recordSelectOptionsQuery(fn (Builder $query) => $query->whereBelongsTo(auth()->user()))
```
### Handling duplicates
By default, you will not be allowed to attach a record more than once. This is because you must also set up a primary `id` column on the pivot table for this feature to work.
Please ensure that the `id` attribute is listed in the `withPivot()` method of the relationship *and* inverse relationship.
Finally, add the `$allowsDuplicates` property to the relation manager:
```php theme={"theme":"gruvbox-dark-hard"}
protected bool $allowsDuplicates = true;
```
## Associating and dissociating records
Filament is able to associate and dissociate records for `HasMany` and `MorphMany` relationships.
When generating your relation manager, you may pass the `--associate` flag to also add `AssociateAction`, `DissociateAction` and `DissociateBulkAction` to the table:
```bash theme={"theme":"gruvbox-dark-hard"}
php artisan make:filament-relation-manager CategoryResource posts title --associate
```
Alternatively, if you've already generated your resource, you can just add the actions to the `$table` arrays:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Resources\Table;
use Filament\Tables;
public static function table(Table $table): Table
{
return $table
->columns([
// ...
])
->headerActions([
// ...
Tables\Actions\AssociateAction::make(),
])
->actions([
// ...
Tables\Actions\DissociateAction::make(),
])
->bulkActions([
// ...
Tables\Actions\DissociateBulkAction::make(),
]);
}
```
### Preloading the associate modal select options
By default, as you search for a record to associate, options will load from the database via AJAX. If you wish to preload these options when the form is first loaded instead, you can use the `preloadRecordSelect()` method of `AssociateAction`:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Tables\Actions\AssociateAction;
AssociateAction::make()->preloadRecordSelect()
```
### Scoping the options
You may want to scope the options available to `AssociateAction`:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Tables\Actions\AssociateAction;
use Illuminate\Database\Eloquent\Builder;
AssociateAction::make()
->recordSelectOptionsQuery(fn (Builder $query) => $query->whereBelongsTo(auth()->user())
```
## Viewing records
When generating your relation manager, you may pass the `--view` flag to also add a `ViewAction` to the table:
```bash theme={"theme":"gruvbox-dark-hard"}
php artisan make:filament-relation-manager CategoryResource posts title --view
```
Alternatively, if you've already generated your relation manager, you can just add the `ViewAction` to the `$table->actions()` array:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Resources\Table;
use Filament\Tables;
public static function table(Table $table): Table
{
return $table
->columns([
// ...
])
->actions([
Tables\Actions\ViewAction::make(),
// ...
]);
}
```
## Deleting records
By default, you will not be able to interact with deleted records in the relation manager. If you'd like to add functionality to restore, force delete and filter trashed records in your relation manager, use the `--soft-deletes` flag when generating the relation manager:
```bash theme={"theme":"gruvbox-dark-hard"}
php artisan make:filament-relation-manager CategoryResource posts title --soft-deletes
```
Alternatively, you may add soft deleting functionality to an existing relation manager:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Resources\Table;
use Filament\Tables;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\SoftDeletingScope;
public static function table(Table $table): Table
{
return $table
->columns([
// ...
])
->filters([
Tables\Filters\TrashedFilter::make(),
// ...
])
->actions([
Tables\Actions\DeleteAction::make(),
Tables\Actions\ForceDeleteAction::make(),
Tables\Actions\RestoreAction::make(),
// ...
])
->bulkActions([
Tables\Actions\DeleteBulkAction::make(),
Tables\Actions\ForceDeleteBulkAction::make(),
Tables\Actions\RestoreBulkAction::make(),
// ...
]);
}
protected function getTableQuery(): Builder
{
return parent::getTableQuery()
->withoutGlobalScopes([
SoftDeletingScope::class,
]);
}
```
### Lifecycle hooks
You can use the `before()` and `after()` methods to execute code before and after a record is deleted:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Tables\Actions\DeleteAction;
DeleteAction::make()
->before(function () {
// ...
})
->after(function () {
// ...
})
```
### Halting the deletion process
At any time, you may call `$action->halt()` from inside a lifecycle hook or mutation method, which will halt the entire deletion process:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Notifications\Actions\Action;
use Filament\Notifications\Notification;
use Filament\Resources\RelationManagers\RelationManager;
use Filament\Tables\Actions\DeleteAction;
DeleteAction::make()
->before(function (DeleteAction $action, RelationManager $livewire) {
if (! $livewire->ownerRecord->team->subscribed()) {
Notification::make()
->warning()
->title('You don\'t have an active subscription!')
->body('Choose a plan to continue.')
->persistent()
->actions([
Action::make('subscribe')
->button()
->url(route('subscribe'), shouldOpenInNewTab: true),
])
->send();
$action->halt();
}
})
```
If you'd like the action modal to close too, you can completely `cancel()` the action instead of halting it:
```php theme={"theme":"gruvbox-dark-hard"}
$action->cancel();
```
## Accessing the owner record
Relation managers are Livewire components. When they are first loaded, the owner record (the Eloquent record which serves as a parent - the main resource model) is mounted in a public `$ownerRecord` property. Thus, you may access the owner record using:
```php theme={"theme":"gruvbox-dark-hard"}
$this->ownerRecord
```
However, in you're inside a `static` method like `form()` or `table()`, `$this` isn't accessible. So, you may [use a callback](../../forms/advanced#using-closure-customization) to access the `$livewire` instance:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Forms;
use Filament\Resources\Form;
use Filament\Resources\RelationManagers\RelationManager;
public static function form(Form $form): Form
{
return $form
->schema([
Forms\Components\Select::make('store_id')
->options(function (RelationManager $livewire): array {
return $livewire->ownerRecord->stores()
->pluck('name', 'id')
->toArray();
}),
// ...
]);
}
```
All methods in Filament accept a callback which you can access `$livewire->ownerRecord` in.
## Grouping relation managers
You may choose to group relation managers together into one tab. To do this, you may wrap multiple managers in a `RelationGroup` object, with a label:
```php theme={"theme":"gruvbox-dark-hard"}
use Filament\Resources\RelationManagers\RelationGroup;
public static function getRelations(): array
{
return [
// ...
RelationGroup::make('Contacts', [
RelationManagers\IndividualsRelationManager::class,
RelationManagers\OrganizationsRelationManager::class,
]),
// ...
];
}
```
## Conditional visibility
By default, relation managers will be visible if the `viewAny()` method for the related model policy returns `true`.
You may use the `canViewForRecord()` method to determine if the relation manager should be visible for a specific owner record:
```php theme={"theme":"gruvbox-dark-hard"}
use Illuminate\Database\Eloquent\Model;
public static function canViewForRecord(Model $ownerRecord): bool
{
return $ownerRecord->status === Status::Draft;
}
```
## Moving the resource form to tabs
On the Edit or View page class, override the `hasCombinedRelationManagerTabsWithForm()` method:
```php theme={"theme":"gruvbox-dark-hard"}
public function hasCombinedRelationManagerTabsWithForm(): bool
{
return true;
}
```
)}
Your logo here