Fields

Type

Class

Namespace

craft\services

Inherits

craft\services\Fields » yii\base\Component (opens new window) » yii\base\BaseObject (opens new window)

Implements

yii\base\Configurable (opens new window)

Since

3.0.0

Fields service.

An instance of the service is available via Craft::$app->fields.

View source (opens new window)

Public Properties

Property	Description
allFieldTypes	string (opens new window)[] – The available field type classes
allFields	craft\base\FieldInterface[] – The fields
allGroups	craft\models\FieldGroup[] – The field groups
behaviors (opens new window)	yii\base\Behavior (opens new window) – List of behaviors attached to this component.
fieldTypesWithContent	string (opens new window)[] – The field type classes
fieldVersion	string (opens new window), null (opens new window)
fieldsWithContent	craft\base\FieldInterface[] – The fields
fieldsWithoutContent	craft\base\FieldInterface[] – The fields
ignoreProjectConfigChanges	boolean (opens new window) – Whether to ignore changes to the project config.
oldFieldColumnPrefix	string (opens new window), null (opens new window)

allFieldTypes

Type

string (opens new window)[]

Default value

null

Access

Read-only

The available field type classes

View source (opens new window)

allFields

Type

craft\base\FieldInterface[]

Default value

null

Access

Read-only

The fields

View source (opens new window)

allGroups

Type

craft\models\FieldGroup[]

Default value

null

Access

Read-only

The field groups

View source (opens new window)

fieldTypesWithContent

Type

string (opens new window)[]

Default value

null

Access

Read-only

The field type classes

View source (opens new window)

fieldVersion

Type

string (opens new window), null (opens new window)

Default value

null

Access

Read-only

Since

3.7.21

View source (opens new window)

fieldsWithContent

Type

craft\base\FieldInterface[]

Default value

null

Access

Read-only

The fields

View source (opens new window)

fieldsWithoutContent

Type

craft\base\FieldInterface[]

Default value

null

Access

Read-only

Since

3.7.60

The fields

View source (opens new window)

ignoreProjectConfigChanges

DEPRECATED

Deprecated in 3.1.2. Use craft\services\ProjectConfig::$muteEvents instead.

Type

boolean (opens new window)

Default value

false

Whether to ignore changes to the project config.

View source (opens new window)

oldFieldColumnPrefix

Type

string (opens new window), null (opens new window)

Default value

null

View source (opens new window)

Public Methods

