مرحله ۶: اضافه کردن فایل اسکریپت

مقدمه

از این مرحله به بعد به مباحث پیشرفته‌تر می‌پردازیم. 

در این مرحله، یک فایل اسکریپت نصب (installation script) اضافه می‌کنیم. این فایل اسکریپت هنگام نصب یا حذف افزونه اجرا می‌شود و می‌تواند برای انجام عملیات مختلف مرتبط با نصب به کار رود، مثلاً: 

- بررسی حداقل نسخه PHP و جوملای لازم 

- تعریف پیش‌فرض‌های پیکربندی برای افزونه 

کد منبع این مرحله در پوشه mod_hello مرحله ۶ موجود است

( github.com/joomla/manual-examples/tree/main/module-tutorial/step6_script)

فایل اسکریپت نصب

فایل اسکریپت نصب، یک کلاس است که باید ۵ تابع اصلی را پیاده‌سازی کند: 

- preflight: در ابتدای فرایند نصب صدا زده می‌شود 

- install، update، uninstall: در میانه فرایند نصب فراخوانی می‌شوند، به ترتیب برای نصب اولیه، به‌روزرسانی و حذف افزونه 

- postflight: در انتهای فرایند نصب اجرا می‌شود 

ابتدا بهتر است درباره روند نصب در جوملا مطالعه کنید تا درک بهتری از جایگاه فایل اسکریپت در روند کلی نصب پیدا کنید.

تعریف فایل اسکریپت 

ساده‌ترین روش نوشتن فایل اسکریپت استفاده از اینترفیس \Joomla\CMS\Installer\InstallerScriptInterface است که در مسیر libraries/src/Installer/InstallerScriptInterface.php تعریف شده است. 

شما باید یک نمونه از کلاسی که این ۵ تابع را پیاده‌سازی می‌کند، برگردانید. نام کلاس اهمیت ندارد، بنابراین می‌توان از کلاس ناشناس استفاده کرد، مانند نمونه زیر: 

<?php
defined('_JEXEC') or die;
use Joomla\CMS\Factory;
use Joomla\CMS\Installer\InstallerAdapter;
use Joomla\CMS\Installer\InstallerScriptInterface;
use Joomla\CMS\Language\Text;
return new class () implements InstallerScriptInterface {
    private string $minimumJoomla = '4.4.0';
    private string $minimumPhp    = '7.4.0';
    public function install(InstallerAdapter $adapter): bool
    {
        echo "mod_hello install<br>";
        return true;
    }
    public function update(InstallerAdapter $adapter): bool
    {
        echo "mod_hello update<br>";
        return true;
    }
    public function uninstall(InstallerAdapter $adapter): bool
    {
        echo "mod_hello uninstall<br>";
        return true;
    }
    public function preflight(string $type, InstallerAdapter $adapter): bool
    {
        echo "mod_hello preflight<br>";    
        if (version_compare(PHP_VERSION, $this->minimumPhp, '<')) {
            Factory::getApplication()->enqueueMessage(sprintf(Text::_('JLIB_INSTALLER_MINIMUM_PHP'), $this->minimumPhp), 'error');
            return false;
        }
        if (version_compare(JVERSION, $this->minimumJoomla, '<')) {
            Factory::getApplication()->enqueueMessage(sprintf(Text::_('JLIB_INSTALLER_MINIMUM_JOOMLA'), $this->minimumJoomla), 'error');
            return false;
        }
        return true;
    }
    public function postflight(string $type, InstallerAdapter $adapter): bool
    {
        echo "mod_hello postflight<br>";
        return true;
    }
}

توضیحات بیشتر درباره توابع 

- پارامتر `$type` رشته‌ای است که نوع نصب را مشخص می‌کند: 'install'، 'update' یا 'uninstall'. (ممکن است مقدار 'discover-install' هم باشد که خارج از حوزه این آموزش است.) 

- پارامتر `adapter` نمونه‌ای از \Joomla\CMS\Installer\Adapter\ModuleAdapter است.

نکات مهم 

- در برخی توابع، صرفاً متنی برای نمایش (echo) می‌زنیم که در صورت موفقیت آمیز بودن نصب، روی صفحه نمایش داده می‌شود. این متن‌ها به زبان انگلیسی هستند ولی می‌توانید از رشته‌های زبان (.sys.ini) برای ترجمه استفاده کنید. 

- تابع preflight نسخه‌های PHP و جوملا را بررسی می‌کند؛ این مهم است چون کد mod_hello از APIهایی استفاده می‌کند که قبل از جوملا نسخه ۴ در دسترس نبوده‌اند. 

- اگر نصب با خطا مواجه شود (برای مثال چک نسخه انجام نشود)، جوملا درخواست HTTP را به صفحه نصب افزونه‌ها هدایت (redirect) می‌کند، بنابراین خروجی‌های echo دیده نمی‌شوند. در این مواقع باید پیام‌ها را با استفاده از `enqueueMessage` ارسال کرد. این تابع پیام را در جلسه ذخیره می‌کند و جوملا پس از پاسخ تغییر مسیر، پیام را در پاسخ به درخواست HTTP بعدی نمایش می‌دهد.

فایل مانیفست (Manifest File) 

تنها کاری که باقی مانده، به‌روزرسانی فایل مانیفست است تا به جوملا اطلاع دهیم یک فایل اسکریپت نصب (script file) داریم که باید هنگام نصب، به‌روزرسانی یا حذف ماژول اجرا شود: 

مسیر: mod_hello/mod_hello.xml 

<?xml version="1.0" encoding="UTF-8"?>
<extension type="module" client="site" method="upgrade">
    <name>MOD_HELLO_NAME</name>
    <version>1.0.6</version>
    <author>me</author>
    <creationDate>today</creationDate>
    <description>MOD_HELLO_DESCRIPTION</description>
    <namespace path="src">My\Module\Hello</namespace>
    <files>
        <folder module="mod_hello">services</folder>
        <folder>src</folder>
        <folder>tmpl</folder>
        <folder>language</folder>
    </files>
    <scriptfile>script.php</scriptfile>  <!-- این خط اضافه شده -->
    <config>
        <fields name="params">
            <fieldset name="basic">
                <field
                    name="header"
                    type="list"
                    label="MOD_HELLO_HEADER_LEVEL"
                    default="h4"
                    >
                    <option value="h3">MOD_HELLO_HEADER_LEVEL_3</option>
                    <option value="h4">MOD_HELLO_HEADER_LEVEL_4</option>
                    <option value="h5">MOD_HELLO_HEADER_LEVEL_5</option>
                    <option value="h6">MOD_HELLO_HEADER_LEVEL_6</option>
                </field>
            </fieldset>
        </fields>
    </config>
</extension>

نکته مهم 

خط `<scriptfile>script.php</scriptfile>` به مانیفست اضافه شده تا جوملا بداند هنگام نصب یا حذف ماژول، باید فایل `script.php` را اجرا کند.