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 Matrix service is globally accessible in Craft via Craft::$app->matrix.
# Public Properties
| Property | Description |
|---|---|
| allBlockTypes | craft\models\MatrixBlockType[] – An array of block types. |
| behaviors | yii\base\Behavior – List of behaviors attached to this component |
| ignoreProjectConfigChanges | boolean – Whether to ignore changes to the project config. |
# allBlockTypes
- Type
- craft\models\MatrixBlockType[]
- Default value
null- Access
- Read-only
- Since
- 3.3.0
An array of block types.
# ignoreProjectConfigChanges
DEPRECATED
Deprecated in 3.1.2. Use craft\services\ProjectConfig::$muteEvents instead.
- Type
- boolean
- Default value
false
Whether to ignore changes to the project config.
# 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 an object property. |
| __isset() | Checks if a property is set, i.e. defined and not null. |
| __set() | Sets value of an object property. |
| __unset() | Sets an object property to 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. |
| 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. |
| 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. |
| getContentTableName() | Returns the content table name for a given Matrix field. |
| getSupportedSiteIds() | Returns the site IDs that are supported by Matrix blocks for the given propagation method and owner element. |
| getSupportedSiteIdsForField() | Returns the site IDs that are supported by Matrix blocks for the given Matrix field 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. |
| init() | Initializes the object. |
| 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. |
# defineContentTableName()
- Since
- 3.0.23
Defines a new Matrix content table name.
Arguments
$field(craft\fields\Matrix)
Returns
# deleteBlockType()
Deletes a block type.
Arguments
$blockType(craft\models\MatrixBlockType) – The block type.
Returns
boolean – Whether the block type was deleted successfully.
# deleteMatrixField()
Deletes a Matrix field.
Arguments
$matrixField(craft\fields\Matrix) – The Matrix field.
Returns
boolean – Whether the field was deleted successfully.
Throws
# duplicateBlocks()
- Since
- 3.2.0
Duplicates Matrix blocks from one owner element to another.
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
Throws
- Throwable
if reasons
# getAllBlockTypes()
- Since
- 3.3.0
Returns all the block types.
Returns
craft\models\MatrixBlockType[] – An array of block types.
# getBlockById()
Returns a block by its ID.
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.
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.
Arguments
$fieldId(integer) – The Matrix field ID.
Returns
craft\models\MatrixBlockType[] – An array of block types.
# getContentTableName()
DEPRECATED
Deprecated in 3.0.23. Use craft\fields\Matrix::$contentTable instead.
Returns the content table name for a given Matrix field.
Arguments
$matrixField(craft\fields\Matrix) – The Matrix field.
Returns
string, false – The table name, or false if $useOldHandle was set to true and there was no old handle.
# getSupportedSiteIds()
- Since
- 3.3.18
Returns the site IDs that are supported by Matrix blocks for the given propagation method and owner element.
Arguments
$propagationMethod(string)$owner(craft\base\ElementInterface)
Returns
integer[]
# getSupportedSiteIdsForField()
DEPRECATED
Deprecated in 3.3.18. Use getSupportedSiteIds() instead.
- Since
- 3.2.0
Returns the site IDs that are supported by Matrix blocks for the given Matrix field and owner element.
Arguments
$field(craft\fields\Matrix)$owner(craft\base\ElementInterface)
Returns
integer[]
# handleChangedBlockType()
Handle block type change
Arguments
$event(craft\events\ConfigEvent)
# handleDeletedBlockType()
Handle block type change
Arguments
$event(craft\events\ConfigEvent)
Throws
- Throwable
if reasons
# saveBlockType()
Saves a block type.
Arguments
$blockType(craft\models\MatrixBlockType) – The block type to be saved.$runValidation(boolean) – Whether the block type should be validated before being saved. Defaults totrue.
Returns
Throws
- yii\base\Exception
if an error occurs when saving the block type - Throwable
if reasons
# saveField()
Saves a Matrix field.
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.
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.
Arguments
$blockType(craft\models\MatrixBlockType) – The block type.$validateUniques(boolean) – Whether the Name and Handle attributes should be validated to ensure they’re unique. Defaults totrue.
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.
Arguments
$matrixField(craft\fields\Matrix) – The Matrix field
Returns
boolean – Whether the settings validated.
# Constants
| Constant | Description |
|---|---|
CONFIG_BLOCKTYPE_KEY |