Field / $field

get($key)

Get a field setting or dynamic data property.

$name = $field->get('name');
$label = $field->get('label');

getFieldtype()

Return the Fieldtype module for this field. Same as $field->type.

$fieldtype = $field->getFieldtype();

getTable()

Get the database table name used by this field. The table name is field_ prefixed with the field name, truncated to 64 characters max.

echo $field->getTable(); // field_body

getLabel($language = null) / getDescription($language = null) / getNotes($language = null)

Get the label, description, or notes for the current language (or a specified language in multi-language environments). Unlike $field->label, these methods are language-aware.

echo $field->getLabel();
echo $field->getDescription();
echo $field->getNotes();

getIcon($prefix = false)

Get the icon name. When $prefix is true, returns with fa- prefix.

echo $field->getIcon();       // cog
echo $field->getIcon(true);   // fa-cog

getFieldgroups()

Return the list of Fieldgroups using this field.

$fieldgroups = $field->getFieldgroups();

getTemplates()

Return the list of Templates using this field.

$templates = $field->getTemplates();

numFieldgroups()

Return the number of Fieldgroups this field is used in.

$count = $field->numFieldgroups();

getContext($for, $namespace = '')

Get this field in context of a Page, Template, or Fieldgroup.

$fieldContext = $field->getContext($template);

hasContext($for, $namespace = '')

Check if this field has context settings for the given Page, Template, or Fieldgroup.

if($field->hasContext($template)) {
    // field has per-template context settings
}

getInputfield(Page $page, $contextStr = '')

Get the Inputfield module used to collect input for this field on the given page.

$inputfield = $field->getInputfield($page);

getConfigInputfields()

Get Inputfields needed to configure this field in the admin. Returns an InputfieldWrapper (a fieldset containing Inputfield instances).

$configInputfields = $field->getConfigInputfields();

editUrl($options = [])

Get URL to edit this field in the admin.

echo $field->editUrl(); // /admin/setup/field/edit?id=123
echo $field->editUrl('description'); // with #find-description anchor
echo $field->editUrl(['http' => true]); // with full scheme and hostname

set($key, $value)

Set a native setting or dynamic data property. Also available via property assignment.

$field->set('label', 'New Label');
// or
$field->label = 'New Label';

setName($name)

Set the field's name. Throws WireException for reserved words, duplicate names, system fields, or invalid formats. When renaming, the previous name is tracked in prevName and the previous table in prevTable.

$field->setName('new_name');

setFieldtype($type)

Set the field's type. Accepts a Fieldtype object or a string class name. Supports setup names via FieldtypeName.setupName syntax. When changing type, the previous Fieldtype is tracked in prevFieldtype.

$field->setFieldtype('FieldtypeText');
$field->setFieldtype('FieldtypeImage.lightbox'); // with setup name

save()

Save the field's settings and data to the database. To hook this, hook to Fields::save() instead.

$field->save();

setLabel($text, $language = null) / setDescription($text, $language = null) / setNotes($text, $language = null)

Set label, description, or notes, optionally for a specific language in multi-language environments.

$field->setLabel('My Label');
$field->setDescription('Long description', $language);

setIcon($icon)

Set the icon for this field. The fa- or icon- prefix is stripped automatically.

$field->setIcon('fa-cog');
$field->setIcon('icon-home');
$field->setIcon('user'); // all equivalent

setTable($table = null)

Set an override table name, or pass null to restore the default. The table name is sanitized and truncated to 64 characters.

$field->setTable('custom_table');
$field->setTable(null); // restore default

addFlag($flag)

Add a bitmask flag to the field. Returns $this for chaining.

$field->addFlag(Field::flagAutojoin);

removeFlag($flag)

Remove a bitmask flag from the field. System and permanent flags cannot be removed without first adding flagSystemOverride. Returns $this for chaining.

$field->removeFlag(Field::flagAutojoin);

To remove a system or permanent flag, add flagSystemOverride first:

$field->addFlag(Field::flagSystemOverride);
$field->removeFlag(Field::flagSystem);
$field->removeFlag(Field::flagSystemOverride);
$field->save();

This is intentionally indirect to prevent accidental removal of system field protections.

hasFlag($flag)

Check if the field has the given bitmask flag.

if($field->hasFlag(Field::flagSystem)) {
    echo "This is a system field";
}

$useRoles

Boolean property that enables or disables access control. Setting to true adds flagAccess; setting to false removes it.

$field->useRoles = true;  // enable access control
$field->useRoles = false; // disable access control

$editRoles / $viewRoles

Arrays of Role IDs with edit or view access. Applicable only when useRoles is true.

$field->editRoles = [1, 2]; // role IDs
$field->viewRoles = [1];

setRoles($type, $roles)

Set the roles allowed to view or edit this field. $type is 'view' or 'edit'. Accepts an array of Role IDs, Role objects, or role names.

$field->setRoles('edit', [1, 2]);
$field->setRoles('view', ['guest']);

viewable(Page $page = null, User $user = null)

Check if the field is viewable on the given page by the given user. To maximize efficiency, check $field->useRoles first. Note: this does not check that the page itself is viewable — use $page->viewable() for that. Note there is also $page->viewable($field).

if($field->viewable($page)) {
    echo $page->get($field->name);
}

editable(Page $page = null, User $user = null)

Check if the field is editable on the given page by the given user. To maximize efficiency, check $field->useRoles first. Note: this does not check that the page itself is editable — use $page->editable() or $page->editable($field) for that.

if($field->editable($page)) {
    // user can edit this field on this page
}

Tags are space-separated strings stored on the field. Tag lookups are case-insensitive.

$tags / $tagList

The tags property returns a space-separated string. The tagList property returns an array (read-only).

echo $field->tags;   // "foo bar"
print_r($field->tagList); // ['foo' => 'foo', 'bar' => 'bar']

getTags($getString = false)

Get tags as an array, or as a space-separated string when $getString is true.

$tags = $field->getTags();        // array
$tagsStr = $field->getTags(true); // "foo bar"

setTags($tagList, $reindex = true)

Set all tags at once. Accepts an array or space-separated string.

$field->setTags(['foo', 'bar']);
$field->setTags('foo bar');

addTag($tag)

Add a single tag. Returns the current tag list.

$field->addTag('featured');

removeTag($tag)

Remove a tag. Returns the current tag list.

$field->removeTag('featured');

hasTag($tag)

Check if the field has the given tag (case-insensitive).

if($field->hasTag('featured')) {
    // field has the "featured" tag
}

• Field objects are managed by the $fields API variable ($fields->get(), $fields->save(), etc.).
• Manipulations to a Field are not saved until $field->save() is called.
• The __toString() method returns the field name.
• System fields (with flagSystem) cannot be renamed or deleted. Use flagSystemOverride to override.
• The database table name is field_ + field name, truncated to 64 characters.
• Setting useRoles to true/false automatically adds/removes flagAccess.
• Tag operations are case-insensitive — adding "Foo" when "foo" exists will not duplicate.
• getLabel() returns the field name when no label is set.
• Source file: wire/core/Field/Field.php.