Matrix

Type: Class
Namespace: craft\services
Inherits: craft\services\Matrix » yii\base\Component (opens new window) » yii\base\BaseObject (opens new window)
Implements: yii\base\Configurable (opens new window)
Since: 3.0.0

The Matrix service provides APIs for managing Matrix fields.

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

# Public Properties

Property	Description
allBlockTypes	craft\models\MatrixBlockType[] – An array of block types.
behaviors (opens new window)	yii\base\Behavior (opens new window) – 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 (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.
__set() (opens new window)	Sets the value of a component property.
__unset() (opens new window)	Sets a component property to be null.
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.
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() (opens new window)	Detaches a behavior from the component.
detachBehaviors() (opens new window)	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() (opens new window)	Makes sure that the behaviors declared in behaviors() (opens new window) are attached to this component.
getAllBlockTypes()	Returns all the block types.
getBehavior() (opens new window)	Returns the named behavior object.
getBehaviors() (opens new window)	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() (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.
mergeCanonicalChanges()	Merges recent canonical Matrix block changes into the given Matrix field’s blocks.
off() (opens new window)	Detaches an existing event handler from this component.
on() (opens new window)	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() (opens new window)	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 (opens new window)

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 (opens new window)

Arguments

$field (craft\fields\Matrix)

Returns

string (opens new window)

# `deleteBlockType()`

Deletes a block type.

View source (opens new window)

Arguments

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

Returns

boolean (opens new window) – Whether the block type was deleted successfully.

# `deleteMatrixField()`

Deletes a Matrix field.

View source (opens new window)

Arguments

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

Returns

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

Throws

Throwable (opens new window)

# `duplicateBlocks()`

Since: 3.2.0

Duplicates Matrix blocks from one owner element to another.

View source (opens new window)

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 (opens new window)) – Whether to duplicate blocks for the source element’s other supported sites
$deleteOtherBlocks (boolean (opens new window)) – Whether to delete any blocks that belong to the element, which weren’t included in the duplication
$trackDuplications (boolean (opens new window)) – Whether to keep track of the duplications from craft\services\Elements::$duplicatedElementIds and craft\services\Elements::$duplicatedElementSourceIds
$force (boolean (opens new window)) – Whether to force duplication, even if it looks like only the block ownership was duplicated

Throws

Throwable (opens new window)
if reasons

# `duplicateOwnership()`

Since: 4.0.0

Duplicates block ownership relations for a new draft element.

View source (opens new window)

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 (opens new window)

Returns

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

# `getBlockById()`

Returns a block by its ID.

View source (opens new window)

Arguments

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

Returns

craft\elements\MatrixBlock, null (opens new window) – The Matrix block, or null if it didn’t exist.

# `getBlockTypeById()`

Returns a block type by its ID.

View source (opens new window)

Arguments

$blockTypeId (integer (opens new window)) – The block type ID.

Returns

craft\models\MatrixBlockType, null (opens new window) – The block type, or null if it didn’t exist.

# `getBlockTypesByFieldId()`

Returns the block types for a given Matrix field.

View source (opens new window)

Arguments

$fieldId (integer (opens new window)) – 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 (opens new window)

Arguments

$propagationMethod (string (opens new window))
$owner (craft\base\ElementInterface)
$propagationKeyFormat (string (opens new window), null (opens new window))

Returns

integer (opens new window)[]

# `handleChangedBlockType()`

Handle block type change

View source (opens new window)

Arguments

$event (craft\events\ConfigEvent)

# `handleDeletedBlockType()`

Handle block type change

View source (opens new window)

Arguments

$event (craft\events\ConfigEvent)

Throws

Throwable (opens new window)
if reasons

# `mergeCanonicalChanges()`

Since: 3.7.0

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

View source (opens new window)

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 (opens new window)

Arguments

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

Returns

boolean (opens new window)

Throws

yii\base\Exception (opens new window)
if an error occurs when saving the block type
Throwable (opens new window)
if reasons

# `saveField()`

Saves a Matrix field.

View source (opens new window)

Arguments

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

Throws

Throwable (opens new window)
if reasons

# `saveSettings()`

Saves a Matrix field's settings.

View source (opens new window)

Arguments

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

Returns

boolean (opens new window) – Whether the settings saved successfully.

Throws

Throwable (opens new window)
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 (opens new window)

Arguments

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

Returns

boolean (opens new window) – 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 (opens new window)

Arguments

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

Returns

boolean (opens new window) – Whether the settings validated.

← Images Path →

Matrix

# Public Properties

# allBlockTypes

# Public Methods

# createRevisionBlocks()

Arguments

# defineContentTableName()

Arguments

Returns

# deleteBlockType()

Arguments

Returns

# deleteMatrixField()

Arguments

Returns

Throws

# duplicateBlocks()

Arguments

Throws

# duplicateOwnership()

Arguments

# getAllBlockTypes()

Returns

# getBlockById()

Arguments

Returns

# getBlockTypeById()

Arguments

Returns

# getBlockTypesByFieldId()

Arguments

Returns

# getSupportedSiteIds()

Arguments

Returns

# handleChangedBlockType()

Arguments

# handleDeletedBlockType()

Arguments

Throws

# mergeCanonicalChanges()

Arguments

# saveBlockType()

Arguments

Returns

Throws

# saveField()

Arguments

Throws

# saveSettings()

Arguments

Returns

Throws

# validateBlockType()

Arguments

Returns

# validateFieldSettings()

Arguments

Returns

# `allBlockTypes`

# `createRevisionBlocks()`

# `defineContentTableName()`

# `deleteBlockType()`

# `deleteMatrixField()`

# `duplicateBlocks()`

# `duplicateOwnership()`

# `getAllBlockTypes()`

# `getBlockById()`

# `getBlockTypeById()`

# `getBlockTypesByFieldId()`

# `getSupportedSiteIds()`

# `handleChangedBlockType()`

# `handleDeletedBlockType()`

# `mergeCanonicalChanges()`

# `saveBlockType()`

# `saveField()`

# `saveSettings()`

# `validateBlockType()`

# `validateFieldSettings()`