Entities and schema
###################

Mautic uses :xref:`Doctrine ORM` to define the schema. Plugins define their schema using entity classes stored in its ``Entity`` directory. Define the schema for the entity through Doctrine's :xref:`PHP static function mapping<Doctrine ORM PHP mapping>` or :xref:`annotations<Doctrine ORM annotations>`.

.. warning:: You use the PHP mapping **or** annotations. You can't use a mix of the two.

Entity PHP static function mapping
**********************************

You can build the schema through Doctrine's ``Doctrine\ORM\Mapping\Builder\ClassMetadataBuilder`` class. Refer to :xref:`Doctrine ORM PHP mapping` for methods available. Mautic also provides a decorated ``ClassMetadataBuilder`` class through ``Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder`` described below.

.. The link to this file is defined in docs/code_samples/helloworld_entity_world.py 
.. literalinclude:: ../code_samples_downloaded/Entity_World.php
    :language: php

.. php:class:: Mautic\CoreBundle\Doctrine\Mapping\ClassMetadataBuilder

.. php:method:: addBigIntIdField([string $fieldName = 'id', string $columnName = 'id', bool $isPrimary = true, boolean $isNullable = false])

    Adds autogenerated ID field type of BIGINT UNSIGNED

    :param string $fieldName: Name of the ORM field.
    :param string $columnName: Name of the column created in the database table.
    :param boolean $isPrimary: ``TRUE`` to configure this field as a primary key for the table.
    :param bool $isNullable: ``TRUE`` to allow ``NULL`` values.

    :returns: ``$this``
    :returntype: \\Mautic\\CoreBundle\\Doctrine\\Mapping\\ClassMetadataBuilder

.. php:method:: addCategory()

    Creates a many to one relationship with `Mautic\CategoryBundle\Entity\Category`. Defines a ``category`` ORM property mapped to a ``category_id`` column on the table with a foreign key to ``categories.id``.

    :returns: ``$this``
    :returntype: \\Mautic\\CoreBundle\\Doctrine\\Mapping\\ClassMetadataBuilder

