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 |