Contextualizando

Para gerenciar e fazer alterações nos esquemas do banco de dados de forma simplificada, o Magento possui as classes de Install Data e Upgrade Data, que criam scripts para processar o código em SQL e automaticamente inserir dados das atualizações no banco de dados.

Quando utilizar as instalações e atualizações de esquema?

As classes de Install Data e Upgrade Data servem para a alteração, remoção e/ou criação de dados em uma tabela específica do banco de dados. E elas devem ser usadas em versões anteriores a versão 2.3 do Magento 2, mas para versões posteriores é recomendado o uso de classes do tipo Data Patch.

Outro fator que é decisório para utilização das classes Install Data e Upgrade Data é a incompatibilidade dos módulos, caso a tabela tenha sido criada através do arquivo db_schema.xml ou Schema Patch, as alterações de dados devem ser feitas por Data Patch e não por classes do tipo Install Data ou Upgrade Data. Essas classes devem ser usadas para quando as tabelas forem criadas com Install Schema e Upgrade Schema, saiba como criar/atualizar Como criar/atualizar tabelas e dados com DataPatch e SchemaPatch.

Código para a inserir dados em uma tabela

Install Data

Essa classe será executada quando o módulo for instalado e persistirá os dados nas tabelas do banco, ou seja, essa classe pode ser utilizada para inserir, remover e/ou alterar dados no banco de uma tabela específica. As classes Install Data são executadas depois das classes Install Schema.

A classe Install Data deve seguir a estrutura de pastas \{Vendor}\{Module}\Setup\InstallData e deve implementar a interface \Magento\Framework\Setup\InstallDataInterface, que obriga a classe a implementar o método install(\Magento\Framework\Setup\ModuleDataSetupInterface $setup, \Magento\Framework\Setup\ModuleContextInterface $context). A interface ModuleDataSetupInterface gera através de injeção de dependência um objeto de configuração que fornece muitas funções para interagir com o servidor do banco de dados. A interface ModuleContextInterface possui apenas o método getVersion(), que retorna a versão atual do módulo, ou seja, retorna o valor do atributo setup_version do arquivo module.xml.

<?php

namespace Vendor\Module\Setup;

use Magento\Framework\Setup\InstallDataInterface;
use Magento\Framework\Setup\ModuleDataSetupInterface;
use Magento\Framework\Setup\ModuleContextInterface;

class InstallData implements InstallDataInterface
{
    public function install(
        ModuleDataSetupInterface $setup,
        ModuleContextInterface $context
    ): void {
        $setup->startSetup();
        $setup->getConnection()->insert(
            $setup->getTable('{table_name}'),
            [
                '{column_name_1}' => '{value}',
                '{column_name_2}' => 1,
                '{column_name_3}' => {true/false},
                '{column_name_n}' => '0000-00-00'
            ]
        );
        $setup->endSetup();
    }
}

Upgrade Data

Essa classe será executada quando o módulo for atualizado para adicionar/remover os dados para as tabelas do banco de dados.

A classe Upgrade Data deve seguir a estrutura de pastas \{Vendor}\{Module}\Setup\UpgradeData e implementar a interface \Magento\Framework\Setup\UpgradeDataInterface, que obriga a classe a implementar o método upgrade(\Magento\Framework\Setup\ModuleDataSetupInterface $setup, \Magento\Framework\Setup\ModuleContextInterface $context). A interface ModuleDataSetupInterface gera através de injeção de dependência um objeto de configuração que fornece muitas funções para interagir com o servidor do banco de dados. A interface ModuleContextInterface possui apenas o método getVersion(), que retorna a versão atual do módulo, ou seja, retorna o valor do atributo setup_version do arquivo module.xml.

<?php

namespace {Vendor}\{Module}\Setup;

use Magento\Framework\Setup\UpgradeDataInterface;
use Magento\Framework\Setup\ModuleDataSetupInterface;
use Magento\Framework\Setup\ModuleContextInterface;

class UpgradeData implements UpgradeDataInterface
{
    public function upgrade(
        ModuleDataSetupInterface $setup,
        ModuleContextInterface $context
    ): void {
        $setup->startSetup();

        if (version_compare($context->getVersion(), '{version_to_implement}', '<')) {
            $this->upgradeVersion($setup);
        }

        $setup->endSetup();
    }

    private function upgradeVersion(ModuleDataSetupInterface $setup): void
    {
        $setup->getConnection()->insert(
            $setup->getTable('{table_name}'),
            [
                '{column_name_1}' => '{value}',
                '{column_name_2}' => 1,
                '{column_name_3}' => {true/false},
                '{column_name_n}' => '0000-00-00'
            ]
        );
    }
}

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="{Vendor}_{Module}" setup_version="{version_number}" />
</config>

Finalizando

Valores entre chaves ({test}) devem ser alterados na implementação do código.

Habilitando as alterações

Comando para atualizar os dados e o esquema do banco de dados.

php bin/magento setup:upgrade

Diretórios e Arquivos

Segue a a lista de diretórios e arquivos que devem ser criados.

- app/
  - code/
    - {Vendor}/
        - {Module}/
          - etc/
            - module.xml
          - Setup/
            - InstallData.php
            - UpgradeData.php
          - registration.php
          - composer.json