Matrix

Type

Class

Namespace

craft\services

Inherits

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

Implements

yii\base\Configurable

Since

3.0.0

The Matrix service provides APIs for managing Matrix fields.

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

View source

Public Properties

Property	Description
allBlockTypes	craft\models\MatrixBlockType[] – An array of block types.
behaviors	yii\base\Behavior – List of behaviors attached to this component.

allBlockTypes

Type

craft\models\MatrixBlockType[]

Default value

null

Access

Read-only

Since

3.3.0

An array of block types.

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.
__set()	Sets the value of a component property.
__unset()	Sets a component property to be null.
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.
createRevisionBlocks()	Creates revisions for all the blocks that belong to the given canonical element, and assigns those revisions to the given owner revision.
defineContentTableName()	Defines a new Matrix content table name.
deleteBlockType()	Deletes a block type.
deleteMatrixField()	Deletes a Matrix field.
detachBehavior()	Detaches a behavior from the component.
detachBehaviors()	Detaches all behaviors from the component.
duplicateBlocks()	Duplicates Matrix blocks from one owner element to another.
duplicateOwnership()	Duplicates block ownership relations for a new draft element.
ensureBehaviors()	Makes sure that the behaviors declared in behaviors() are attached to this component.
getAllBlockTypes()	Returns all the block types.
getBehavior()	Returns the named behavior object.
getBehaviors()	Returns all behaviors attached to this component.
getBlockById()	Returns a block by its ID.
getBlockTypeById()	Returns a block type by its ID.
getBlockTypesByFieldId()	Returns the block types for a given Matrix field.
getSupportedSiteIds()	Returns the site IDs that are supported by Matrix blocks for the given propagation method and owner element.
handleChangedBlockType()	Handle block type change
handleDeletedBlockType()	Handle block type change
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.
mergeCanonicalChanges()	Merges recent canonical Matrix block changes into the given Matrix field’s blocks.
off()	Detaches an existing event handler from this component.
on()	Attaches an event handler to an event.
saveBlockType()	Saves a block type.
saveField()	Saves a Matrix field.
saveSettings()	Saves a Matrix field's settings.
trigger()	Triggers an event.
validateBlockType()	Validates a block type.
validateFieldSettings()	Validates a Matrix field's settings.

createRevisionBlocks()

Since

4.0.0

Creates revisions for all the blocks that belong to the given canonical element, and assigns those revisions to the given owner revision.

View source

Arguments

• $field (craft\fields\Matrix) – The Matrix field
• $canonical (craft\base\ElementInterface) – The canonical element
• $revision (craft\base\ElementInterface) – The revision element

defineContentTableName()

Since

3.0.23

Defines a new Matrix content table name.

View source

Arguments

• $field (craft\fields\Matrix)

Returns

string

deleteBlockType()

Deletes a block type.

View source

Arguments

• $blockType (craft\models\MatrixBlockType) – The block type.

Returns

boolean – Whether the block type was deleted successfully.

deleteMatrixField()

Deletes a Matrix field.

View source

Arguments

• $matrixField (craft\fields\Matrix) – The Matrix field.

Returns

boolean – Whether the field was deleted successfully.

Throws

• Throwable

duplicateBlocks()

Since

3.2.0

Duplicates Matrix blocks from one owner element to another.

View source

Arguments

• $field (craft\fields\Matrix) – The Matrix field to duplicate blocks for
• $source (craft\base\ElementInterface) – The source element blocks should be duplicated from
• $target (craft\base\ElementInterface) – The target element blocks should be duplicated to
• $checkOtherSites (boolean) – Whether to duplicate blocks for the source element’s other supported sites
• $deleteOtherBlocks (boolean) – Whether to delete any blocks that belong to the element, which weren’t included in the duplication
• $trackDuplications (boolean) – Whether to keep track of the duplications from craft\services\Elements::$duplicatedElementIds and craft\services\Elements::$duplicatedElementSourceIds
• $force (boolean) – Whether to force duplication, even if it looks like only the block ownership was duplicated

Throws

• Throwable
  if reasons

duplicateOwnership()

Since

4.0.0

Duplicates block ownership relations for a new draft element.

View source

Arguments

• $field (craft\fields\Matrix) – The Matrix field
• $canonical (craft\base\ElementInterface) – The canonical element
• $draft (craft\base\ElementInterface) – The draft element

getAllBlockTypes()

Since

3.3.0

Returns all the block types.

View source

Returns

craft\models\MatrixBlockType[] – An array of block types.

getBlockById()

Returns a block by its ID.

View source

Arguments

• $blockId (integer) – The Matrix block’s ID.
• $siteId (integer, null) – The site ID to return. Defaults to the current site.

Returns

craft\elements\MatrixBlock, null – The Matrix block, or null if it didn’t exist.

getBlockTypeById()

Returns a block type by its ID.

View source

Arguments

• $blockTypeId (integer) – The block type ID.

Returns

craft\models\MatrixBlockType, null – The block type, or null if it didn’t exist.

getBlockTypesByFieldId()

Returns the block types for a given Matrix field.

View source

Arguments

• $fieldId (integer) – The Matrix field ID.

Returns

craft\models\MatrixBlockType[] – An array of block types.

getSupportedSiteIds()

Since

3.3.18

Returns the site IDs that are supported by Matrix blocks for the given propagation method and owner element.

View source

Arguments

• $propagationMethod (string)
• $owner (craft\base\ElementInterface)
• $propagationKeyFormat (string, null)

Returns

integer[]

handleChangedBlockType()

Handle block type change

View source

Arguments

• $event (craft\events\ConfigEvent)

handleDeletedBlockType()

Handle block type change

View source

Arguments

• $event (craft\events\ConfigEvent)

Throws

• Throwable
  if reasons

mergeCanonicalChanges()

Since

3.7.0

Merges recent canonical Matrix block changes into the given Matrix field’s blocks.

View source

Arguments

• $field (craft\fields\Matrix) – The Matrix field
• $owner (craft\base\ElementInterface) – The element the field is associated with

saveBlockType()

Saves a block type.

View source

Arguments

• $blockType (craft\models\MatrixBlockType) – The block type to be saved.
• $runValidation (boolean) – Whether the block type should be validated before being saved. Defaults to true.

Returns

boolean

Throws

• yii\base\Exception
  if an error occurs when saving the block type
• Throwable
  if reasons

saveField()

Saves a Matrix field.

View source

Arguments

• $field (craft\fields\Matrix) – The Matrix field
• $owner (craft\base\ElementInterface) – The element the field is associated with

Throws

• Throwable
  if reasons

saveSettings()

Saves a Matrix field's settings.

View source

Arguments

• $matrixField (craft\fields\Matrix) – The Matrix field
• $validate (boolean) – Whether the settings should be validated before being saved.

Returns

boolean – Whether the settings saved successfully.

Throws

• Throwable
  if reasons

validateBlockType()

Validates a block type.

If the block type doesn’t validate, any validation errors will be stored on the block type.

View source

Arguments

• $blockType (craft\models\MatrixBlockType) – The block type.

Returns

boolean – Whether the block type validated.

validateFieldSettings()

Validates a Matrix field's settings.

If the settings don’t validate, any validation errors will be stored on the settings model.

View source

Arguments

• $matrixField (craft\fields\Matrix) – The Matrix field

Returns

boolean – Whether the settings validated.