Entities and schema

Note

此页面的内容需要进行重大更新。旧页面包含过时且可能不准确的信息。您仍然可以通过 Mautic Developer Documentation archived repository 访问它。

如果您有兴趣帮助开发此页面和其他新内容的，请考虑加入文档编写工作。

请阅读 Contributing Guidelines 和 Contributing to Mautic’s documentation 以开始贡献。

Mautic 使用 Doctrine ORM 定义模式。插件使用存储在其 Entity 目录中的实体类来定义其模式。通过 Doctrine 的 PHP static function mapping 或 annotations 定义实体的模式。

Warning

您可以使用 PHP 静态函数映射或注解。您不能同时使用两者。

Entity PHP 静态函数映射

您可以使用 Doctrine 的 Doctrine\ORM\Mapping\Builder\ClassMetadataBuilder 类来构建模式。请参阅 Doctrine ORM PHP mapping 以获取可用方法。Mautic 还通过 Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder 提供了一个装饰后的 ClassMetadataBuilder 类，如下所示。

class Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder

addBigIntIdField([string $fieldName = 'id', string $columnName = 'id', bool $isPrimary = true, boolean $isNullable = false])

添加自动生成的 BIGINT UNSIGNED 类型 ID 字段。

Parameters:

$fieldName (string) – ORM 字段的名称。
$columnName (string) – 在数据库表中创建的列的名称。
$isPrimary (boolean) – 如果要将此字段配置为主键，则设置为 TRUE。
$isNullable (bool) – 如果允许 NULL 值，则设置为 TRUE。

Returns:

$this

Return type:

\Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder

addCategory()

与 MauticCategoryBundleEntityCategory 创建一个多对一关系。定义一个名为 category 的 ORM 属性，该属性映射到表中的 category_id 列，并具有指向 categories.id 的外键。

Returns:: $this
Return type:: \Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder

