Файлы SQL и скрипт установки

До сих пор таблицу #__hello_posts мы создавали вручную. У пользователя расширения такой возможности нет: всё должно произойти само при установке. Для этого в манифесте указывают файлы SQL, а для действий сложнее запросов — скрипт установки на PHP.

Файлы

Создайте вручную папку sql в административной части и файл script.php:

administrator/components/com_hello/
├── hello.xml
├── script.php                           скрипт установки
├── sql/
│   ├── install.mysql.utf8.sql           выполняется при установке
│   ├── uninstall.mysql.utf8.sql         выполняется при удалении
│   └── updates/
│       └── mysql/
│           ├── 1.0.0.sql                по файлу на версию
│           └── 1.1.0.sql
└── ...

Установка таблицы

-- administrator/components/com_hello/sql/install.mysql.utf8.sql
CREATE TABLE IF NOT EXISTS `#__hello_posts` (
    `id` INT UNSIGNED NOT NULL AUTO_INCREMENT,
    `title` VARCHAR(255) NOT NULL,
    `body` TEXT NOT NULL,
    `published` TINYINT NOT NULL DEFAULT 1,
    `created` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Файл подключают в манифесте, а папку sql добавляют к файлам административной части:

<!-- administrator/components/com_hello/hello.xml -->
<install>
    <sql>
        <file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
    </sql>
</install>

Теперь при установке компонента на чистом сайте таблица создаётся сама. Приставку #__ Joomla заменяет настоящей.

Удаление

-- administrator/components/com_hello/sql/uninstall.mysql.utf8.sql
DROP TABLE IF EXISTS `#__hello_posts`;

<uninstall>
    <sql>
        <file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
    </sql>
</uninstall>

Когда администратор удаляет компонент, таблица удаляется вместе с ним.

Обновление структуры

В версии 1.1.0 записи понадобился столбец category_id. На сайтах, где компонент уже стоит, файл установки повторно не выполняется. Изменения кладут в отдельный файл, названный номером версии:

-- administrator/components/com_hello/sql/updates/mysql/1.1.0.sql
ALTER TABLE `#__hello_posts` ADD COLUMN `category_id` INT UNSIGNED NOT NULL DEFAULT 0;

<update>
    <schemas>
        <schemapath type="mysql">sql/updates/mysql</schemapath>
    </schemas>
</update>

Joomla запоминает номер последнего выполненного файла и при обновлении выполняет все файлы с бо́льшими номерами. Чтобы отсчёт начался с первой версии, в папку кладут и файл 1.0.0.sql — он может быть пустым. Тот же столбец не забудьте добавить в install.mysql.utf8.sql: новые установки файлы обновлений не выполняют.

Скрипт установки

Скрипт — класс с методами, которые Joomla вызывает в разные моменты установки. Его подключают одной строкой манифеста:

<scriptfile>script.php</scriptfile>

// administrator/components/com_hello/script.php
defined('_JEXEC') or die;
 
use Joomla\CMS\Factory;
use Joomla\CMS\Installer\InstallerAdapter;
 
class Com_HelloInstallerScript
{
    public function preflight(string $type, InstallerAdapter $adapter): bool
    {
        if (version_compare(PHP_VERSION, '8.1.0', '<')) {
            Factory::getApplication()->enqueueMessage('Нужен PHP 8.1 или новее', 'error');
 
            return false;
        }
 
        return true;
    }
 
    public function postflight(string $type, InstallerAdapter $adapter): void
    {
        if ($type === 'install' || $type === 'discover_install') {
            Factory::getApplication()->enqueueMessage('Компонент Hello установлен. Откройте «Компоненты → Hello».');
        }
    }
}

Имя класса — имя расширения с заглавной буквы и окончанием InstallerScript: для модуля это Mod_HelloInstallerScript. После установки администратор увидит сообщение из postflight().

Методы скрипта

Метод	Когда вызывается
`preflight($type, $adapter)`	До установки или обновления; `false` отменяет её
`install($adapter)`	При первой установке
`update($adapter)`	При обновлении
`uninstall($adapter)`	При удалении
`postflight($type, $adapter)`	После установки или обновления

Аргумент $type — строка install, update, discover_install или uninstall.

Как проверить

Удалите компонент в разделе «Система → Управление → Расширения» — исчезнут его папки и таблица, поэтому сначала сохраните копию файлов. Верните папки на место и установите компонент через «Поиск»: таблица создана заново, а вверху показано сообщение скрипта.

Частая ошибка

Уже выпущенный файл обновления правят задним числом. На сайтах, где он выполнен, Joomla не запустит его снова, и структура таблиц у пользователей разойдётся. Для каждого изменения создавайте новый файл с новым номером версии.

Спасибо, что читаете!