Method	Description
__call() (opens new window)	Calls the named method which is not a class method.
__clone() (opens new window)	This method is called after the object is created by cloning an existing one.
__construct() (opens new window)	Constructor.
__get() (opens new window)	Returns the value of a component property.
__isset() (opens new window)	Checks if a property is set, i.e. defined and not null.
__serialize()	Serializer
__set() (opens new window)	Sets the value of a component property.
__unset() (opens new window)	Sets a component property to be null.
applyFieldDelete()	Applies a field delete to the database.
applyFieldSave()	Applies a field save to the database.
assembleLayout()	Assembles a field layout.
assembleLayoutFromPost()	Assembles a field layout from post data.
attachBehavior() (opens new window)	Attaches a behavior to this component.
attachBehaviors() (opens new window)	Attaches a list of behaviors to the component.
behaviors() (opens new window)	Returns a list of behaviors that this component should behave as.
canGetProperty() (opens new window)	Returns a value indicating whether a property can be read.
canSetProperty() (opens new window)	Returns a value indicating whether a property can be set.
className() (opens new window)	Returns the fully qualified name of this class.
createField()	Creates a field with a given config.
createFieldConfig()	Returns the config for the given field.
createLayoutElement()	Creates a field layout element instance from its config.
deleteField()	Deletes a field.
deleteFieldById()	Deletes a field by its ID.
deleteGroup()	Deletes a field group.
deleteGroupById()	Deletes a field group by its ID.
deleteLayout()	Deletes a field layout.
deleteLayoutById()	Deletes a field layout(s) by its ID.
deleteLayoutsByType()	Deletes field layouts associated with a given element type.
detachBehavior() (opens new window)	Detaches a behavior from the component.
detachBehaviors() (opens new window)	Detaches all behaviors from the component.
doesFieldWithHandleExist()	Returns whether a field exists with a given handle and context.
ensureBehaviors() (opens new window)	Makes sure that the behaviors declared in behaviors() (opens new window) are attached to this component.
getAllFieldTypes()	Returns all available field type classes.
getAllFields()	Returns all fields within a field context(s).
getAllGroups()	Returns all field groups.
getBehavior() (opens new window)	Returns the named behavior object.
getBehaviors() (opens new window)	Returns all behaviors attached to this component.
getCompatibleFieldTypes()	Returns all field types whose column types are considered compatible with a given field.
getFieldByHandle()	Returns a field by its handle and optional context.
getFieldById()	Returns a field by its ID.
getFieldByUid()	Returns a field by its UID.
getFieldIdsByLayoutId()	Returns the field IDs for a given layout ID.
getFieldIdsByLayoutIds()	Returns the field IDs grouped by layout IDs, for a given set of layout IDs.
getFieldTypesWithContent()	Returns all field types that have a column in the content table.
getFieldVersion()	Returns the current field version.
getFieldsByElementType()	Returns all of the fields used by a given element type.
getFieldsByGroupId()	Returns all the fields in a given group.
getFieldsByLayoutId()	Returns the fields in a field layout, identified by its ID.
getFieldsWithContent()	Returns all fields that have a column in the content table.
getFieldsWithoutContent()	Returns all fields that don’t have a column in the content table.
getGroupById()	Returns a field group by its ID.
getGroupByUid()	Returns a field group by its UID.
getLayoutById()	Returns a field layout by its ID.
getLayoutByType()	Returns a field layout by its associated element type.
getLayoutTabsById()	Returns a layout's tabs by its ID.
getLayoutsByIds()	Returns field layouts by their IDs.
getLayoutsByType()	Returns all of the field layouts associated with a given element type.
handleChangedField()	Handle field changes.
handleChangedGroup()	Handle field group change
handleDeletedField()	Handle a field getting deleted.
handleDeletedGroup()	Handle field group getting deleted.
hasEventHandlers() (opens new window)	Returns a value indicating whether there is any handler attached to the named event.
hasMethod() (opens new window)	Returns a value indicating whether a method is defined.
hasProperty() (opens new window)	Returns a value indicating whether a property is defined for this component.
init() (opens new window)	Initializes the object.
off() (opens new window)	Detaches an existing event handler from this component.
on() (opens new window)	Attaches an event handler to an event.
prepFieldForSave()	Preps a field to be saved.
refreshFields()	Refreshes the internal field cache.
restoreLayoutById()	Restores a field layout by its ID.
saveField()	Saves a field.
saveGroup()	Saves a field group.
saveLayout()	Saves a field layout.
trigger() (opens new window)	Triggers an event.
updateFieldVersion()	Sets a new field version, so the CustomFieldBehavior class will get regenerated on the next request.

__serialize()

Since

3.5.14

Serializer

View source (opens new window)

applyFieldDelete()

Since

3.1.0

Applies a field delete to the database.

View source (opens new window)

Arguments

• $fieldUid

Throws

• Throwable (opens new window)
  if database error

applyFieldSave()

Since

3.1.0

Applies a field save to the database.

View source (opens new window)

Arguments

• $fieldUid (string (opens new window))
• $data (array (opens new window))
• $context (string (opens new window))

assembleLayout()

DEPRECATED

Deprecated in 3.5.0.

Assembles a field layout.

View source (opens new window)

Arguments

• $postedFieldLayout (array (opens new window)) – The post data for the field layout
• $requiredFields (array (opens new window)) – The field IDs that should be marked as required in the field layout

Returns

craft\models\FieldLayout – The field layout

assembleLayoutFromPost()

Assembles a field layout from post data.

View source (opens new window)

Arguments

• $namespace (string (opens new window), null (opens new window)) – The namespace that the form data was posted in, if any

Returns

craft\models\FieldLayout – The field layout

Throws

• yii\web\BadRequestHttpException (opens new window)

createField()

Creates a field with a given config.

View source (opens new window)

Arguments

• $config (mixed) – The field’s class name, or its config, with a type value and optionally a settings value

Returns

craft\base\FieldInterface – The field

createFieldConfig()

Since

3.1.0

Returns the config for the given field.

View source (opens new window)

Arguments

• $field (craft\base\FieldInterface)

Returns

array (opens new window)

createLayoutElement()

Since

3.5.0

Creates a field layout element instance from its config.

View source (opens new window)

Arguments

• $config (array (opens new window))

Returns

craft\base\FieldLayoutElementInterface

Throws

• yii\base\InvalidArgumentException (opens new window)
  if $config['type'] does not implement craft\base\FieldLayoutElementInterface

