Настройка базы данных для работы компонента на Joomla 4

Эта статья является частью учебника "Разработка компонента MVC для Joomla 4.x". Он предназначен для руководства по программированию, поэтому, если вы не читали предыдущие части руководства, вам рекомендуется сделать это. Ранее было рассмотрено добавление переменной запроса в ссылку меню, которое в свою очередь служит продолжением добавления типа меню для фронтенда на Joomla 4.

• Настройка базы данных для работы компонента на Joomla 4.x
• Необходимые изменения в коде файлов компонента Joomla 4
• Содержимое файлов компонента для Joomla 4.x
  • admin/sql/install.mysql.utf8.sql
  • admin/sql/uninstall.mysql.utf8.sql
  • admin/sql/mysql/0.0.7.sql
  • helloworld.xml
• Тестирование установки базы данных компонента Joomla 4

Настройка базы данных для работы компонента на Joomla 4.x

Наконец то мы, добрались до стадии разработки, на которой требуется создать таблицы базы данных, которые наш компонент будет использовать для хранения и извлечения данных. В зависимости от его назначения вашему расширению могут не потребоваться таблицы базы данных для работы, но, учитывая уровень сложности расширений компонентов Joomla 4, это маловероятно.

Установка, удаление и обновление версий в компоненте Joomla 4 выполняются с помощью сценариев SQL, размещенных в папке admin/sql компонента. Сценарий SQL соответствует определенному ядру базы данных, например install.mysql.utf8.sql будет выполняться только в том случае, если Joomla работает в базе данных MySQL. На момент написания статьи, Joomla 4 поддерживает MySQL и PostgreSQL, и мы рекомендуем писать сценарии SQL для обоих типов баз данных для максимальной совместимости. Однако для целей этого урока мы сосредоточимся на сценариях, основанных на MySQL.

Давайте продолжим и напишем сценарии SQL, которые понадобятся для создания таблицы базы данных для хранения настраиваемых сообщений для нашего компонента. В последующих разделах руководства мы создадим панель управления для управления этими сообщениями в админке.

Необходимые изменения в коде файлов компонента Joomla 4

Нам нужно будет создать пару файлов, дополняющих для установку и удаление компонента, в которых будет создаваться и удаляться таблица в базе данных с данными компонента. А также один файл обновления для подключения базы данных к работе компонента только с текущей разрабатываемой версией. Поскольку наш компонент уже установлен, для внесения необходимых изменений и необходим этот файл обновления.

1. Новый файл: admin/sql/install.mysql.utf8.sql
   • Файл SQL, который запускается при установке компонента в базу данных MySQL.
2. Новый файл: admin/sql/uninstall.mysql.utf8.sql
   • Файл SQL, который запускается при удалении компонента в базе данных MySQL.
3. Новый файл: admin/sql/mysql/0.0.7.sql
   • Файл SQL, который запускается при обновлении компонента до/после версии 0.0.7 в базе данных MySQL.
4. Обновления: helloworld.xml
   • Нам нужно будет добавить новый каталог sql в наш список копий файлов и добавить инструкции для Joomla 4 о том, где найти наши скрипты. Это всё должно быть прописано в файле манифеста нашего компонента.

Содержимое файлов компонента для Joomla 4.x

admin/sql/install.mysql.utf8.sql

Этот файл необходимо будет обновлять всякий раз, когда вы вносите изменения в схему базы данных компонента. Он запускается при установке компонента Joomla 4 в систему. Обратите внимание, что при создании таблиц вы должны ставить перед именем префикс #__. Joomla автоматически заменит этот префикс префиксом таблицы базы данных, настроенной в системе. Вы должны убедиться, что имена ваших баз данных используют этот префикс всякий раз, когда вы их создаете или обновляете. Кроме того, мы настоятельно рекомендуем вам префиксировать все имена таблиц, имена ключей и т.д. именем вашего компонента (как показано в примерах этого мануала), чтобы предотвратить вероятность конфликтов между компонентами на сайте, работающем на CMS Joomla 4.

