Settings

Edit settings in the administration

Enable Editor mode in its own dropdown beside the administration language switch. The dropdown also opens every setting of the model you are looking at. The switch is available only to a signed-in administrator with full access (hasAdminAccess()) with APP_DEBUG=true outside the production environment. The server applies the same restrictions to reads and writes. With roles enabled, full access requires permissions = true; with roles disabled, CrudAdmin administrators already have full access. Pencils beside form headings, table headers, buttons, filters and the column picker open a shared settings modal. Their tooltips show the setting keys. A button pencil opens all three button texts: opening a new form, submitting a new record and saving an existing record. The pencil beside the table heading opens all editable settings for that model. Every modal edits only the settings its pencil covers. Edits render in the administration immediately; closing the modal without saving restores the stored settings. The initial editable set is increments, filter.single, filter.max_buttons, title.create, title.update, buttons.create, buttons.insert, buttons.update, columns.*.name, columns.*.hidden, and the default column snapshot. Other settings remain in PHP. The editor uses a shared registry for field types, group titles and server validation; fields are grouped by their prefix into the same cards the administration uses for field groups, and an empty field shows the value the administration renders in its place as the placeholder. Changes are written to app/Admin/model-settings.php, keyed by the full model class. Commit and deploy this file with your application. It contains the current configuration only, not a change history. Existing model settings and mutators remain supported; the map overrides their values. Restore original setting removes an override.

app/Admin/model-settings.php

<?php

return [
    'App\\Models\\Product' => [
        'buttons.create' => _('Add product'),
        'columns.price.name' => _('Price'),
        'filter.max_buttons' => 4,
        'title.create' => _('New product'),
        'title.update' => _('Editing :name'),
    ],
];

Enter text in the source language. The editor reads source strings even when your current administration language is different. Translatable values are written using _('text'), and app/Admin is included in administration gettext extraction. Placeholders such as :name and :id remain supported. The map is independent of bootstrap/cache/crudadmin.php: admin:cache never overwrites it, and settings are translated at runtime. Conflicting concurrent edits are rejected; reopen the editor to load the current file before saving again.

Default columns

In editor mode, arrange and toggle columns in the column dropdown, then choose Use as default. This saves both their order and visibility for the model, including nested tables. A snapshot can override hidden; it cannot expose password or inaccessible columns. Clear default removes the snapshot and restores the model defaults. Existing personal column preferences remain above the shared defaults. When the developer changes table settings, the open model previews the new defaults. Newly introduced columns are inserted after their nearest predecessor from the current model definition and use that definition’s visibility. Removed fields are ignored; migrated virtual columns are retained explicitly. Use snapshots for new ordering configuration. Legacy columns.*.before and columns.*.after declarations remain readable for compatibility and can be converted by admin:settings-migrate.

Defining settings

Settings control texts, the table, the grid, search and form behaviour of a module. Define them in the $settings property, or in the settings() method when values depend on runtime conditions.

app/Models/Order.php

protected $settings = [
    'title.update' => 'Order no. :number',
    'columns.client_id.name' => 'Customer',
    'grid.default' => 'full',
];

app/Models/Product.php

public function settings()
{
    return [
        'increments' => admin()?->isSuperAdmin() ?? false,
        'search.autosave' => true,
        'form.modal' => ['enabled' => true, 'width' => 900],
    ];
}

When the settings() method exists, the $settings property is ignored. The method is evaluated on every request of the administration, so it can read config, the logged administrator or the request. Settings can be written as nested arrays or with dot keys. Both forms produce the same result and can be mixed. When the same path is declared twice, the later value wins.

protected $settings = [
    'grid' => ['default' => 'full'],
    'grid.big.disabled' => true,
];

To extend the settings of a model from a module or a parent class, use the setSettingsProperty mutator:

public function setSettingsProperty($settings)
{
    return array_merge($settings, [
        'form.actions' => true,
        'title.update' => ':number - :name',
    ]);
}

Texts in title.*, buttons.* and columns.*.name are translated with gettext, so write them in the source language of the administration.