deleteField()

Deletes a field.

View source (opens new window)

Arguments

• $field (craft\base\FieldInterface) – The field

Returns

boolean (opens new window) – Whether the field was deleted successfully

Throws

• Throwable (opens new window)
  if reasons

deleteFieldById()

Deletes a field by its ID.

View source (opens new window)

Arguments

• $fieldId (integer (opens new window)) – The field’s ID

Returns

boolean (opens new window) – Whether the field was deleted successfully

deleteGroup()

Deletes a field group.

View source (opens new window)

Arguments

• $group (craft\models\FieldGroup) – The field group

Returns

boolean (opens new window) – Whether the field group was deleted successfully

deleteGroupById()

Deletes a field group by its ID.

View source (opens new window)

Arguments

• $groupId (integer (opens new window)) – The field group’s ID

Returns

boolean (opens new window) – Whether the field group was deleted successfully

deleteLayout()

Deletes a field layout.

View source (opens new window)

Arguments

• $layout (craft\models\FieldLayout) – The field layout

Returns

boolean (opens new window) – Whether the field layout was deleted successfully

deleteLayoutById()

Deletes a field layout(s) by its ID.

View source (opens new window)

Arguments

• $layoutId (integer (opens new window), integer (opens new window)[]) – The field layout’s ID

Returns

boolean (opens new window) – Whether the field layout was deleted successfully

deleteLayoutsByType()

Deletes field layouts associated with a given element type.

View source (opens new window)

Arguments

• $type (string (opens new window)) – The element type

Returns

boolean (opens new window) – Whether the field layouts were deleted successfully

doesFieldWithHandleExist()

Returns whether a field exists with a given handle and context.

View source (opens new window)

Arguments

• $handle (string (opens new window)) – The field handle
• $context (string (opens new window), null (opens new window)) – The field context (defauts to craft\services\Content::$fieldContext)

Returns

boolean (opens new window) – Whether a field with that handle exists

getAllFieldTypes()

Returns all available field type classes.

View source (opens new window)

Returns

string (opens new window)[] – The available field type classes

getAllFields()

Returns all fields within a field context(s).

View source (opens new window)

Arguments

• $context (string (opens new window), string (opens new window)[], false (opens new window), null (opens new window)) – The field context(s) to fetch fields from. Defaults to craft\services\Content::$fieldContext. Set to false to get all fields regardless of context.

Returns

craft\base\FieldInterface[] – The fields

getAllGroups()

Returns all field groups.

View source (opens new window)

Returns

craft\models\FieldGroup[] – The field groups

getCompatibleFieldTypes()

Returns all field types whose column types are considered compatible with a given field.

View source (opens new window)

Arguments

• $field (craft\base\FieldInterface) – The current field to base compatible fields on
• $includeCurrent (boolean (opens new window)) – Whether $field's class should be included

Returns

string (opens new window)[] – The compatible field type classes

getFieldByHandle()

Returns a field by its handle and optional context.

View source (opens new window)

Arguments

• $handle (string (opens new window)) – The field’s handle
• $context (string (opens new window), string (opens new window)[], false (opens new window), null (opens new window)) – The field context(s) to fetch fields from. Defaults to craft\services\Content::$fieldContext. Set to false to get all fields regardless of context.

Returns

craft\base\FieldInterface, null (opens new window) – The field, or null if it doesn’t exist

Example

• PHP
• Twig

$body = Craft::$app->fields->getFieldByHandle('body');

getFieldById()

Returns a field by its ID.

View source (opens new window)

Arguments

• $fieldId (integer (opens new window)) – The field’s ID

Returns

craft\base\FieldInterface, null (opens new window) – The field, or null if it doesn’t exist

getFieldByUid()

Returns a field by its UID.

View source (opens new window)

Arguments

• $fieldUid (string (opens new window)) – The field’s UID

Returns

craft\base\FieldInterface, null (opens new window) – The field, or null if it doesn’t exist

getFieldIdsByLayoutId()

Since

3.1.24

Returns the field IDs for a given layout ID.

View source (opens new window)

Arguments

• $layoutId (integer (opens new window)) – The field layout ID

Returns

integer (opens new window)[]

getFieldIdsByLayoutIds()

Returns the field IDs grouped by layout IDs, for a given set of layout IDs.

View source (opens new window)

Arguments

• $layoutIds (integer (opens new window)[]) – The field layout IDs

Returns

array (opens new window)

getFieldTypesWithContent()

