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 |
|---|---|
| $behaviors | yii\base\Behavior – List of behaviors attached to this component |
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. |
| deleteBlockType() | Deletes a block type. |
| deleteMatrixField() | Deletes a Matrix field. |
| detachBehavior() | Detaches a behavior from the component. |
| detachBehaviors() | Detaches all behaviors from the component. |
| ensureBehaviors() | Makes sure that the behaviors declared in behaviors() are attached to this component. |
| 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. |
| getParentMatrixField() | Returns the parent Matrix field, if any. |
| 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. |
deleteBlockType()
Deletes a block type.
Arguments
$blockType(craft\models\MatrixBlockType) – The block type.
Returns
boolean – Whether the block type was deleted successfully.
Throws
- Throwable
if reasons
Signature
public boolean deleteBlockType ( craft\models\MatrixBlockType $blockType )
deleteMatrixField()
Deletes a Matrix field.
Arguments
$matrixField(craft\fields\Matrix) – The Matrix field.
Returns
boolean – Whether the field was deleted successfully.
Throws
Signature
public boolean deleteMatrixField ( craft\fields\Matrix $matrixField )
getBlockById()
Returns a block by its ID.
Arguments
Returns
craft\elements\MatrixBlock, null – The Matrix block, or null if it didn’t exist.
Signature
public craft\elements\MatrixBlock, null getBlockById ( \craft\services\int $blockId, \craft\services\int $siteId = null )
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.
Signature
public craft\models\MatrixBlockType, null getBlockTypeById ( \craft\services\int $blockTypeId )
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.
Signature
public craft\models\MatrixBlockType[] getBlockTypesByFieldId ( \craft\services\int $fieldId )
getContentTableName()
Returns the content table name for a given Matrix field.
Arguments
$matrixField(craft\fields\Matrix) – The Matrix field.$useOldHandle(boolean) – Whether the method should use the field’s old handle when determining the table name (e.g. to get the existing table name, rather than the new one).
Returns
Signature
public string, false getContentTableName ( craft\fields\Matrix $matrixField, \craft\services\bool $useOldHandle = false )
getParentMatrixField()
Returns the parent Matrix field, if any.
Arguments
$matrixField(craft\fields\Matrix) – The Matrix field.
Returns
craft\fields\Matrix, null – The Matrix field’s parent Matrix field, or null if there is none.
Signature
public craft\fields\Matrix, null getParentMatrixField ( craft\fields\Matrix $matrixField )
saveBlockType()
Saves a block type.
Arguments
$blockType(craft\models\MatrixBlockType) – The block type to be saved.$validate(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
Signature
public boolean saveBlockType ( craft\models\MatrixBlockType $blockType, \craft\services\bool $validate = true )
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
Signature
public void saveField ( craft\fields\Matrix $field, craft\base\ElementInterface $owner )
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
Signature
public boolean saveSettings ( craft\fields\Matrix $matrixField, \craft\services\bool $validate = true )
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.
Signature
public boolean validateBlockType ( craft\models\MatrixBlockType $blockType, \craft\services\bool $validateUniques = true )
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.
Signature
public boolean validateFieldSettings ( craft\fields\Matrix $matrixField )