Template-Joomla/samples/script/script_package.php

<?php
/**
 * ============================================================================
 * INSTRUCTIONS FOR USE:
 * 1. This file template serves as the standard structure for all script files
 * across the extension repositories. Copy and implement this pattern 
 * universally in every script file to maintain consistency.
 * 2. Replace '{REPONAME}' with the actual name of the repo (UPPERCASE).
 * Example: "MOKOSUITEBACKUP"
 * 3. Replace '{PACKAGENAME}' with the Joomla extension element name (lowercase).
 * Example: "pkg_mokosuitebackup", "com_mokosuitebackup", "mod_mokosuitebackup"
 * ============================================================================
 */

/**
 * @package     Joomla.Installer
 * @subpackage  {PACKAGENAME}
 */

use Joomla\CMS\Factory;
use Joomla\CMS\Log\Log;

defined('_JEXEC') || die;

class {REPONAME}InstallerScript
{
    /**
     * @var string  The saved download key cached during preflight to survive updates
     */
    private $savedDownloadKey = '';

    /**
     * Preflight hook runs before any installation/update/uninstallation action.
     */
    public function preflight($type, $parent): bool
    {
        if ($type === 'update') {
            $this->backupDownloadKey();
        }

        return true;
    }

    /**
     * Postflight hook runs after any installation/update/uninstallation action.
     */
    public function postflight($type, $parent): void
    {
        if ($type === 'install') {
            $this->installSuccessful();
            $this->warnMissingLicenseKey();
        }

        if ($type === 'update') {
            $this->restoreDownloadKey();
            $this->installSuccessful();
        }
    }

    public function install($parent): void {}
    public function update($parent): void {}
    public function uninstall($parent): void {}

    /**
     * Cache the existing download key from the update sites table before update runs.
     */
    private function backupDownloadKey(): void
    {
        try {
            $db    = Factory::getDbo();
            $query = $db->getQuery(true)
                ->select($db->quoteName('us.extra_query'))
                ->from($db->quoteName('#__update_sites', 'us'))
                ->join(
                    'INNER',
                    $db->quoteName('#__update_sites_extensions', 'use')
                    . ' ON ' . $db->quoteName('use.update_site_id') . ' = ' . $db->quoteName('us.update_site_id')
                )
                ->join(
                    'INNER',
                    $db->quoteName('#__extensions', 'e')
                    . ' ON ' . $db->quoteName('e.extension_id') . ' = ' . $db->quoteName('use.extension_id')
                )
                ->where($db->quoteName('e.element') . ' = ' . $db->quote('{PACKAGENAME}'))
                ->where($db->quoteName('e.type') . ' = ' . $db->quote('package'))
                ->setLimit(1);

            $db->setQuery($query);
            $extraQuery = (string) $db->loadResult();

            if (!empty($extraQuery)) {
                parse_str($extraQuery, $output);
                $this->savedDownloadKey = $output['dlid'] ?? $extraQuery;
            }
        } catch (\Exception $e) {
            Log::add('{REPONAME}: Could not backup download key: ' . $e->getMessage(), Log::WARNING, 'jerror');
        }
    }

    /**
     * Restore the download key to the (possibly new) update site record.
     */
    private function restoreDownloadKey(): void
    {
        try {
            $db    = Factory::getDbo();
            $query = $db->getQuery(true)
                ->select($db->quoteName('us.update_site_id'))
                ->from($db->quoteName('#__update_sites', 'us'))
                ->join(
                    'INNER',
                    $db->quoteName('#__update_sites_extensions', 'use')
                    . ' ON ' . $db->quoteName('use.update_site_id') . ' = ' . $db->quoteName('us.update_site_id')
                )
                ->join(
                    'INNER',
                    $db->quoteName('#__extensions', 'e')
                    . ' ON ' . $db->quoteName('e.extension_id') . ' = ' . $db->quoteName('use.extension_id')
                )
                ->where($db->quoteName('e.element') . ' = ' . $db->quote('{PACKAGENAME}'))
                ->where($db->quoteName('e.type') . ' = ' . $db->quote('package'))
                ->setLimit(1);
            
            $db->setQuery($query);
            $updateSiteId = (int) $db->loadResult();

            if ($updateSiteId > 0 && !empty($this->savedDownloadKey)) {
                $query = $db->getQuery(true)
                    ->update($db->quoteName('#__update_sites'))
                    ->set($db->quoteName('extra_query') . ' = ' . $db->quote('dlid=' . $this->savedDownloadKey))
                    ->where($db->quoteName('update_site_id') . ' = ' . $updateSiteId);
                
                $db->setQuery($query);
                $db->execute();
            }
        } catch (\Exception $e) {
            Log::add('{REPONAME}: Could not restore download key: ' . $e->getMessage(), Log::WARNING, 'jerror');
            
            Factory::getApplication()->enqueueMessage(
                '<h4>{REPONAME}</h4>'
                    . '<p>Your download/license key could not be preserved during the update.</p>'
                    . '<p>Please re-enter it in the <a class="btn btn-sm btn-warning ms-2" href="index.php?option=com_installer&view=updatesites&filter[search]={PACKAGENAME}">Update Sites</a> manager to continue receiving updates.</p>',
                'warning'
            );
        }
    }

    /**
     * Show post-install license key prompt
     */
    private function warnMissingLicenseKey(): void
    {
        try {
            Factory::getApplication()->enqueueMessage(
                '<h4>{REPONAME} License Key Required</h4>'
                    . '<p>A download/license key (DLID) is required to receive updates.</p>'
                    . '<p>Enter your key in the <a class="btn btn-sm btn-warning ms-2" href="index.php?option=com_installer&view=updatesites&filter[search]={PACKAGENAME}">Update Sites</a> manager '
                    . 'or contact <a class="btn btn-sm btn-warning ms-2" href="https://mokoconsulting.tech/support" target="_blank" rel="noopener">Moko Consulting Support</a> to obtain one.</p>',
                'warning'
            );
        } catch (\Exception $e) {}
    }

    /**
     * Show install successful prompt
     */
    private function installSuccessful(): void
    {
        try {
            Factory::getApplication()->enqueueMessage(
                '<h4>{REPONAME} installed successfully!</h4>',
                'info'
            );
        } catch (\Exception $e) {}
    }
}