Upgrade i install script modułu Magento

Pisząc własne funkcjonalności/moduły do Magento nie sposób pominąć folder sql, gdzie umieszczamy kod, który zostaje wykonany przy instalacji/upgradzie naszego modułu. W tym wpisie przedstawię w jaki sposób poprawnie stworzyć pliki install oraz upgrade dla modułu. Zanim przejdę do konkretnych przykładów, należy podkreślić, że skrypt należy wcześniej zadeklarować w pliku config.xml. Na potrzeby wpisu tworzę moduł o nazwie Scripts (Xcoding_Scripts) a w nim:

Deklaracja skryptu

app\code\local\Xcoding\Scripts\etc\config.xml

<?xml version="1.0"?>
   <!--
     ~    @category  Xcoding_Scripts
     ~    @package   Xcoding_Scripts
     ~    @author    X-Coding IT Studio (http://www.x-coding.pl/)
     -->
   <config>
       <modules>
           <Xcoding_Scripts>
               <version>1.0.0</version>
           </Xcoding_Scripts>
       </modules>
       <global>
           <blocks>
               <!-- deklaracja bloku -->
               <xcoding_scripts>
                   <class>Xcoding_Scripts_Block</class>
               </xcoding_scripts>
           </blocks>
           <helpers>
               <!-- deklaracja helpera -->
               <xcoding_scripts>
                   <class>Xcoding_Scripts_Helper</class>
               </xcoding_scripts>
           </helpers>
           <models>
               <xcoding_scripts>
                   <class>Xcoding_Scripts_Model</class>
                   <resourceModel>xcoding_scripts_resource</resourceModel>
               </xcoding_scripts>

               <xcoding_scripts_resource>
                   <class>Xcoding_Scripts_Model_Resource</class>
                   <entities>
                       <test_table>
                           <table>scripts_test</table>
                       </test_table>
                       <new_test_table>
                           <table>scripts_test_upgrade</table>
                       </new_test_table>
                   </entities>
               </xcoding_scripts_resource>
           </models>
           <resources>
               <!-- deklaracja skryptu -->
               <xcoding_scripts_setup>
                   <setup>
                       <module>Xcoding_Scripts</module>
                       <class>Mage_CatalogIndex_Model_Resource_Setup</class>
                   </setup>
                   <connection>
                       <use>core_setup</use>
                   </connection>
               </xcoding_scripts_setup>
           </resources>
       </global>
   </config>

Deklarację zamieszczamy w globals > resources gdzie podajemy unikalną nazwę resource – w tym przypadku xcoding_scripts_setup.

<resources>
            <!-- deklaracja skryptu -->
            <xcoding_scripts_setup>
                <setup>
                    <module>Xcoding_Scripts</module>
                </setup>
                <connection>
                    <use>core_setup</use>
                </connection>
            </xcoding_scripts_setup>
        </resources>

To właśnie xcoding_scripts_setup będzie widoczny w tabeli core_resource po instalacji modułu. Nazwa ta również wyznacza nazwę folderu w którym będą się znajdować skrypty.

Struktura plików

Pierwszy skrypt instalacyjny – nowa tabela

Domyślnie klasą reprezentującą installer jest Mage_Core_Model_Resource_Setup, ale jeśli chcemy użyć innej dostępnej lub własnej, wystarczy zadeklarować ją w config.xml w taki sposób:

...
  <resources>
      <!-- deklaracja skryptu -->
      <xcoding_scripts_setup>
          <setup>
              <module>Xcoding_Scripts</module>
              <!-- klasa installera -->
              <class>Mage_ImportExport_Model_Resource_Setup</class>
          </setup>
          ...

Korzystam z domyślnego instalatora, kod skryptu tworzącego tabelę:

app\code\local\Xcoding\Scripts\sql\xcoding_scripts_setup\install-1.0.0.php

<?php
    /**
     *    @category  Xcoding_Scripts
     *    @package   Xcoding_Scripts
     *    @author    X-Coding IT Studio (http://www.x-coding.pl/)
     */

    /** @var Mage_Core_Model_Resource_Setup $this */
    $installer = $this;

    $installer->startSetup();

    $table = $installer->getConnection()
            ->newTable($installer->getTable('xcoding_scripts/test_table'))
            ->addColumn('id', Varien_Db_Ddl_Table::TYPE_INTEGER, null, array(
                            'identity'  => true,
                    'unsigned'  => true,
            'nullable'  => false,
            'primary'   => true,
    ), 'Id')
    ->addColumn('small_text', Varien_Db_Ddl_Table::TYPE_VARCHAR, 30, array(
                    'nullable'  => false,
    ), 'Text field')
    ->addColumn('text', Varien_Db_Ddl_Table::TYPE_TEXT, null, array(
                    'nullable'  => true,
    ), 'Long text')
    ->addColumn('boolean_column', Varien_Db_Ddl_Table::TYPE_BOOLEAN, null, array(
                    'nullable'  => false,
    ), 'Boolean column')
    ->addColumn('created_at', Varien_Db_Ddl_Table::TYPE_TIMESTAMP, null, array(
                    'nullable'  => false
    ), 'Created at');

    $installer->getConnection()->createTable($table);

    $installer->endSetup();

$installer->getTable('xcoding_scripts/test_table') => scripts_test wynikające z entity w config.xml

...
   <xcoding_scripts_resource>
       <class>Xcoding_Scripts_Model_Resource</class>
       <entities>
           <test_table>
               <table>scripts_test</table>
           </test_table>

Odpalamy!

Aby nasz skrypt się wykonał musimy wykonać 2 akcje: aktywować moduł i wyczyścić cache. A więc aktywacja modułu:

app\etc\modules\Xcoding_Scripts.xml

<?xml version="1.0"?>
<!--
  ~    @category  Xcoding_Scripts
  ~    @package   Xcoding_Scripts
  ~    @author    X-Coding IT Studio (http://www.x-coding.pl/)
  -->
<config>
    <modules>
        <Xcoding_Scripts>
            <active>true</active>
            <codePool>local</codePool>
        </Xcoding_Scripts>
    </modules>
</config>

Nowa tabela utworzona

Przy próbie odświeżenia strony aplikacji wykonał się skrypt instalacyjny i zgodnie z oczekiwaniami została utworzona nowa teabla w bazie danych o nazwie scripts_test. Stan naszego modułu (wersja modułu oraz wersja danych) możemy zweryfikować w tabeli core_resource.

Nowy moduł w Magento Moduł jest poprawnie zarejestrowany

Jak widać został dodany nowy rekord z code odpowiadającym nazwą zdeklarowaną w config.xml oraz aktualnym version i data_version. Dla potwierdzenia sprawdźmy utworzoną tabelę w bazie danych:

Efekt działania Wszystko zgodnie z oczekiwaniami

Rozbudowa o kolejne wersje, czyli upgrade script

Tutaj mamy znacznie mniej pracy, ponieważ wszystko jest już przygotowane pod względem konfiguracyjnym. Co należy zrobić:

  1. Utworzyć nowy plik upgrade w folderze sql w formacie: upgrade-{stara wersja}-{nowa wersja}.php
  2. Zmienić odpowiednio wersję modułu w config.xml
  3. Wyczyścić cache

W tym przypadku tworzę plik upgrade-1.0.0-2.0.0 o podobnej zawartości jak skrypt instalacyjny – zmieniając tylko nazwę tabeli którą utworzymy.

<?php
        /**
         *    @category  Xcoding_Scripts
         *    @package   Xcoding_Scripts
         *    @author    X-Coding IT Studio (http://www.x-coding.pl/)
         */

        /**
         *    @category  Xcoding_Scripts
         *    @package   Xcoding_Scripts
         *    @author    X-Coding IT Studio (http://www.x-coding.pl/)
         */

        /** @var Mage_Core_Model_Resource_Setup $this */
        $installer = $this;

$installer->startSetup();

$table = $installer->getConnection()
        ->newTable($installer->getTable('xcoding_scripts/new_test_table'))
        ->addColumn('id', Varien_Db_Ddl_Table::TYPE_INTEGER, null, array(
                        'identity'  => true,
                'unsigned'  => true,
        'nullable'  => false,
        'primary'   => true,
), 'Id')
->addColumn('small_text', Varien_Db_Ddl_Table::TYPE_VARCHAR, 30, array(
                'nullable'  => false,
), 'Text field')
->addColumn('text', Varien_Db_Ddl_Table::TYPE_TEXT, null, array(
                'nullable'  => true,
), 'Long text')
->addColumn('boolean_column', Varien_Db_Ddl_Table::TYPE_BOOLEAN, null, array(
                'nullable'  => false,
), 'Boolean column')
->addColumn('created_at', Varien_Db_Ddl_Table::TYPE_TIMESTAMP, null, array(
                'nullable'  => false
), 'Created at');

$installer->getConnection()->createTable($table);

$installer->endSetup();

Kolejnym krokiem jest zmiana wersji modułu w config.xml na 2.0.0

...
   <config>
       <modules>
           <Xcoding_Scripts>
               <version>2.0.0</version>
           </Xcoding_Scripts>
       </modules>
   ...

Teraz czyścimy cache i gotowe! Wersja modułu została zwiększona a tabela utworzona:

Wynik upgrade

Nowa tabela po upgrade Efekt zgodny z oczekiwanym 🙂

Każdy kolejny plik upgrade tworzymy analogicznie do powyższego.

FacebookTwitterGoogle+LinkedIn