GithubModuleUpdate.php

<?php

/**
 * webtrees: online genealogy
 * Copyright (C) 2025 webtrees development team
 *                    <http://webtrees.net>
 *
 * CustomModuleManager (webtrees custom module):
 * Copyright (C) 2025 Markus Hemprich
 *                    <http://www.familienforschung-hemprich.de>
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <https://www.gnu.org/licenses/>.
 *
 * 
 * CustomModuleManager
 *
 * A weebtrees(https://webtrees.net) 2.2 custom module to manage custom modules
 * 
 */

declare(strict_types=1);

namespace Jefferson49\Webtrees\Module\CustomModuleManager\ModuleUpdates;

use Fisharebest\Webtrees\FlashMessages;
use Fisharebest\Webtrees\I18N;
use Fisharebest\Webtrees\Module\ModuleInterface;
use Fisharebest\Webtrees\Services\ModuleService;
use Jefferson49\Webtrees\Exceptions\GithubCommunicationError;
use Jefferson49\Webtrees\Helpers\GithubService;
use Jefferson49\Webtrees\Module\CustomModuleManager\CustomModuleManager;
use Jefferson49\Webtrees\Module\CustomModuleManager\Exceptions\CustomModuleManagerException;


/**
 * Update API for a custom module, which is hosted in a Github repository
 */
class GithubModuleUpdate extends AbstractModuleUpdate implements CustomModuleUpdateInterface 
{#
    const NAME = 'GitHub';

    //The Github repository of the module, e.g. Jefferson49/CustomModuleManager
    protected string $github_repo;

    //Whether we shall get the latest version from Github instead from the module itself
    protected bool $get_latest_version_from_github;

    //A tag prefix for the module version, e.g. 'v' ('1.2.3' => 'v1.2.3')
    protected string $tag_prefix;

    //Whether the Github repository does not have a release
    protected bool $no_release;

    //The default branch of the Github repository. Used to download the source ZIP file for some modules, which do not provide a release
    protected string $default_branch;

    // The module service
    protected ModuleService $module_service;

    // The Custom Module Manager module
    protected ModuleInterface $custom_module_manager;
    
    /**
     * @param string $module_name  The custom module name
     * @param array  $params       The configuration parameters of the update service
     * 
     * @return void
     */
    public function __construct(string $module_name, array $params) {

        $this->module_name           = $module_name;
        $this->module_service        = new ModuleService();
        $this->custom_module_manager = $this->module_service->findByName(CustomModuleManager::activeModuleName());


        if (array_key_exists('github_repo', $params)) {
            $this->github_repo = $params['github_repo'];
        }
        else {
            throw new CustomModuleManagerException(I18N::translate('Could not create the %s update service. Configuration parameter "%s" missing.', basename(str_replace('\\', '/', __CLASS__)) , 'github_repo'));
        }

        if (array_key_exists('get_latest_version_from_github', $params)) {
            $this->get_latest_version_from_github = $params['get_latest_version_from_github'];
        }
        else {
            $this->get_latest_version_from_github = false;
        }

        if (array_key_exists('tag_prefix', $params)) {
            $this->tag_prefix = $params['tag_prefix'];
        }
        else {
            $this->tag_prefix = '';
        }

        if (array_key_exists('no_release', $params)) {
            $this->no_release = $params['no_release'];
        }
        else {
            $this->no_release = false;
        }

        if (array_key_exists('default_branch', $params)) {
            $this->default_branch = $params['default_branch'];
        }
        else {
            $this->default_branch = '';
        }

        $this->category = self::identifyCategoryFromConfig($module_name, $params);
    }

    /**
     * The name of the module update service
     *
     * @return string
     */
    public function name(): string {

        return self::NAME;
    }

    /**
     * Where can we download the module
     * 
     * @param  string $version  The version of the module; latest version if empty
     * 
     * @return string
     */
    public function downloadUrl(string $version = ''): string
    {
        $download_url = '';

        //For certain modules, which do not provide a release, we take the URL of the source code ZIP file of the default branch
        if ($this->no_release) {
            return 'https://github.com/' . $this->github_repo . '/archive/refs/heads/' . $this->default_branch . '.zip';
        }

        $github_api_token = $this->custom_module_manager->getPreference(CustomModuleManager::PREF_GITHUB_API_TOKEN, '');       

        // Get the download URL from Github
        try {
            $download_url = GithubService::downloadUrl($this->github_repo, $version, $this->tag_prefix, $github_api_token);
        } 
        catch (GithubCommunicationError $ex) {
            // Can't connect to GitHub?
            $message =  I18N::translate('Communication error with %s', $this->name()) . ': ' . 
                        I18N::translate('Cannot retrieve download URL.') . "\n" .
                        $ex->getMessage();
            throw new CustomModuleManagerException($message);
        }

        return $download_url;
    }

    /**
     * Where can we find a documentation for the module
     * 
     * @return string
     */
    public function documentationUrl(): string
    {
        return 'https://github.com/'. $this->github_repo;
    }

    /**
     * Get the GitHub repository
     * 
     * @return string
     */
    public function getGithubRepo(): string
    {
        return $this->github_repo;
    }