Returns all field types that have a column in the content table.

View source (opens new window)

Returns

string (opens new window)[] – The field type classes

getFieldVersion()

Since

3.7.21

Returns the current field version.

View source (opens new window)

Returns

string (opens new window), null (opens new window)

getFieldsByElementType()

Returns all of the fields used by a given element type.

View source (opens new window)

Arguments

• $elementType (string (opens new window))

Returns

craft\base\FieldInterface[] – The fields

getFieldsByGroupId()

Returns all the fields in a given group.

View source (opens new window)

Arguments

• $groupId (integer (opens new window)) – The field group’s ID

Returns

craft\base\FieldInterface[] – The fields

getFieldsByLayoutId()

Returns the fields in a field layout, identified by its ID.

View source (opens new window)

Arguments

• $layoutId (integer (opens new window)) – The field layout’s ID

Returns

craft\base\FieldInterface[] – The fields

getFieldsWithContent()

Returns all fields that have a column in the content table.

View source (opens new window)

Arguments

• $context (string (opens new window), string (opens new window)[], false (opens new window), null (opens new window)) – The field context(s) to fetch fields from. Defaults to craft\services\Content::$fieldContext. Set to false to get all fields regardless of context.

Returns

craft\base\FieldInterface[] – The fields

getFieldsWithoutContent()

Since

3.7.60

Returns all fields that don’t have a column in the content table.

View source (opens new window)

Arguments

• $context (string (opens new window), string (opens new window)[], false (opens new window), null (opens new window)) – The field context(s) to fetch fields from. Defaults to craft\services\Content::$fieldContext. Set to false to get all fields regardless of context.

Returns

craft\base\FieldInterface[] – The fields

getGroupById()

Returns a field group by its ID.

View source (opens new window)

Arguments

• $groupId (integer (opens new window)) – The field group’s ID

Returns

craft\models\FieldGroup, null (opens new window) – The field group, or null if it doesn’t exist

getGroupByUid()

Since

3.3.0

Returns a field group by its UID.

View source (opens new window)

Arguments

• $groupUid (string (opens new window)) – The field group’s UID

Returns

craft\models\FieldGroup, null (opens new window) – The field group, or null if it doesn’t exist

getLayoutById()

Returns a field layout by its ID.

View source (opens new window)

Arguments

• $layoutId (integer (opens new window)) – The field layout’s ID

Returns

craft\models\FieldLayout, null (opens new window) – The field layout, or null if it doesn’t exist

getLayoutByType()

Returns a field layout by its associated element type.

View source (opens new window)

Arguments

• $type (string (opens new window)) – The associated element type

Returns

craft\models\FieldLayout – The field layout

getLayoutTabsById()

Returns a layout's tabs by its ID.

View source (opens new window)

Arguments

• $layoutId (integer (opens new window)) – The field layout’s ID

Returns

craft\models\FieldLayoutTab[] – The field layout’s tabs

getLayoutsByIds()

Since

3.7.27

Returns field layouts by their IDs.

View source (opens new window)

Arguments

• $layoutIds (integer (opens new window)[]) – The field layouts’ IDs

Returns

craft\models\FieldLayout[] – The field layouts

getLayoutsByType()

Since

3.5.0

Returns all of the field layouts associated with a given element type.

View source (opens new window)

Arguments

• $type (string (opens new window))

Returns

craft\models\FieldLayout[] – The field layouts

handleChangedField()

Handle field changes.

View source (opens new window)

Arguments

• $event (craft\events\ConfigEvent)

Throws

• Throwable (opens new window)

handleChangedGroup()

Handle field group change

View source (opens new window)

Arguments

• $event (craft\events\ConfigEvent)

handleDeletedField()

Handle a field getting deleted.

View source (opens new window)

Arguments

• $event (craft\events\ConfigEvent)

handleDeletedGroup()

Handle field group getting deleted.

View source (opens new window)

Arguments

• $event (craft\events\ConfigEvent)

prepFieldForSave()

Since

3.1.2

Preps a field to be saved.

View source (opens new window)

Arguments

• $field (craft\base\FieldInterface)

refreshFields()

Since

3.0.20

Refreshes the internal field cache.

This should be called whenever a field is updated or deleted directly in the database, rather than going through this service.

View source (opens new window)

restoreLayoutById()

Since

3.1.0

Restores a field layout by its ID.

View source (opens new window)

Arguments

• $id (integer (opens new window)) – The field layout’s ID

Returns

