Fields

Type

Class

Namespace

craft\services

Inherits

craft\services\Fields » yii\base\Component » yii\base\BaseObject

Implements

yii\base\Configurable

Since

3.0.0

Fields service.

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

View source

Public Properties

Property	Description
allFieldTypes	string[] – The available field type classes
allFields	craft\base\FieldInterface[] – The fields
allLayouts	craft\models\FieldLayout[]
behaviors	yii\base\Behavior – List of behaviors attached to this component.
fieldContext	string – The active field context
fieldTypesWithContent	string[] – The field type classes
fieldVersion	string, null
fieldsWithContent	craft\base\FieldInterface[] – The fields
fieldsWithoutContent	craft\base\FieldInterface[] – The fields
nestedEntryFieldTypes	string[] – The field type classes which manage nested entries

allFieldTypes

Type

string[]

Default value

null

Access

Read-only

The available field type classes

View source

allFields

Type

craft\base\FieldInterface[]

Default value

null

Access

Read-only

The fields

View source

allLayouts

Type

craft\models\FieldLayout[]

Default value

null

Access

Read-only

Since

5.0.0

View source

fieldContext

Type

string

Default value

'global'

Since

5.0.0

The active field context

View source

fieldTypesWithContent

Type

string[]

Default value

null

Access

Read-only

The field type classes

View source

fieldVersion

Type

string, null

Default value

null

Access

Read-only

Since

3.7.21

View source

fieldsWithContent

Type

craft\base\FieldInterface[]

Default value

null

Access

Read-only

The fields

View source

fieldsWithoutContent

Type

craft\base\FieldInterface[]

Default value

null

Access

Read-only

Since

4.3.2

The fields

View source

nestedEntryFieldTypes

Type

string[]

Default value

null

Access

Read-only

The field type classes which manage nested entries

View source

Public Methods

Method	Description
__call()	Calls the named method which is not a class method.
__clone()	This method is called after the object is created by cloning an existing one.
__construct()	Constructor.
__get()	Returns the value of a component property.
__isset()	Checks if a property is set, i.e. defined and not null.
__serialize()	Serializer
__set()	Sets the value of a component property.
__unset()	Sets a component property to be null.
applyFieldDelete()	Applies a field delete to the database.
applyFieldSave()	Applies a field save to the database.
assembleLayoutFromPost()	Assembles a field layout from post data.
attachBehavior()	Attaches a behavior to this component.
attachBehaviors()	Attaches a list of behaviors to the component.
behaviors()	Returns a list of behaviors that this component should behave as.
canGetProperty()	Returns a value indicating whether a property can be read.
canSetProperty()	Returns a value indicating whether a property can be set.
className()	Returns the fully qualified name of this class.
createField()	Creates a field with a given config.
createFieldConfig()	Returns the config for the given field.
createLayout()	Creates a field layout from the given config.
createLayoutElement()	Creates a field layout element instance from its config.
deleteField()	Deletes a field.
deleteFieldById()	Deletes a field 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()	Detaches a behavior from the component.
detachBehaviors()	Detaches all behaviors from the component.
doesFieldWithHandleExist()	Returns whether a field exists with a given handle and context.
ensureBehaviors()	Makes sure that the behaviors declared in behaviors() are attached to this component.
findFieldUsages()	Returns all the field layouts that contain the given field.
getAllFieldTypes()	Returns all available field type classes.
getAllFields()	Returns all fields within a field context(s).
getAllLayouts()	Returns all saved field layouts.
getBehavior()	Returns the named behavior object.
getBehaviors()	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.
getFieldTypesWithContent()	Returns all field types that have a column in the content table.
getFieldVersion()	Returns the current field version.
getFieldsByType()	Returns all fields of a certain type.
getFieldsWithContent()	Returns all fields that store content in the elements_sites.content table.
getFieldsWithoutContent()	Returns all fields that don’t store content in the elements_sites.content table.
getLayoutById()	Returns a field layout by its ID.
getLayoutByType()	Returns a field layout by its associated element type.
getLayoutByUid()	Returns a field layout by its UUID.
getLayoutsByIds()	Returns field layouts by their IDs.
getLayoutsByType()	Returns all of the field layouts associated with a given element type.
getNestedEntryFieldTypes()	Returns all field types which manage nested entries.
handleChangedField()	Handle field changes.
handleDeletedField()	Handle a field getting deleted.
hasEventHandlers()	Returns a value indicating whether there is any handler attached to the named event.
hasMethod()	Returns a value indicating whether a method is defined.
hasProperty()	Returns a value indicating whether a property is defined for this component.
init()	Initializes the object.
off()	Detaches an existing event handler from this component.
on()	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.
saveLayout()	Saves a field layout.
trigger()	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

applyFieldDelete()

Since

3.1.0

Applies a field delete to the database.

View source

Arguments

• $fieldUid (string)

Throws

• Throwable
  if database error

applyFieldSave()

Since

3.1.0

Applies a field save to the database.

View source

Arguments

• $fieldUid (string)
• $data (array)
• $context (string)

assembleLayoutFromPost()

Assembles a field layout from post data.

View source

Arguments

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

Returns

craft\models\FieldLayout – The field layout

Throws

• yii\web\BadRequestHttpException

createField()

Creates a field with a given config.

View source

Arguments

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

Returns

\craft\services\T – The field

createFieldConfig()

Since

3.1.0

Returns the config for the given field.

View source

Arguments

• $field (craft\base\FieldInterface)

Returns

array

createLayout()

Since

4.0.0

Creates a field layout from the given config.

View source

Arguments

• $config (array)

Returns

craft\models\FieldLayout

createLayoutElement()

Since

3.5.0

Creates a field layout element instance from its config.