    /**
     * Fetch the latest version of this module
     *
     * @param bool $fetch_latest  Whether to fetch the latest version, e.g. from a GitHub repository 
     * 
     * @return string
     */
    public function customModuleLatestVersion(bool $fetch_latest = false): string
    {
        $latest_version = '';
        $stored_version = '';
        $module = $this->getModule();

        // If the installed module is available, try to get latest version from the module
        if ($module !== null && !$fetch_latest && !$this->get_latest_version_from_github) {

            $latest_version = $module->customModuleLatestVersion();
            $short_module_name = substr($module->name(), 0, 25) . '_';
            $stored_version = $this->custom_module_manager->getPreference($short_module_name . CustomModuleManager::PREF_LATEST_VERSION, '');

            // If we had retrieved and stored a later version before
            if (CustomModuleManager::versionCompare($module->name(), $stored_version, $latest_version) > 0) {
                $latest_version = $stored_version;
            }
        }

        // For certain modules, which do not provide a release, try to get the latest version by update URL
        if ($latest_version === '' && $module !== null && $this->no_release) {

            $latest_version =  self::getLatestVersionByUpdateURL($module);
        }
        // Otherwise, try to get the latest version from Github
        elseif ($latest_version === '' && $this->github_repo !== '') {

            $github_api_token = $this->custom_module_manager->getPreference(CustomModuleManager::PREF_GITHUB_API_TOKEN, '');       

            try {
                $latest_version = GithubService::getLatestReleaseTag($this->github_repo, $github_api_token);
            }
            catch (GithubCommunicationError $ex) {
                // Can't connect to GitHub? 
                    if (!CustomModuleManager::rememberGithubCommunciationError()) {
                    FlashMessages::addMessage(I18N::translate('Communication error with %s', self::NAME), 'danger');
                }
            }
        }

        if ($module !== null) {
            $short_module_name = substr($module->name(), 0, 25) . '_';

            // If a later version was retrieved, store it 
            if (CustomModuleManager::versionCompare($module->name(), $latest_version, $this->customModuleVersion()) > 0) {

                $this->custom_module_manager->setPreference($short_module_name . CustomModuleManager::PREF_LATEST_VERSION, $latest_version);
            }
            // Otherwise, reset stored version
            elseif ($stored_version !== '') {
                $this->custom_module_manager->setPreference($short_module_name . CustomModuleManager::PREF_LATEST_VERSION, '');
            } 
        }

        return $latest_version;
    }

    /**
     * Get the release notes for the latest version of this module
     *
     * @return string
     */
    public function getLatestReleaseNotes(): string
    {
        $github_api_token = $this->custom_module_manager->getPreference(CustomModuleManager::PREF_GITHUB_API_TOKEN, '');       

        //Get the latest releases note from GitHub
        try {
            return GithubService::getLatestReleaseNotes($this->github_repo, $github_api_token);
        }
        catch (GithubCommunicationError $ex) {
            // Can't connect to GitHub?
            return I18N::translate('Could not retrieve release notes due to a communication error with GitHub.');
        }
    }

    /**
     * Whether the module provides releases in the repository
     *
     * @return bool
     */
    public function providesReleasesInRepository(): bool {
        return !$this->no_release;
    }

    /**
     * Get the cached download count for this module.
     * 
     * Fetches the maximum download count across the latest 3 releases' assets.
     * The result is cached for 24 hours using module preferences to avoid hitting 
     * GitHub API rate limits on every page load.
     *
     * @return int  The download count, or -1 if unavailable
     */
    public function getDownloadCount(): int
    {
        $short_module_name = substr($this->module_name, 0, 25) . '_';
        $cache_key = $short_module_name . CustomModuleManager::PREF_DOWNLOAD_COUNT;
        $cache_time_key = $short_module_name . CustomModuleManager::PREF_DOWNLOAD_COUNT_TIME;

        // Check if we have a cached value that is less than 24 hours old
        $cached_time = (int) $this->custom_module_manager->getPreference($cache_time_key, '0');
        $cached_count = $this->custom_module_manager->getPreference($cache_key, '');

        if ($cached_count !== '' && (time() - $cached_time) < 86400) {
            return (int) $cached_count;
        }

        // If the module does not provide releases, we cannot get download counts
        if ($this->no_release) {
            return -1;
        }

        $github_api_token = $this->custom_module_manager->getPreference(CustomModuleManager::PREF_GITHUB_API_TOKEN, '');

        try {
            $download_count = GithubService::getRecentReleasesMaxDownloads($this->github_repo, $github_api_token);

            // Cache the result
            $this->custom_module_manager->setPreference($cache_key, (string) $download_count);
            $this->custom_module_manager->setPreference($cache_time_key, (string) time());

            return $download_count;
        } catch (GithubCommunicationError $ex) {
            // If we have a stale cached value, return it rather than nothing
            if ($cached_count !== '') {
                return (int) $cached_count;
            }

            if (!CustomModuleManager::rememberGithubCommunciationError()) {
                FlashMessages::addMessage(I18N::translate('Communication error with %s', self::NAME), 'danger');
            }

            return -1;
        }
    }

    /**
     * Get the latest release URL
     *
     * @return string
     */
    public function getLatestReleaseURL(): string {

        return 'https://github.com/' . $this->github_repo . '/releases/latest';
    }
}