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.
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.
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:
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ć:
- Utworzyć nowy plik upgrade w folderze sql w formacie:
upgrade-{stara wersja}-{nowa wersja}.php - Zmienić odpowiednio wersję modułu w
config.xml - 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:
Efekt zgodny z oczekiwanym ?
Każdy kolejny plik upgrade tworzymy analogicznie do powyższego.