Relation fields

​

Many to one

namespace App\Models;

use Admin\Eloquent\AdminModel;

class Product extends AdminModel
{
    protected $migration_date = '2026-01-10 10:00:00';

    protected $name = 'Products';

    public function fields()
    {
        return [
            'name' => 'name:Name|required',
            'category' => 'name:Category|belongsTo:categories,name|required',
            'vat' => 'name:VAT rate|belongsTo:vats,:name (:vat %)',
        ];
    }
}

• A key without the _id suffix is renamed, category is stored in the category_id column and read as $product->category_id. The relation method keeps the short name, $product->category.
• The migration creates an unsigned integer column with a foreign key to the related table. The column is nullable unless the field is required.
• The field is rendered as a select. Options are loaded from the related admin model with the permissions of the logged administrator.
• Fields pointing to the same table load the options only once, with the columns of all their labels.
• An empty value of an optional relation is stored as NULL.
• Rows are searchable by the label columns of the related record. Searching in the relation column itself compares the id.
• Deleting a record used in a relation shows a warning with the list of modules and ids using it. The administrator can still confirm the deletion.

​

Many to many

public function fields()
{
    return [
        'username' => 'name:Username|required',
        'warehouses' => 'name:Assigned warehouses|belongsToMany:warehouses,name',
        'groups' => 'name:Client groups|belongsToMany:clients_groups,name,admin_client_groups|required',
    ];
}

• No column is created in the model table. CrudAdmin creates a pivot table with an id column and two foreign keys, {owner in singular}_id and {related table in singular}_id.
• The default pivot table name is {related table in singular}_{model in singular}_{field key}, e.g. warehouse_admin_warehouses. The model part is derived from the class name, not from $table.
• The third value sets your own pivot table name, belongsToMany:clients_groups,name,admin_client_groups.
• A relation to the own table names the second pivot column with an underscore prefix, e.g. category_id and _category_id.
• Selected ids are synced into the pivot table on create and update. An empty selection removes all rows, required rejects it.
• The model gets the relation method $admin->warehouses and the pivot rows relation $admin->warehouses_pivot.
• Cloning a record copies its pivot rows.
• max:3 limits the number of selected items in the form.

​

Converting a relation to many to many

// Before
'warehouse' => 'name:Warehouse|belongsTo:warehouses,name',

// After
'warehouses' => 'name:Warehouses|belongsToMany:warehouses,name|migrateToPivot',

• Without a value, the old column is the singular field key with _id, warehouses reads warehouse_id.
• migrateToPivot:main_warehouse_id reads the given column.
• Values are imported only when the old field was removed, its column still exists and the pivot table does not exist yet. Confirm dropping the old column in the migration prompt, the values are read before the column is dropped.

​

Relation options

public function fields()
{
    return [
        'product' => 'name:Product|belongsTo:products,:name - :ean|required',
    ];
}

/*
 * Offer only products on stock
 */
public function scopeProductIdOption($query)
{
    $query->where('stock', '>', 0);
}

/*
 * Build each option, all returned columns are sent to the form
 */
public function setProductIdOption($product)
{
    return [
        'id' => $product->getKey(),
        'name' => $product->name,
        'ean' => $product->ean,
        'stock' => $product->stock,
    ];
}

​

Large relation tables

'product' => 'name:Product|belongsTo:products,:name - :ean|async',

'customer' => 'name:Customer|belongsTo:customers,:firstname :lastname|async:500',

• The search matches every word of the query in any column of the label template (:name, :ean), at most 100 records are returned.
• The table and the edit form load labels only of the records displayed in the current page.

​

Required relations in existing tables

use App\Models\OrdersStatus;

public function fields()
{
    return [
        'status' => 'name:Status|belongsTo:orders_statuses,name|required',
    ];
}

public function onRequiredStatusIdRelation()
{
    $this->newQuery()->withoutGlobalScopes()->update([
        'status_id' => OrdersStatus::where('default', true)->value('id'),
    ]);
}

​

Filtering options by another field

filterBy:field_key
filterBy:field_key,foreign_column
filterBy:field_key,foreign_column,option_column

public function fields()
{
    return [
        'country' => 'name:Country|belongsTo:countries,name|required',
        'city' => 'name:City|belongsTo:cities,name|filterBy:country',
        'street' => 'name:Street|belongsTo:streets,name|filterBy:city',
    ];
}

'country' => 'name:Country|belongsTo:countries,name',
'capital' => 'name:Capital|belongsTo:cities,name|filterBy:country,capital_of_id',

• a filtered field which is not required is hidden until the filter field has a value and there are matching options,
• a selected value disappears when it no longer matches the filter,
• the backend does not validate that the stored value matches the filter. Add your own rule when it matters.

​

Filtering by a static select

'continent' => 'name:Continent|type:select|options:europe,asia',
'country' => 'name:Country|belongsTo:countries,name|filterBy:continent',

​

Filtering by several values

'brands' => 'name:Brands|belongsToMany:brands,name',
'product' => 'name:Product|belongsTo:products,name|filterBy:brands',

​

Filtering by a column of the selected option

'branch' => 'name:Branch|belongsTo:branches,name',
'doctor' => 'name:Doctor|belongsTo:doctors,username|filterBy:branch,partner_id,partner_id',

​

Filtering by the parent record

'street' => 'name:Street|belongsTo:streets,name|filterBy:cities.id,city_id',

​

Required only with options

'street' => 'name:Street|belongsTo:streets,name|filterBy:city|required_with_values',

​

Prefilling values from a relation

fillBy:field_key
fillBy:field_key.column
fillBy:field_key,column

public function fields()
{
    return [
        'client' => 'name:Client|belongsTo:clients,:firstname :lastname',
        'firstname' => 'name:First name|fillBy:client',
        'lastname' => 'name:Last name|fillBy:client',
        'delivery' => 'name:Delivery|belongsTo:deliveries,name|required',
        'delivery_price' => 'name:Delivery price|type:decimal|fillBy:delivery.price',
    ];
}

​

Managing related records from a field

'vat' => 'name:VAT rate|belongsTo:vats,:name (:vat %)|required|canAdd',
'client' => 'name:Client|belongsTo:clients,:username|canAdd|canEdit',
'groups' => 'name:Client groups|belongsToMany:clients_groups,name|canAdd|canList',

• Buttons are shown only when the administrator has the permission to the related model.
• canEdit and canView need a selected value and are not available for belongsToMany. canAdd on belongsToMany appends the new record to the selection.
• On a field with filterBy the buttons appear once the filter field has a value, and a new record gets the filter value.

​

Restricting rows by the administrator

public function filterRowsByColumns()
{
    return ['school_id'];
}

public function fields()
{
    return [
        'school' => 'name:School|belongsTo:schools,name|hasAccessFilter',
        'schools' => 'name:Schools|belongsToMany:schools,name|hasAccessFilter',
    ];
}

• belongsTo rows are filtered where school_id equals the administrator value.
• belongsToMany rows are filtered to those having the value in the pivot table.
• The schools table itself and the options of every relation select pointing to it contain only the permitted rows.
• Relations without hasAccessFilter are not filtered.