.. php:method:: addContact([bool $nullable = false, string $onDelete = 'CASCADE', bool $isPrimaryKey = false, ?string $inversedBy = null)

    Creates a many to one relationship with `Mautic\LeadBundle\Entity\Lead`. Defines a ``contact`` ORM property mapped to a ``contact_id`` column on the table with a foreign key to ``leads.id``.

    :param bool $nullable: ``TRUE`` to allow ``NULL`` values.
    :param string $onDelete: Foreign key reference option such as ``CASCADE`` or ``SET NULL``.
    :param bool $isPrimaryKey: ``TRUE`` to configure this field as a primary key for the table.
    :param string|null $inversedBy: Property on the ``Mautic\LeadBundle\Entity\Lead`` entity this relates to. This is only used by Core.

    :returns: ``$this``
    :returntype: \\Mautic\\CoreBundle\\Doctrine\\Mapping\\ClassMetadataBuilder

.. php:method:: addDateAdded([bool $nullable = false])

    Creates a mutable date/time field. Defines a ``dateAdded`` ORM property mapped to a ``date_added`` column on the table.

    :param bool $nullable: ``TRUE`` to allow ``NULL`` values.

    :returns: ``$this``
    :returntype: \\Mautic\\CoreBundle\\Doctrine\\Mapping\\ClassMetadataBuilder

.. php:method:: addField(string $name, string $type[, array $mapping = []])

    Decorates ``Doctrine\ORM\Mapping\Builder\ClassMetadataBuilder::addField`` that sets the max length to 191 characters for string typed or indexed fields for compatibility with UTF8MB4 encoding.

    :param string $name: Name of the ORM field.
    :param string $type: Doctrine field type. See ``Doctrine\DBAL\Types\Types``.
    :param array $mapping: Custom field definitions.

    :returns: ``$this``
    :returntype: \\Mautic\\CoreBundle\\Doctrine\\Mapping\\ClassMetadataBuilder

.. php:method:: addId()

    :returns: ``$this``
    :returntype: \\Mautic\\CoreBundle\\Doctrine\\Mapping\\ClassMetadataBuilder

.. php:method:: addIdColumns([string $nameColumn = 'name', string $descriptionColumn = 'description'])

    Creates ``id``, ``name``, and ``description`` ORM fields. ``id`` is an auto-incremented unsigned integer set as a primary key. ``name`` is created as  ``varchar(191)`` and ``description`` as ``longtext``. Customize the ORM names for ``name`` and ``description`` through the optional parameters.

    :param string $nameColumn: Customize the name for the ``name`` field.
    :param string $descriptionColumn: Customize the name for the ``description`` field.

    :returns: ``$this``
    :returntype: \\Mautic\\CoreBundle\\Doctrine\\Mapping\\ClassMetadataBuilder

.. php:method:: addIpAddress([bool $nullable = false])

    Creates a many to one relationship with `Mautic\CoreBundle\Entity\IpAddress`. Defines a ``ipAddress`` ORM property mapped to a ``ip_id`` column on the table with a foreign key to ``ip_addresses.id``.

    :param bool $nullable: ``TRUE`` to allow ``NULL`` values.

    :returns: ``$this``
    :returntype: \\Mautic\\CoreBundle\\Doctrine\\Mapping\\ClassMetadataBuilder

.. php:method:: addNamedField(string $name, string $type, string $columnName[, $nullable = false])

    Creates a field with a custom column name.

    :param string $name: Name of the ORM field.
    :param string $type: Doctrine field type. See ``Doctrine\DBAL\Types\Types``.
    :param string $columnName: Name of the table's column name.
    :param bool $nullable: ``TRUE`` to allow ``NULL`` values.

    :returns: ``$this``
    :returntype: \\Mautic\\CoreBundle\\Doctrine\\Mapping\\ClassMetadataBuilder

.. php:method:: addNullableField(string $name[, string $type = Types::STRING, ?string $columnName = null])

    Creates a field that allows a ``NULL`` value.

    :param string $name: Name of the ORM field.
    :param string $type: Doctrine field type. See ``Doctrine\DBAL\Types\Types``.
    :param string $columnName: Name of the table's column name.

    :returns: ``$this``
    :returntype: \\Mautic\\CoreBundle\\Doctrine\\Mapping\\ClassMetadataBuilder

.. php:method:: addPublishDates()

    Creates ``publishUp`` and ``publishDown`` nullable mutable date/time fields as  ``publish_up`` and ``publish_down`` respectively.

    :returns: ``$this``
    :returntype: \\Mautic\\CoreBundle\\Doctrine\\Mapping\\ClassMetadataBuilder

.. php:method:: addUuid()

    Creates a ``id`` GUID field as a primary key. You should generate a UUID in the entity's ``__construct`` or pass one into the ``__construct`` when creating a new entity. You can use ``$this->id = Ramsey\Uuid\Uuid::uuid4()->toString();``.

    :returns: ``$this``
    :returntype: \\Mautic\\CoreBundle\\Doctrine\\Mapping\\ClassMetadataBuilder

.. php:method:: createField(string $name, string $type)

    Instantiates and returns a ``Doctrine\ORM\Mapping\Builder\FieldBuilder`` object. ``length`` is set if the field is a string type or indexed.

    :returns: \\Doctrine\\ORM\\Mapping\\Builder\\FieldBuilder

.. php:method:: createManyToMany(string $name, string $targetEntity)

    Creates a many to many field to the targeted entity. Instantiates and returns a ``Mautic\CoreBundle\Doctrine\Mapping\ManyToManyAssociationBuilder`` object that decorates ``Doctrine\ORM\Mapping\Builder\ManyToManyAssociationBuilder`` with ``orphanRemoval()`` support.

    :param string $name: Name of the ORM field.
    :param string $targetEntity: Fully qualified classname for the targeted entity.

    :returns: \\Mautic\\CoreBundle\\Doctrine\\Mapping\\ManyToManyAssociationBuilder

.. php:method:: createManyToOne(string $name, string $targetEntity)

    Creates a field with a many to one relationship to the targeted entity. Instantiates and returns a ``Mautic\CoreBundle\Doctrine\Mapping\AssociationBuilder`` object that decorates ``Doctrine\ORM\Mapping\Builder\AssociationBuilder`` with ``orphanRemoval()`` and ``isPrimaryKey()`` support.

    :param string $name: Name of the ORM field.
    :param string $targetEntity: Fully qualified classname for the targeted entity.

    :returns: \\Mautic\\CoreBundle\\Doctrine\\Mapping\\AssociationBuilder

.. php:method:: createOneToMany(string $name, string $targetEntity)

    Creates a field with a one to many relationship to the targeted entity. Instantiates and returns a ``Mautic\CoreBundle\Doctrine\Mapping\OneToManyAssociationBuilder`` object that decorates ``Doctrine\ORM\Mapping\Builder\OneToManyAssociationBuilder`` with ``orphanRemoval()`` support.

    :param string $name: Name of the ORM field.
    :param string $targetEntity: Fully qualified classname for the targeted entity.

    :returns: \\Mautic\\CoreBundle\\Doctrine\\Mapping\\OneToManyAssociationBuilder

.. php:method:: createOneToOne(string $name, string $targetEntity)

    Creates a field with a one to one relationship to the targeted entity. Instantiates and returns a ``Mautic\CoreBundle\Doctrine\Mapping\AssociationBuilder`` object that decorates ``Doctrine\ORM\Mapping\Builder\AssociationBuilder`` with ``orphanRemoval()`` and ``isPrimaryKey()`` support.

    :param string $name: Name of the ORM field.
    :param string $targetEntity: Fully qualified classname for the targeted entity.

    :returns: \\Mautic\\CoreBundle\\Doctrine\\Mapping\\AssociationBuilder

.. php:method:: isIndexedVarchar(string $name, string $type)

    Checks whether the field should have a max length of 191 configured for compatibility with UTF8MB4 encoded fields.

    :returns: Returns ``TRUE`` if the field is a ``string`` type or is indexed.
    :returntype: bool

Entity annotations
******************

You can choose to use annotations instead of the PHP static method. Refer to :xref:`Doctrine's documentation on available annotations<Doctrine ORM annotations>`.

.. code-block:: php

    <?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 uses :xref:`Doctrine migrations<Doctrine migrations bundle>` to manage schema changes. Plugins don't have access to this as migration files are in Core's ``migrations`` directory.

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 :ref:`Plugin's bundle class<plugins/structure:File and directory structure>` extends ``Mautic\IntegrationsBundle\Bundle\AbstractPluginBundle``.

.. code-block:: php

    <?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.

.. code-block:: php

    <?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);");
        }
    }