View source

Arguments

• $config (array)

Returns

\craft\services\T

Throws

• yii\base\InvalidArgumentException
  if $config['type'] does not implement craft\base\FieldLayoutElement

deleteField()

Deletes a field.

View source

Arguments

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

Returns

boolean – Whether the field was deleted successfully

Throws

• Throwable
  if reasons

deleteFieldById()

Deletes a field by its ID.

View source

Arguments

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

Returns

boolean – Whether the field was deleted successfully

deleteLayout()

Deletes a field layout.

View source

Arguments

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

Returns

boolean – Whether the field layout was deleted successfully

deleteLayoutById()

Deletes a field layout(s) by its ID.

View source

Arguments

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

Returns

boolean – Whether the field layout was deleted successfully

deleteLayoutsByType()

Deletes field layouts associated with a given element type.

View source

Arguments

• $type (string) – The element type

Returns

boolean – Whether the field layouts were deleted successfully

doesFieldWithHandleExist()

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

View source

Arguments

• $handle (string) – The field handle
• $context (string, null) – The field context (defauts to craft\services\Fields::$fieldContext)

Returns

boolean – Whether a field with that handle exists

findFieldUsages()

Since

5.0.0

Returns all the field layouts that contain the given field.

View source

Arguments

• $field (craft\base\FieldInterface)

Returns

craft\models\FieldLayout[]

getAllFieldTypes()

Returns all available field type classes.

View source

Returns

string[] – The available field type classes

getAllFields()

Returns all fields within a field context(s).

View source

Arguments

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

Returns

craft\base\FieldInterface[] – The fields

getAllLayouts()

Since

5.0.0

Returns all saved field layouts.

View source

Returns

craft\models\FieldLayout[]

getCompatibleFieldTypes()

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

View source

Arguments

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

Returns

string[] – The compatible field type classes

getFieldByHandle()

Returns a field by its handle and optional context.

View source

Arguments

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

Returns

craft\base\FieldInterface, null – The field, or null if it doesn’t exist

---

Example

php

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

twig

{% set body = craft.app.fields.getFieldByHandle('body') %}
{{ body.instructions }}

getFieldById()

Returns a field by its ID.

View source

Arguments

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

Returns

craft\base\FieldInterface, null – The field, or null if it doesn’t exist

getFieldByUid()

Returns a field by its UID.

View source

Arguments

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

Returns

craft\base\FieldInterface, null – The field, or null if it doesn’t exist

getFieldTypesWithContent()

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

View source

Returns

string[] – The field type classes

getFieldVersion()

Since

3.7.21

Returns the current field version.

View source

Returns

string, null

getFieldsByType()

Since

4.4.0

Returns all fields of a certain type.

View source

Arguments

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

Returns

craft\base\FieldInterface[] – The fields

getFieldsWithContent()

Returns all fields that store content in the elements_sites.content table.

View source

Arguments

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

Returns

craft\base\FieldInterface[] – The fields

getFieldsWithoutContent()

Since

4.3.2

Returns all fields that don’t store content in the elements_sites.content table.

View source

Arguments

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

Returns

craft\base\FieldInterface[] – The fields

getLayoutById()

Returns a field layout by its ID.

View source

Arguments

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

Returns

craft\models\FieldLayout, null – The field layout, or null if it doesn’t exist

getLayoutByType()

Returns a field layout by its associated element type.

View source

Arguments

• $type (string) – The associated element type

Returns

craft\models\FieldLayout – The field layout

getLayoutByUid()

Returns a field layout by its UUID.

View source

Arguments

• $uid (string) – The field layout’s UUID

Returns

craft\models\FieldLayout, null – The field layout, or null if it doesn’t exist

getLayoutsByIds()

Since

3.7.27

Returns field layouts by their IDs.

View source

Arguments

• $layoutIds (integer[]) – 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

Arguments

• $type (string)

Returns

craft\models\FieldLayout[] – The field layouts

getNestedEntryFieldTypes()

Returns all field types which manage nested entries.

View source

Returns

string[] – The field type classes which manage nested entries

handleChangedField()

Handle field changes.

View source

Arguments

• $event (craft\events\ConfigEvent)

Throws

• Throwable

handleDeletedField()

Handle a field getting deleted.

View source

Arguments

• $event (craft\events\ConfigEvent)

prepFieldForSave()

Since

3.1.2

Preps a field to be saved.

View source

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

restoreLayoutById()

Since

3.1.0

Restores a field layout by its ID.

View source

Arguments

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

Returns

boolean – Whether the layout was restored successfully

saveField()

Saves a field.

View source

Arguments

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

Returns

boolean – Whether the field was saved successfully

Throws

• Throwable
  if reasons

saveLayout()

Saves a field layout.

View source

Arguments

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

Returns

boolean – Whether the field layout was saved successfully

Throws

• yii\base\Exception
  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

Events

EVENT_AFTER_DELETE_FIELD

Type

craft\events\FieldEvent

The event that is triggered after a field 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_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_DELETE_FIELD

Type

craft\events\FieldEvent

The event that is triggered before a field 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_LAYOUT

Type

craft\events\FieldLayoutEvent

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

---

EVENT_DEFINE_COMPATIBLE_FIELD_TYPES

Type

craft\events\DefineCompatibleFieldTypesEvent

Since

4.5.7

The event that is triggered when defining the compatible field types for a field.

See also getCompatibleFieldTypes()

---

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 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;
    }
);

EVENT_REGISTER_NESTED_ENTRY_FIELD_TYPES

Type

craft\events\RegisterComponentTypesEvent

Since

5.0.0

The event that is triggered when registering field types which manage nested entries.

These field types must implement craft\base\ElementContainerFieldInterface.

---