addContact([bool $nullable = false, string $onDelete = 'CASCADE', bool $isPrimaryKey = false, ?string $inversedBy = null): 与 MauticLeadBundleEntityLead 创建一个多对一关系。定义一个名为 contact 的 ORM 属性，该属性映射到表中的 contact_id 列，并具有指向 leads.id 的外键。

param bool $nullable:

TRUE 以允许 NULL 值。

param string $onDelete:: 外部键引用选项，例如 CASCADE 或 SET NULL。
param bool $isPrimaryKey:: 如果要将此字段配置为主表的主键，则设置为 TRUE。
param string|null $inversedBy:: 与 MauticLeadBundleEntityLead 实体相关的属性。仅由 Core 使用。
returns:: $this
returntype:: \Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder

Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder::addDateAdded([bool $nullable = false])

创建一个可变的日期/时间字段。定义一个映射到表上 date_added 列的 dateAdded ORM 属性。

Parameters:

$nullable (bool) – TRUE 以允许 NULL 值。

Returns:

$this

Return type:

\Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder

Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder::addField(string $name, string $type[, array $mapping = []])

装饰 DoctrineORMMappingBuilderClassMetadataBuilder::addField，该方法设置字符串类型或索引字段的最大长度为 191 个字符，以兼容 UTF8MB4 编码。

Parameters:

$name (string) – ORM 字段的名称。
$type (string) – Doctrine 字段类型。请参阅 Doctrine\DBAL\Types\Types。
$mapping (array) – 自定义字段定义。

Returns:

$this

Return type:

\Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder

Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder::addId()

Returns:: $this
Return type:: \Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder

Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder::addIdColumns([string $nameColumn = 'name', string $descriptionColumn = 'description'])

创建 id、name 和 description ORM 字段。id 是一个自动递增的无符号整数，并设置为主键。name 创建为 varchar(191)，description 创建为 longtext。可以通过可选参数自定义 name 和 description 的 ORM 名称。

Parameters:

$nameColumn (string) – 自定义 name 字段的名称。
$descriptionColumn (string) – 自定义 description 字段的名称。

Returns:

$this

Return type:

\Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder

Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder::addIpAddress([bool $nullable = false])

创建一个与 MauticCoreBundleEntityIpAddress 的一对多关系。定义一个映射到表上 ip_id 列的 ipAddress ORM 属性，并具有指向 ip_addresses.id 的外部键。

Parameters:

$nullable (bool) – TRUE 以允许 NULL 值。

Returns:

$this

Return type:

\Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder

Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder::addNamedField(string $name, string $type, string $columnName[, $nullable = false]): 创建一个具有自定义列名称的字段。

param string $name:

ORM字段的名称。

param string $type:: Doctrine字段类型。参见``DoctrineDBALTypesTypes``.
param string $columnName:: 表列的名称。
param bool $nullable:: 如果设置为“TRUE”，则允许“NULL”值。
returns:: $this
returntype:: \Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder

Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder::addNullableField(string $name[, string $type = Types::STRING, ?string $columnName = null])

创建一个允许“NULL”值的字段。

Parameters:

$name (string) – ORM字段的名称。
$type (string) – Doctrine字段类型。参见``DoctrineDBALTypesTypes``.
$columnName (string) – 表列的名称。

Returns:

$this

Return type:

\Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder

Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder::addPublishDates()

创建可变的“publishUp”和“publishDown”日期/时间字段，分别命名为“publish_up”和“publish_down”，并且允许NULL值。

Returns:: $this
Return type:: \Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder

Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder::addUuid()

创建一个名为“id”的GUID字段，并将其设置为主键。您应该在实体的“__construct”方法中生成一个UUID，或者在创建新实体时传递一个UUID。可以使用“$this->id = RamseyUuidUuid::uuid4()->toString();”。

Returns:: $this
Return type:: \Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder

Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder::createField(string $name, string $type)

实例化并返回一个“DoctrineORMMappingBuilderFieldBuilder”对象。“length”属性如果字段是字符串类型或索引，则会被设置。

Returns:: \Doctrine\ORM\Mapping\Builder\FieldBuilder

Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder::createManyToMany(string $name, string $targetEntity)

创建一个指向目标实体的多对多字段。实例化并返回一个“MauticCoreBundleDoctrineMappingManyToManyAssociationBuilder”对象，该对象装饰了“DoctrineORMMappingBuilderManyToManyAssociationBuilder”，并支持“orphanRemoval()”。

Parameters:

$name (string) – ORM字段的名称。
$targetEntity (string) – 目标实体的完全限定类名。

Returns:

\Mautic\CoreBundle\Doctrine\Mapping\ManyToManyAssociationBuilder

Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder::createManyToOne(string $name, string $targetEntity)

创建一个指向目标实体的一对多关系字段。实例化并返回一个“MauticCoreBundleDoctrineMappingAssociationBuilder”对象，该对象装饰了“DoctrineORMMappingBuilderAssociationBuilder”，并支持“orphanRemoval()”和“isPrimaryKey()”。

Parameters:

$name (string) – ORM字段的名称。
$targetEntity (string) – 目标实体的完全限定类名。

Returns:

\Mautic\CoreBundle\Doctrine\Mapping\AssociationBuilder

Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder::createOneToMany(string $name, string $targetEntity)

创建与目标实体之间的一对多关系字段。实例化并返回一个 Mautic\CoreBundle\Doctrine\Mapping\OneToManyAssociationBuilder 对象，该对象通过 orphanRemoval() 支持来装饰 Doctrine\ORM\Mapping\Builder\OneToManyAssociationBuilder。

param string $name:

ORM 字段的名称。

param string $targetEntity:

目标实体的完全限定类名。

returns:

\Mautic\CoreBundle\Doctrine\Mapping\OneToManyAssociationBuilder

Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder::createOneToOne(string $name, string $targetEntity)

创建与目标实体之间的一对一关系字段。实例化并返回一个 Mautic\CoreBundle\Doctrine\Mapping\AssociationBuilder 对象，该对象通过 orphanRemoval() 和 isPrimaryKey() 支持来装饰 Doctrine\ORM\Mapping\Builder\AssociationBuilder。

Parameters:

$name (string) – ORM 字段的名称。
$targetEntity (string) – 目标实体的完全限定类名。

Returns:

\Mautic\CoreBundle\Doctrine\Mapping\AssociationBuilder

Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder::isIndexedVarchar(string $name, string $type)

检查该字段是否应配置最大长度为 191，以兼容 UTF8MB4 编码的字段。

Returns:: 如果该字段是 string 类型或已索引，则返回 TRUE。
Return type:: bool

Entity annotations

您可以选择使用注释而不是 PHP 静态方法。请参阅 Doctrine 关于可用注释的文档。

<?php

declare(strict_types=1);

namespace Mautic\UserBundle\Entity;

use Doctrine\ORM\Mapping as ORM;
use Ramsey\Uuid\Uuid;

/**
 * @ORM\Table (name="worlds")
 */
class World
{
    /**
     * @ORM\Column(type="guid")
     * @ORM\Id
     */
    private $id;

    /**
     * @ORM\Column(type="string", length=191)
     */
    private $name;

    public function __construct()
    {
        $this->id = Uuid::uuid4()->toString();
    }

    public function getId(): string
    {
        return $this->id;
    }

    public function getName(): string
    {
        return $this->name;
    }

    public function setName(string $name): void
    {
        $this->name = $name;
    }
}

Plugin schema migrations

Mautic Core 使用 Doctrine 迁移来管理模式更改。插件无法访问此功能，因为迁移文件位于 Core 的 migrations 目录中。

Mautic provides a way for Plugins to manage their schema changes through the Integration bundle’s \Mautic\IntegrationsBundle\Migration\Engine. Mautic automatically handles migrations if the Plugin’s bundle class extends Mautic\IntegrationsBundle\Bundle\AbstractPluginBundle.

<?php

declare(strict_types=1);

namespace MauticPlugin\HelloWorldBundle;

use Mautic\IntegrationsBundle\Bundle\AbstractPluginBundle;

class HelloWorldBundle extends AbstractPluginBundle
{
}

Define migrations in the Plugin’s Migrations directory. The file and class names can be anything but it’s recommended to match the version of the Plugin that introduces the change. For example, Version_1_0_1.php. Extend each migration class with \Mautic\IntegrationsBundle\Migration\AbstractMigration.

Warning

Mautic executes every migration file when it upgrades the Plugin. Therefore, you must define the isApplicable() method to let Mautic know to execute the migration’s SQL queries. Otherwise, Doctrine throws an exception if MySQL returns an error such as when an index or column already exists.

<?php

declare(strict_types=1);

namespace MauticPlugin\HelloWorldBundle\Migrations;

use Doctrine\DBAL\Schema\Schema;
use Doctrine\DBAL\Schema\SchemaException;
use Mautic\IntegrationsBundle\Migration\AbstractMigration;

class Version_1_0_1 extends AbstractMigration
{
    private $table = 'hello_world';

    protected function isApplicable(Schema $schema): bool
    {
        try {
            return !$schema->getTable($this->concatPrefix($this->table))->hasColumn('is_enabled');
        } catch (SchemaException $e) {
            return false;
        }
    }

    protected function up(): void
    {
        $this->addSql("ALTER TABLE `{$this->concatPrefix($this->table)}` ADD `is_enabled` tinyint(1) 0");

        $this->addSql("CREATE INDEX {$this->concatPrefix('is_enabled')} ON {$this->concatPrefix($this->table)}(is_enabled);");
    }
}

class Mautic\IntegrationsBundle\Migration\AbstractMigration

protected property tablePrefix: Mautic’s configured database table prefix.

protected abstract isApplicable(Schema $schema)

Parameters:

$schema (Doctrine\DBAL\Schema\Schema) – Use the Schema object to evaluate Mautic’s current schema.

Returns:

Return FALSE to skip this migration. Otherwise, TRUE.

Return type:

bool

protected abstract up()

Define the SQL queries through addSql.

Return type:: void

protected addSql(string $sql)

Parameters:

$sql (string) – SQL query to execute. Prefix table and index names with tablePrefix or use concatPrefix.

Return type:

void

protected Mautic\IntegrationsBundle\Migration\AbstractMigration::columnsToString(array $columns)

param array $columns:

列名的数组。

return:

返回一个由数组中的值组成的逗号分隔的字符串列表。例如，$this->columnsToString(['a', 'b', 'c']) 将返回 'a,b,c'.

returntype:

string

protected Mautic\IntegrationsBundle\Migration\AbstractMigration::concatPrefix(string $name)

为给定的名称添加配置的表前缀。

Parameters:

$name (string) – 要添加前缀的列或索引的名称。

Returns:

添加了前缀的名称。

Return type:

string

protected Mautic\IntegrationsBundle\Migration\AbstractMigration::generateAlterTableForeignKeyStatement(string $table, array $columns, string $referenceTable, array $referenceColumns[, string $suffix = ''])

生成完整的 SQL 语句，用于向表中添加新的外键。

Parameters:

$table (string) – 当前表的名称，不包含表前缀。
$columns (array) – 当前表的列数组。
$referenceTable (string) – 被引用的表的名称，不包含表前缀。
$referenceColumns (array) – 被引用的表的列数组。
$suffix (string) – 要附加到查询的字符串，例如 ON DELETE CASCADE。

Returns:

用于添加新外键的 SQL 语句。

Return type:

string

protected Mautic\IntegrationsBundle\Migration\AbstractMigration::generateIndexStatement(string $table, array $columns)

生成一个 INDEX 语句，该语句将在 CREATE TABLE 或 ALTER TABLE 语句中使用，以创建索引。

Parameters:

$table (string) – 要添加索引的表的名称。
$columns (array) – 要包含在索引中的列数组。

Returns:

INDEX {tableName} ($columns…) 语句

Return type:

string