Обратите также внимание, что мы используем проверки IF EXISTS для наших операторов DROP и помещаем операторы DROP перед операторами CREATE. Хотя может показаться, что состояние базы данных предсказуемо - до ее создания не должно быть существующей таблицы с таким именем, - лучше никогда не предполагать, что предыдущая операция установки/удаления завершилась чисто и успешно. В редких случаях, когда такая ошибка возможна, наш код будет продолжать работать, выполнив все необходимые подготовительные операции.

Если бы этот файл был для базы данных PostgreSQL, он назывался бы install.postgresql.utf8.sql.

DROP TABLE IF EXISTS `#__helloworld_greetings`;

CREATE TABLE `#__helloworld_greetings` ( 
    `id` SERIAL NOT NULL, 
    `greeting` VARCHAR(200) NOT NULL, 
    `published` BOOLEAN NOT NULL DEFAULT FALSE, 
    PRIMARY KEY (`id`)
) ENGINE = InnoDB; 

INSERT INTO `#__helloworld_greetings` (`greeting`) VALUES
    ('Hello World!'),
    ('Good bye World!');

admin/sql/uninstall.mysql.utf8.sql

Этот файл должен выполнить все действия, необходимые для удаления собственных данных этого компонента в базе данных сайта на CMS Joomla 4. В нашем случае это в настоящее время очень просто - если таблица helloworld_greetings существует, удалите ее.

Если бы этот файл был для базы данных PostgreSQL, он назывался бы uninstall.postgresql.utf8.sql.

DROP TABLE IF EXISTS `#__helloworld_greetings`;

admin/sql/mysql/0.0.7.sql

При создании новой версии компонента с соответствующими изменениями базы данных эти изменения должны быть внесены в файлы обновления базы данных. Имя файла - это просто номер версии компонента, требующий изменений, и файлы группируются в папки в соответствии с ядром базы данных, на котором они работают. Когда Joomla 4 обновляет компонент, она будет искать любые файлы обновления между ранее установленным номером версии и новым номером версии и запускать их последовательно.

В нашем случае, поскольку до нашей новой версии 0.0.7 у нас не было таблиц базы данных, этот файл идентичен установочному файлу.

Если бы этот файл был для базы данных PostgreSQL, он назывался бы так же, но был бы помещен в папку admin/sql/postgresql.

DROP TABLE IF EXISTS `#__helloworld_greetings`;

CREATE TABLE `#__helloworld_greetings` ( 
    `id` SERIAL NOT NULL, 
    `greeting` VARCHAR(200) NOT NULL, 
    `published` BOOLEAN NOT NULL DEFAULT FALSE, 
    PRIMARY KEY (`id`)
) ENGINE = InnoDB; 

INSERT INTO `#__helloworld_greetings` (`greeting`) VALUES
    ('Hello World!'),
    ('Good bye World!');

helloworld.xml

В нашем обновленном файле манифеста нам нужно указать Joomla 4, чтобы она скопировала нашу новую папку admin/sql при установке/обновлении компонента. Нам также нужно сообщить ему, что у нашего компонента теперь есть файлы базы данных, какие из них нужно запустить для какого действия и где их найти.

Три новых элемента, <install />, <uninstall /> и <update/>, достаточно понятны. Хотя их структура немного отличаются, каждая из них по существу состоит из действия (элемента), типа базы данных (mysql/postgresql) и пути к файлу. Когда вы добавляете поддержку PostgreSQL в свой компонент, вы добавляете дополнительную строку в каждый элемент, чтобы направлять Joomla к нужным файлам.