.. php:class:: Mautic\IntegrationsBundle\Migration\AbstractMigration

.. php:attr:: protected tablePrefix

    Mautic's configured database table prefix.

.. php:method:: protected abstract isApplicable(Schema $schema)

    :param Doctrine\\DBAL\\Schema\\Schema $schema: Use the ``Schema`` object to evaluate Mautic's current schema.

    :returns: Return ``FALSE`` to skip this migration. Otherwise, ``TRUE``.
    :returntype: bool

.. php:method:: protected abstract up()

    Define the SQL queries through :php:meth:`addSql`.

    :returntype: void

.. php:method:: protected addSql(string $sql)

    :param string $sql: SQL query to execute. Prefix table and index names with :php:attr:`tablePrefix` or use :php:meth:`concatPrefix`.

    :returntype: void

.. php:method:: protected columnsToString(array $columns)

    :param array $columns: Array of column names.

    :return: Returns a comma separated value list from the values given in the array. For example, ``$this->columnsToString(['a', 'b', 'c'])`` will return ``'a,b,c'``.
    :returntype: string

.. php:method:: protected concatPrefix(string $name)

    Prefixes the given name with the configured table prefix.

    :param string $name: Name of column or index to prefix.

    :return: Prefixed name.
    :returntype: string

.. php:method:: protected generateAlterTableForeignKeyStatement(string $table, array $columns, string $referenceTable, array $referenceColumns[, string $suffix = ''])

    Generates full SQL statement to add a new foreign key to a table.

    :param string $table: Name of the current table without the table prefix.
    :param array $columns: Array of columns for the current table.
    :param string $referenceTable: Name of the referenced table without the table prefix.
    :param array $referenceColumns: Array of columns for the referenced table.
    :param string $suffix: String to append to the query such as ``ON DELETE CASCADE``.

    :return: SQL statement for adding a new foreign key.
    :returntype: string

.. php:method:: protected generateIndexStatement(string $table, array $columns)

    Generates an ``INDEX`` statement to be used within a ``CREATE TABLE`` or ``ALTER TABLE`` statement to create an index.

    :param string $table: Name of the table where the index will be added.
    :param array $columns: Array of columns to included in the index.

    :return: ``INDEX {tableName} ($columns...)`` statement
    :returntype: string