Matrix
- Type
- Class
- Namespace
- craft\services
- Inherits
- craft\services\Matrix » yii\base\Component » yii\base\BaseObject
- Implements
- yii\base\Configurable
- Since
- 3.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[]
- Access
- Read-only
An array of block types.
ignoreProjectConfigChanges
DEPRECATED
Deprecated in 3.1.2. Use craft\services\ProjectConfig::$muteEvents instead.
- Type
- boolean
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. |
| 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()
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
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::contentTableName 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.
getSupportedSiteIdsForField()
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 |