Most settings only change the administration interface, they do not restrict the server. 'editable' => false makes the form read-only, but updates are still accepted. Use the $editable parameter to forbid them.

Form texts

app/Models/Client.php

protected $settings = [
    'title.rows' => 'Clients',
    'title.create' => 'New client',
    'title.update' => 'Editing client :name (no. :id)',
    'title.tab' => 'Basic information',
    'buttons.create' => 'Add client',
    'buttons.insert' => 'Create client',
    'buttons.update' => 'Save client',
    'buttons.show-history' => 'Changes',
];

Key	Where it is shown	Default
`title.rows`	heading above the table	model name
`title.create`	heading of the new record form	”Add new”
`title.insert`	legacy alias, normalized to `title.create`; wins over a legacy `title.create` when both are set	—
`title.edit`	legacy alias, normalized to `title.update` when an explicit update title is absent	—
`title.update`	heading of an opened record	`name`, `title`, `username` or `number` of the record
`title.tab`	name of the first tab holding fields outside of tabs	”General”
`buttons.create`	add new record button above the table	”Add new”
`buttons.insert`	submit button of the new record form	”Send”
`buttons.update`	submit button of an opened record	”Save”
`buttons.show-history`	history button in the form header	”Show changes”

Every :column placeholder in title.update is replaced by the value of the opened record. Values of select and radio fields are replaced by the option label, translatable values by the first language. Set 'buttons.create' => false to hide the add button.

Columns

app/Models/Product.php

protected $settings = [
    'columns.name.name' => 'Product',
    'columns.name.clickable' => false,
    'columns.code.hidden' => true,
    'columns.description.limit' => 60,
    'columns.price.add_after' => ' €',
    'columns.price.after' => 'name',
    'columns.stock.before' => 'price',
    'columns.released_at.format' => 'd.m.Y',
];

Key	Effect
`name`	column header, also used in the table download
`hidden`	the column is turned off by default, the administrator can turn it on in the columns list
`limit`	maximum length of the text in the cell, `0` shows the whole text
`before` / `after`	legacy ordering; use a default column snapshot for new configuration
`add_before` / `add_after`	text added before or after a non-empty value, for example a unit
`clickable`	`false` does not open the record when the cell is clicked
`format`	date format of the value, also for columns added by `setAdminAttributes`
`type`	`integer` sorts the column numerically
`sortBy`	sorts the column by the values of another column

Use columns.*.name to customize column headers, for example columns.price.name.

Adding new columns

A column which is not a field adds a new column to the table. Its value is added by setAdminAttributes or loaded in scopeAdminRows.

protected $settings = [
    'columns.price_vat' => [
        'name' => 'Price with VAT',
        'after' => 'price',
    ],
    'columns.paid_status' => [
        'name' => 'Status',
        'encode' => false,
    ],
    'columns.progress' => [
        'name' => 'Progress',
        'component' => 'OrderProgressColumn',
    ],
];

'encode' => false renders the value as HTML and disables the text limit.
component renders the cell with a Vue component from the component directories. The component receives the value, valueMutated, valueLimited, field, row and model props. Unknown component names are ignored.
'hidden' => true or 'invisible' => true adds the column turned off, 'column_visible' => true forces it on.

Table and grid

app/Models/StockMovement.php

protected $settings = [
    'increments' => false,
    'checking' => false,
    'table.small' => true,
    'table.switchcolumns' => false,
    'orderBy' => ['created_at' => 'desc'],
];

Key	Effect
`table`	`false` hides the table, table layouts stay visible
`table.small`	compact table
`table.clickable`	`false` does not open records by clicking the row
`table.switchcolumns`	`false` hides the columns list
`checking`	`false` hides the checkboxes for bulk actions
`increments`	`false` hides the id column and the id search option
`dates`	`true` shows created and updated dates in the row actions
`sortable`	`false` disables sorting by clicking column headers, drag and drop is controlled by `$sortable`
`orderBy`	initial sort of the table, `['column' => 'asc']`
`actions`	`false` hides the row action buttons
`editable`	`false` shows opened records read-only
`default`	`true` opens this module after login
`recursivity.name`	tab name of a model nested in itself
`recursivity.max_depth`	maximum nesting of a model in itself, default `10`

