Relationships

A Resource relation adds a related-record manager to a Resource show page. It uses ordinary Eloquent relationships, then tells SeviaFlow which Resource should render and authorize the related records.

Choose the right relationship surface

Use this	What the user does	Example
A relation manager	Opens a related-record section from a parent record, then creates, edits, deletes, attaches, or detaches records according to the configured capabilities.	Open a customer and manage that customer's orders.
`BelongsToManyField`	Selects related records while creating or editing the parent form.	Select several categories on a product form.
`RepeaterField`	Edits a bounded JSON list stored on the same model.	Store a small list of contact methods; this does not create related Eloquent records.

Declare the relation managers

Use a relation class that matches the Eloquent relationship type. The string passed to make() is the relationship method on the parent model. For example, HasManyRelation::make('orders') expects the parent model to have an orders() relationship that returns its related orders.

RelationsResource.php

<?php

declare(strict_types=1);

namespace App\SeviaFlow\Resources\Examples;

use App\Models\Customer;
use App\Models\Order;
use App\Models\Tag;
use SeviaFlow\Core\Resources\Columns\TextColumn;
use SeviaFlow\Core\Resources\Fields\NumberField;
use SeviaFlow\Core\Resources\Relations\BelongsToManyRelation;
use SeviaFlow\Core\Resources\Relations\HasManyRelation;
use SeviaFlow\Core\Resources\Relations\HasOneRelation;
use SeviaFlow\Core\Resources\Resource;

final class RelationsResource extends Resource
{
    protected static string $model = Customer::class;

    public static function relations(): array
    {
        return [
            HasOneRelation::make('profile')
                ->label('Profile')
                ->resource(CustomerProfileResource::class)
                ->allowCreate()
                ->allowEdit(),
            HasManyRelation::make('orders')
                ->label('Orders')
                ->resource(OrderResource::class)
                ->perPage(10)
                ->allowCreate()
                ->allowEdit()
                ->allowDelete(),
            BelongsToManyRelation::make('tags')
                ->label('Tags')
                ->resource(TagResource::class)
                ->titleAttribute('name')
                ->allowAttach()
                ->allowDetach()
                ->pivotColumns([
                    TextColumn::make('priority')->label('Priority'),
                ])
                ->pivotFields([
                    NumberField::make('priority')->label('Priority')->required(),
                ]),
        ];
    }
}

final class CustomerProfileResource extends Resource
{
    protected static string $model = Customer::class;
}

final class OrderResource extends Resource
{
    protected static string $model = Order::class;
}

final class TagResource extends Resource
{
    protected static string $model = Tag::class;
}

The example adds a one-to-one customer profile, a list of customer orders, and a many-to-many tag manager. Each relation points to a Resource class for the related model. For the complete write behavior, also define the matching Eloquent relationship and database keys in your Laravel models and migrations.

Relation types

Relation class	Expected Eloquent relationship	Typical use
`HasOneRelation`	`hasOne`	One profile or settings record belongs to a parent.
`HasManyRelation`	`hasMany`	Many child records belong to a parent.
`BelongsToManyRelation`	`belongsToMany`	Manage links to existing records through a pivot table.
`MorphOneRelation`	`morphOne`	One related record can belong to more than one model type.
`MorphManyRelation`	`morphMany`	Many polymorphic child records belong to a parent.
`MorphToManyRelation`	`morphToMany`	Many-to-many links use a polymorphic pivot table.

Choose which operations appear

Method	Effect
`resource(RelatedResource::class)`	Chooses the Resource class used to display related records and their forms.
`perPage(10)`	Sets the number of related records shown on one manager page.
`allowCreate()`, `allowEdit()`, `allowDelete()`	Enables those relation-manager controls. They do not replace Laravel policies or Resource authorization.
`allowRestore()`	Enables restore behavior for supported has-many relations when the related model uses soft deletes.
`allowAttach()`, `allowDetach()`	Enables linking or unlinking existing records for many-to-many relation managers.
`titleAttribute('name')`	Chooses the related record attribute displayed as its title.
`pivotColumns([...])`, `pivotFields([...])`	Choose which pivot attributes are displayed and edited by the relation manager.

Many-to-many in the parent form

Use BelongsToManyField when users should select several existing related records in the parent create/edit form. Use BelongsToManyRelation when users should manage those links from the parent's show page, including separate attach/detach controls and pivot attributes. These are two different interfaces over the same Eloquent relation.

For the form field, define the relationship name, an optional related Resource and query scope, and practical selection limits. SeviaFlow validates selected IDs and synchronizes links in the parent save transaction. An omitted field preserves existing links; an explicitly empty list clears editable links. Existing links outside the allowed query scope are preserved. See Fields for a complete field example.