<?xml version="1.0" encoding="utf-8"?>
<extension type="component" method="upgrade">
<!-- атрибут 'version' для тега расширения больше не используется -->
 
    <name>Hello World</name>
    <!-- Следующие элементы являются необязательными и не содержат ограничений на форматирование -->
    <creationDate>May 2021</creationDate>
    <!-- Фиктивный автор, не стесняйтесь заменять его в любом месте, где вы его видите -->
    <author>John Smith</author>
    <authorUrl>https://mb4.ru</authorUrl>
    <copyright>Пётр Васечкин</copyright>
    <license>GPL v3</license>
    <!-- Строка 'version' записывается в таблицу компонентов -->
    <version>0.0.7</version>
    <!-- Описание является необязательным и по умолчанию используется имя сомпонента -->
    <description>
        A hello world component!
    </description>
 
    <!-- Это пространство имен PHP, в котором организован
    код расширения. Он должен следовать этому формату:
    
    Vendor\Component\ComponentName
 
    "Vendor" может быть названией компании или вашим собственным именем
    
    Раздел "ComponentName" ДОЛЖЕН соответствовать имени, используемому 
    везде для вашего компонента. Каким бы ни было имя этого XML-файла, 
    пространство имен должно совпадать (заглавные/прописные буквы не учитываются). 
    -->
    <namespace path="src/">JohnSmith\Component\HelloWorld</namespace>
 
    <files folder="site/">
        <folder>language</folder>
        <folder>src</folder>
        <folder>tmpl</folder>
    </files>
 
    <languages>
        <language tag="en-GB">site/language/en-GB/en-GB.com_helloworld.ini</language>
    </languages>
            
    <administration>
        <!-- Ссылка, которая появится в меню админки Joomla "Components" -->
        <menu link="index.php?option=com_helloworld">Hello World</menu>
        <!-- Список файлов и папок для копирования.
             Обратите внимание на атрибут "folder".
             Это имя папки в пакете компонентов для копирования в CMS Joomla 4. -->
        <files folder="admin/">
            <folder>language</folder>
            <folder>services</folder>
            <folder>sql</folder>
            <folder>src</folder>
            <folder>tmpl</folder>
        </files>
 
        <languages>
            <language tag="en-GB">admin/language/en-GB/en-GB.com_helloworld.ini</language>
            <language tag="en-GB">admin/language/en-GB/en-GB.com_helloworld.sys.ini</language>
        </languages>
    </administration>

    <install>
        <sql>
            <file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
        </sql>
    </install>
    <uninstall>
        <sql>
            <file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
        </sql>
    </uninstall>
    <update>
        <schemas>
            <schemapath type="mysql">sql/updates/mysql</schemapath>
        </schemas>
    </update>
 
</extension>

Обратите внимание на строки:

• стр.14 — меняется номер версии компонента.
• стр.52 — добавляем ещё одну папку с SQL-скриптами.
• стр.63..77 — добавляем информацию для операций с базой данных.

Тестирование установки базы данных компонента Joomla 4

Как всегда, заархивируйте новую версию компонента и загрузите ее в админ-панель установки Joomla 4. После установки/обновления вы должны увидеть сообщение о том, что установка прошла успешно. На самом деле сейчас ничто не использует созданную в базе данных таблицу, поэтому используйте предпочтительный клиент базы данных для подключения к базе данных Joomla и проверьте, существует ли новая таблица.

Далее мы начнем создавать админскую часть компонента, работающую в панели администратора Joomla 4 для создания и управления нашими записями приветствий.

На этом на 8 мая 2021 года руководство по созданию MVC компонента для Joomla 4 на официальном сайте обрывается. Ждём и верим, что его допишут!

Перевод с английского:
https://docs.joomla.org/J4.x:Developing_an_MVC_Component/Setting_up_the_Database

Заберите ссылку на статью к себе, чтобы потом легко её найти!
Раз уж досюда дочитали, то может может есть желание рассказать об этом месте своим друзьям, знакомым и просто мимо проходящим?
Не надо себя сдерживать! ;)