Grid

The grid defines how the table and the form share the screen: small, big, half (alias medium) and full.

protected $settings = [
    'grid.default' => 'half',        // default size when the administrator has not chosen one
    'grid.big.disabled' => true,     // disable a single size, or 'grid.full.enabled' => true
    'grid.enabled' => false,         // hide the size switcher
    'grids' => ['half', 'full'],     // allow only these sizes
    'grid.splitmode' => true,        // keep table and form side by side in full size
];

A list of sizes can be written as 'grid' => ['half', 'full'] only when no other grid.* key is set. Together with grid.default use the grids key.

Search, filters and pagination

protected $settings = [
    'search.enabled' => true,          // always show the search bar, false hides it
    'search.column' => 'number',       // preselected search column
    'search.autosave' => true,         // remember searches of the administrator
    'pagination.limit' => 50,          // rows per page, 0 does not load rows at all
    'pagination.limits' => [25, 50, 100],
    'pagination.enabled' => false,     // load all rows at once
    'filter.single' => true,           // only one filter at once
    'filter.max_buttons' => 3,         // more filters are rendered as a dropdown
];

By default the search bar appears when the table has at least 3 rows. Filter buttons are defined by getFilterStates(), which fills filter.items automatically. 'filter.enabled' => false hides them.

Form behaviour

app/Models/Booking.php

protected $settings = [
    'form.modal' => ['enabled' => true, 'width' => 900],
    'form.actions' => true,
    'autoreset' => false,
    'refresh_interval' => 30000,
    'reloadOnUpdate' => true,
];

Key	Effect
`form`	`false` hides the form, only the table is shown
`form.modal`	opens records in a modal in the full grid, `form.modal.width` sets its width
`form.actions`	shows the row action buttons in the header of an opened record
`form.tabs` / `form.header` / `form.footer`	`false` hides the tabs, the form header or the footer with the submit button
`form.autocomplete`	`autocomplete` attribute of text inputs, default from the `model.settings.form.autocomplete` config
`header`	`false` hides the module header with the grid switcher, search and add button
`tabs.default`	index of the tab opened by default
`tabs_autoload`	`false` loads child models of a tab only when the tab is opened
`autoreset`	`false` keeps the created record opened instead of resetting the form
`refresh_interval`	automatic refresh of rows in milliseconds, `false` refreshes once per hour, default 60–120 s
`reloadOnUpdate`	reloads all rows after a record is saved
`rows.eachRequestInitial`	every rows request is initial, so field options and `getAdminModelInitialData()` are refreshed

File fields in the form

protected $settings = [
    'fields.invoice.canDownload' => false,
    'fields.invoice.canDelete' => false,
    'fields.brand_id.options' => ['createOption' => true, 'searchable' => true],
];

canDownload / canDelete hide the download link and the remove button of an uploaded file.
options are passed as props to the select component of the field.

Primary key

The administration reads the primary key name from Eloquent’s getKeyName(). Use the standard model property instead of a separate setting:

protected $primaryKey = 'code';

The default is id. This property identifies the model’s actual database key; it is not an alternative display column. For a non-incrementing string key, also configure $incrementing = false and $keyType = 'string' on the model.

Getting started

Upgrade guide

Admin interface

Validation

Frontend

Website

Edit settings in the administration

Default columns

Defining settings

Form texts

Columns

Adding new columns

Table and grid

Grid

Form behaviour

File fields in the form

Primary key

​Edit settings in the administration

​Default columns

​Defining settings

​Form texts

​Columns

​Adding new columns

​Table and grid

​Grid

​Search, filters and pagination

​Form behaviour

​File fields in the form

​Primary key

Edit settings in the administration

Default columns

Defining settings

Form texts

Columns

Adding new columns

Table and grid

Grid

Search, filters and pagination

Form behaviour

File fields in the form

Primary key