boolean (opens new window) – Whether the layout was restored successfully

saveField()

Saves a field.

View source (opens new window)

Arguments

• $field (craft\base\FieldInterface) – The Field to be saved
• $runValidation (boolean (opens new window)) – Whether the field should be validated

Returns

boolean (opens new window) – Whether the field was saved successfully

Throws

• Throwable (opens new window)
  if reasons

saveGroup()

Saves a field group.

View source (opens new window)

Arguments

• $group (craft\models\FieldGroup) – The field group to be saved
• $runValidation (boolean (opens new window)) – Whether the group should be validated

Returns

boolean (opens new window) – Whether the field group was saved successfully

saveLayout()

Saves a field layout.

View source (opens new window)

Arguments

• $layout (craft\models\FieldLayout) – The field layout
• $runValidation (boolean (opens new window)) – Whether the layout should be validated

Returns

boolean (opens new window) – Whether the field layout was saved successfully

Throws

• yii\base\Exception (opens new window)
  if $layout->id is set to an invalid layout ID

updateFieldVersion()

Sets a new field version, so the CustomFieldBehavior class will get regenerated on the next request.

View source (opens new window)

Protected Methods

Method	Description
updateColumn()	Adds/updates a field’s content table column.

updateColumn()

Since

3.7.39

Adds/updates a field’s content table column.

View source (opens new window)

Arguments

• $db (craft\db\Connection)
• $transaction (yii\db\Transaction (opens new window))
• $table (string (opens new window))
• $oldName (string (opens new window), null (opens new window))
• $newName (string (opens new window))
• $type (string (opens new window))

Returns

void

Constants

Constant	Description
CONFIG_FIELDGROUP_KEY
CONFIG_FIELDS_KEY

Events

EVENT_AFTER_DELETE_FIELD

Type

craft\events\FieldEvent

The event that is triggered after a field is deleted.

EVENT_AFTER_DELETE_FIELD_GROUP

Type

craft\events\FieldGroupEvent

The event that is triggered after a field group is deleted.

EVENT_AFTER_DELETE_FIELD_LAYOUT

Type

craft\events\FieldLayoutEvent

The event that is triggered after a field layout is deleted.

EVENT_AFTER_SAVE_FIELD

Type

craft\events\FieldEvent

The event that is triggered after a field is saved.

EVENT_AFTER_SAVE_FIELD_GROUP

Type

craft\events\FieldGroupEvent

The event that is triggered after a field group is saved.

EVENT_AFTER_SAVE_FIELD_LAYOUT

Type

craft\events\FieldLayoutEvent

The event that is triggered after a field layout is saved.

EVENT_BEFORE_APPLY_FIELD_DELETE

Type

craft\events\FieldEvent

Since

3.1.0

The event that is triggered before a field delete is applied to the database.

EVENT_BEFORE_APPLY_GROUP_DELETE

Type

craft\events\FieldGroupEvent

Since

3.1.0

The event that is triggered before a field group delete is applied to the database.

EVENT_BEFORE_DELETE_FIELD

Type

craft\events\FieldEvent

The event that is triggered before a field is deleted.

EVENT_BEFORE_DELETE_FIELD_GROUP

Type

craft\events\FieldGroupEvent

The event that is triggered before a field group is deleted.

EVENT_BEFORE_DELETE_FIELD_LAYOUT

Type

craft\events\FieldLayoutEvent

The event that is triggered before a field layout is deleted.

EVENT_BEFORE_SAVE_FIELD

Type

craft\events\FieldEvent

The event that is triggered before a field is saved.

EVENT_BEFORE_SAVE_FIELD_GROUP

Type

craft\events\FieldGroupEvent

The event that is triggered before a field group is saved.

EVENT_BEFORE_SAVE_FIELD_LAYOUT

Type

craft\events\FieldLayoutEvent

The event that is triggered before a field layout is saved.

EVENT_REGISTER_FIELD_TYPES

Type

craft\events\RegisterComponentTypesEvent

The event that is triggered when registering field types.

Field types must implement craft\base\FieldInterface. craft\base\Field provides a base implementation.

See Field Types (opens new window) for documentation on creating field types.

Example

• PHP

use craft\events\RegisterComponentTypesEvent;
use craft\services\Fields;
use yii\base\Event;

Event::on(Fields::class,
    Fields::EVENT_REGISTER_FIELD_TYPES,
    function(RegisterComponentTypesEvent $event) {
        $event->types[] = MyFieldType::class;
    }
);