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 Matrix service is globally accessible in Craft via Craft::$app->matrix.
View source (opens new window)
# 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 |
| ignoreProjectConfigChanges | boolean (opens new window) – 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.
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)
# 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 an object property. |
| __isset() (opens new window) | Checks if a property is set, i.e. defined and not null. |
| __set() (opens new window) | Sets value of an object property. |
| __unset() (opens new window) | Sets an object property to 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. |
| 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. |
| 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. |
| 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() (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. |
| 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. |
| 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. |
# defineContentTableName()
- Since
- 3.0.23
Defines a new Matrix content table name.
View source (opens new window)
Arguments
$field(craft\fields\Matrix)
Returns
# 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
# 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
Throws
- Throwable (opens new window)
if reasons
# 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.
# getContentTableName()
DEPRECATED
Deprecated in 3.0.23. Use craft\fields\Matrix::$contentTable instead.
Returns the content table name for a given Matrix field.
View source (opens new window)
Arguments
$matrixField(craft\fields\Matrix) – The Matrix field.
Returns
string (opens new window), false (opens new window) – 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.
View source (opens new window)
Arguments
$propagationMethod(string (opens new window))$owner(craft\base\ElementInterface)
Returns
# 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.
View source (opens new window)
Arguments
$field(craft\fields\Matrix)$owner(craft\base\ElementInterface)
Returns
# 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
# 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 totrue.
Returns
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.$validateUniques(boolean (opens new window)) – Whether the Name and Handle attributes should be validated to ensure they’re unique. Defaults totrue.
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.
# Constants
| Constant | Description |
|---|---|
CONFIG_BLOCKTYPE_KEY |